KParts

selectorinterface.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2010 David Faure <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KPARTS_SELECTORINTERFACE_H
9 #define KPARTS_SELECTORINTERFACE_H
10 
11 #include <kparts/kparts_export.h>
12 
13 #include <QObject>
14 #include <QSharedDataPointer>
15 #include <QStringList>
16 
17 class QString;
18 template<typename T>
19 class QList;
20 
21 namespace KParts
22 {
23 /**
24  * @class SelectorInterface selectorinterface.h <KParts/SelectorInterface>
25  *
26  * @short Optional base class for HtmlExtension-derived classes
27  * Provides DOM Selector like API: querySelector and querySelectorAll,
28  * in order to find specific elements in an HTML document.
29  *
30  * Example:
31  * @code
32  * const QList<SelectorInterface::Element> elements = selectorInterface->querySelectorAll("head > link[rel=\"alternate\"]");
33  * @endcode
34  */
35 class KPARTS_EXPORT SelectorInterface
36 {
37 public:
38  class ElementPrivate;
39  class Element;
40 
41  /**
42  * Query methods.
43  * @see QueryMethods
44  */
45  enum QueryMethod {
46  None = 0x00, /*!< Querying is not possible. */
47  EntireContent = 0x01, /*!< Query or can query the entire content. */
48  SelectedContent = 0x02, /*!< Query or can query only the user selected content, if any. */
49  };
50  /**
51  * Stores a combination of #QueryMethod values.
52  */
53  Q_DECLARE_FLAGS(QueryMethods, QueryMethod)
54 
55  /**
56  * Destructor
57  */
58  virtual ~SelectorInterface()
59  {
60  }
61 
62  /**
63  * Returns the supported query methods.
64  *
65  * By default this function returns None.
66  *
67  * @see QueryMethod
68  */
69  virtual QueryMethods supportedQueryMethods() const;
70 
71  /**
72  * Returns the first (in document order) element in this fragment matching
73  * the given CSS selector @p query and querying method @p method.
74  *
75  * Note that since the returned item is static snapshot, i.e. not live, it
76  * will not be updated when the document changes.
77  *
78  * If the querying method specified by @p method is not supported or cannot be
79  * handled, then a null element is returned.
80  *
81  * @see supportedQueryMethods
82  * @see QueryMethod
83  */
84  virtual Element querySelector(const QString &query, QueryMethod method) const = 0;
85 
86  /**
87  * Returns all (in document order) elements in this fragment matching the
88  * given CSS selector @p query and querying method @p method.
89  *
90  * Note that since the returned list is static snapshot, i.e. not live, it
91  * will not be updated when the document changes.
92  *
93  * If the querying method specified by @p method is not supported or cannot be
94  * handled, then an empty list is returned.
95  *
96  * @see supportedQueryMethods
97  * @see QueryMethod
98  */
99  virtual QList<Element> querySelectorAll(const QString &query, QueryMethod method) const = 0;
100 
101  class KPARTS_EXPORT Element
102  {
103  public:
104  /**
105  * Constructor
106  */
107  Element();
108 
109  /**
110  * Copy constructor
111  */
112  Element(const Element &other);
113 
114  /**
115  * Destructor
116  */
117  ~Element();
118 
119  /**
120  * Returns true if the element is null ; otherwise returns false.
121  */
122  bool isNull() const;
123 
124  /**
125  * Sets the tag name of this element.
126  */
127  void setTagName(const QString &tag);
128 
129  /**
130  * Returns the tag name of this element.
131  */
132  QString tagName() const;
133 
134  /**
135  * Adds an attribute with the given name and value.
136  * If an attribute with the same name exists, its value is replaced by value.
137  */
138  void setAttribute(const QString &name, const QString &value);
139 
140  /**
141  * Returns the list of attributes in this element.
142  */
143  QStringList attributeNames() const;
144 
145  /**
146  * Returns the attribute with the given name. If the attribute does not exist, defaultValue is returned.
147  */
148  QString attribute(const QString &name, const QString &defaultValue = QString()) const;
149 
150  /**
151  * Returns true if the attribute with the given @p name exists.
152  */
153  bool hasAttribute(const QString &name) const;
154 
155  // No namespace support yet, could be added with attributeNS, setAttributeNS
156 
157  /**
158  * Swaps the contents of @p other with the contents of this.
159  */
160  void swap(Element &other)
161  {
162  d.swap(other.d);
163  }
164 
165  /**
166  * Assignment operator
167  */
168  Element &operator=(const Element &other)
169  {
170  if (this != &other) {
171  Element copy(other);
172  swap(copy);
173  }
174  return *this;
175  }
176 
177  private:
179  };
180 };
181 
182 Q_DECLARE_OPERATORS_FOR_FLAGS(SelectorInterface::QueryMethods)
183 
184 } // namespace KParts
185 
186 inline void qSwap(KParts::SelectorInterface::Element &lhs, KParts::SelectorInterface::Element &rhs)
187 {
188  lhs.swap(rhs);
189 }
190 
191 Q_DECLARE_TYPEINFO(KParts::SelectorInterface::Element, Q_MOVABLE_TYPE);
192 
193 Q_DECLARE_INTERFACE(KParts::SelectorInterface, "org.kde.KParts.SelectorInterface")
194 
195 #endif /* KPARTS_SELECTORINTERFACE_H */
QFlags< QueryMethod > QueryMethods
Stores a combination of QueryMethod values.
Optional base class for HtmlExtension-derived classes Provides DOM Selector like API: querySelector a...
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 9 2022 03:51:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.