1 | /* This file is part of the KDE project |
2 | Copyright (C) 2010 David Faure <faure@kde.org> |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef KPARTS_HTMLEXTENSION_H |
21 | #define KPARTS_HTMLEXTENSION_H |
22 | |
23 | #include <QtCore/QSharedDataPointer> |
24 | #include <QtCore/QObject> |
25 | |
26 | #include <kparts/kparts_export.h> |
27 | |
28 | class KUrl; |
29 | |
30 | namespace KParts |
31 | { |
32 | |
33 | class ReadOnlyPart; |
34 | class HtmlExtensionPrivate; |
35 | class SelectorInterfacePrivate; |
36 | |
37 | /** |
38 | * @short an extension for KParts to provide HTML-related features |
39 | * |
40 | * Use qobject_cast to cast the extension to interesting interfaces, like |
41 | * qobject_cast<KParts::SelectorInterface>. |
42 | * |
43 | * @since 4.6 |
44 | */ |
45 | class KPARTS_EXPORT HtmlExtension : public QObject |
46 | { |
47 | Q_OBJECT |
48 | public: |
49 | HtmlExtension(KParts::ReadOnlyPart* parent); |
50 | ~HtmlExtension(); |
51 | |
52 | /** |
53 | * Queries @p obj for a child object which inherits from this |
54 | * HtmlExtension class. |
55 | */ |
56 | static HtmlExtension *childObject( QObject *obj ); |
57 | |
58 | /** |
59 | * Returns the current base url of the part that implements this extension. |
60 | * |
61 | * This function is mostly used to resolve any relative URLs that might be |
62 | * returned when querying the part for links. |
63 | */ |
64 | virtual KUrl baseUrl() const = 0; |
65 | |
66 | /** |
67 | * Returns true if portions of the content in the part that implements |
68 | * this extension are selected. |
69 | * |
70 | * By default this function returns false. |
71 | */ |
72 | virtual bool hasSelection() const; |
73 | |
74 | private: |
75 | // for future extensions |
76 | HtmlExtensionPrivate* const d; |
77 | }; |
78 | |
79 | /** |
80 | * Optional base class for HtmlExtension-derived classes |
81 | * Provides DOM Selector like API: querySelector and querySelectorAll, |
82 | * in order to find specific elements in an HTML document. |
83 | * |
84 | * Example: |
85 | * <code> |
86 | * const QList<SelectorInterface::Element> elements = selectorInterface->querySelectorAll("head > link[rel=\"alternate\"]"); |
87 | * </code> |
88 | */ |
89 | class KPARTS_EXPORT SelectorInterface |
90 | { |
91 | public: |
92 | class ElementPrivate; |
93 | class Element; |
94 | |
95 | /** |
96 | * Query methods. |
97 | */ |
98 | enum QueryMethod { |
99 | None = 0x00, /*!< Quering is not possible. */ |
100 | EntireContent = 0x01, /*!< Query or can query the entire content. */ |
101 | SelectedContent = 0x02 /*!< Query or can query only the user selected content, if any. */ |
102 | }; |
103 | Q_DECLARE_FLAGS(QueryMethods, QueryMethod) |
104 | |
105 | /** |
106 | * Destructor |
107 | */ |
108 | virtual ~SelectorInterface() {} |
109 | |
110 | /** |
111 | * Returns the supported query methods. |
112 | * |
113 | * By default this function returns None. |
114 | * |
115 | * @see QueryMethod |
116 | */ |
117 | virtual QueryMethods supportedQueryMethods() const; |
118 | |
119 | /** |
120 | * Returns the first (in document order) element in this fragment matching |
121 | * the given CSS selector @p query and querying method @p method. |
122 | * |
123 | * Note that since the returned item is static snapshot, i.e. not live, it |
124 | * will not be updated when the document changes. |
125 | * |
126 | * If the quering method specified by @p method is not supported or cannot be |
127 | * handled, then a null element is returned. |
128 | * |
129 | * @see supportedQueryMethods |
130 | * @see QueryMethod |
131 | */ |
132 | virtual Element querySelector(const QString& query, QueryMethod method) const = 0; |
133 | |
134 | /** |
135 | * Returns all (in document order) elements in this fragment matching the |
136 | * given CSS selector @p query and querying method @p method. |
137 | * |
138 | * Note that since the returned list is static snapshot, i.e. not live, it |
139 | * will not be updated when the document changes. |
140 | * |
141 | * If the quering method specified by @p method is not supported or cannot be |
142 | * handled, then an empty list is returned. |
143 | * |
144 | * @see supportedQueryMethods |
145 | * @see QueryMethod |
146 | */ |
147 | virtual QList<Element> querySelectorAll(const QString& query, QueryMethod method) const = 0; |
148 | |
149 | class KPARTS_EXPORT Element { |
150 | public: |
151 | /** |
152 | * Constructor |
153 | */ |
154 | Element(); |
155 | |
156 | /** |
157 | * Copy constructor |
158 | */ |
159 | Element(const Element& other); |
160 | |
161 | /** |
162 | * Destructor |
163 | */ |
164 | ~Element(); |
165 | |
166 | /** |
167 | * Returns true if the element is null ; otherwise returns false. |
168 | */ |
169 | bool isNull() const; |
170 | |
171 | /** |
172 | * Sets the tag name of this element. |
173 | */ |
174 | void setTagName(const QString& tag); |
175 | |
176 | /** |
177 | * Returns the tag name of this element. |
178 | */ |
179 | QString tagName() const; |
180 | |
181 | /** |
182 | * Adds an attribute with the given name and value. |
183 | * If an attribute with the same name exists, its value is replaced by value. |
184 | */ |
185 | void setAttribute(const QString& name, const QString& value); |
186 | |
187 | /** |
188 | * Returns the list of attributes in this element. |
189 | */ |
190 | QStringList attributeNames() const; |
191 | |
192 | /** |
193 | * Returns the attribute with the given name. If the attribute does not exist, defaultValue is returned. |
194 | */ |
195 | QString attribute(const QString& name, const QString& defaultValue = QString()) const; |
196 | |
197 | /** |
198 | * Returns true if the attribute with the given @p name exists. |
199 | */ |
200 | bool hasAttribute(const QString& name) const; |
201 | |
202 | // No namespace support yet, could be added with attributeNS, setAttributeNS |
203 | |
204 | /** |
205 | * Swaps the contents of @p other with the contents of this. |
206 | */ |
207 | void swap( Element& other ) { |
208 | d.swap( other.d ); |
209 | } |
210 | |
211 | /** |
212 | * Assignment operator |
213 | */ |
214 | Element& operator=(const Element& other) { |
215 | if ( this != &other ) { |
216 | Element copy( other ); |
217 | swap( copy ); |
218 | } |
219 | return *this; |
220 | } |
221 | |
222 | private: |
223 | QSharedDataPointer<ElementPrivate> d; |
224 | }; |
225 | }; |
226 | |
227 | /** |
228 | * @short An interface for modifying the settings of browser engines. |
229 | * |
230 | * This interface provides a generic means for querying or changing the |
231 | * settings of browser engines that implement it. |
232 | * |
233 | * To use this class simply cast an instance of the HTMLExtension object |
234 | * using qobject_cast<KParts::HtmlSettingsInterface>. |
235 | * |
236 | * Example: |
237 | * <code> |
238 | * KParts::HTMLExtension* extension = KParts::HTMLExtension::childObject(part); |
239 | * KParts::HtmlSettingsInterface* settings = qobject_cast<KParts::HtmlSettingsInterface>(extension); |
240 | * const bool autoLoadImages = settings->attribute(KParts::AutoLoadImages); |
241 | * </code> |
242 | * |
243 | * @since 4.8.1 |
244 | */ |
245 | class KPARTS_EXPORT HtmlSettingsInterface |
246 | { |
247 | public: |
248 | /** |
249 | * Settings attribute types. |
250 | */ |
251 | enum HtmlSettingsType { |
252 | AutoLoadImages, |
253 | DnsPrefetchEnabled, |
254 | JavaEnabled, |
255 | JavascriptEnabled, |
256 | MetaRefreshEnabled, |
257 | PluginsEnabled, |
258 | PrivateBrowsingEnabled, |
259 | OfflineStorageDatabaseEnabled, |
260 | OfflineWebApplicationCacheEnabled, |
261 | LocalStorageEnabled, |
262 | UserDefinedStyleSheetURL |
263 | }; |
264 | |
265 | /** |
266 | * This enum specifies whether Java/JavaScript execution is allowed. |
267 | * |
268 | * @since 4.8.2 |
269 | */ |
270 | enum JavaScriptAdvice { |
271 | JavaScriptDunno=0, |
272 | JavaScriptAccept, |
273 | JavaScriptReject |
274 | }; |
275 | |
276 | /** |
277 | * This enum specifies the policy for window.open |
278 | * |
279 | * @since 4.8.2 |
280 | */ |
281 | enum JSWindowOpenPolicy { |
282 | JSWindowOpenAllow=0, |
283 | JSWindowOpenAsk, |
284 | JSWindowOpenDeny, |
285 | JSWindowOpenSmart |
286 | }; |
287 | |
288 | /** |
289 | * This enum specifies the policy for window.status and .defaultStatus |
290 | * |
291 | * @since 4.8.2 |
292 | */ |
293 | enum JSWindowStatusPolicy { |
294 | JSWindowStatusAllow=0, |
295 | JSWindowStatusIgnore |
296 | }; |
297 | |
298 | /** |
299 | * This enum specifies the policy for window.moveBy and .moveTo |
300 | * |
301 | * @since 4.8.2 |
302 | */ |
303 | enum JSWindowMovePolicy { |
304 | JSWindowMoveAllow=0, |
305 | JSWindowMoveIgnore |
306 | }; |
307 | |
308 | /** |
309 | * This enum specifies the policy for window.resizeBy and .resizeTo |
310 | * |
311 | * @since 4.8.2 |
312 | */ |
313 | enum JSWindowResizePolicy { |
314 | JSWindowResizeAllow=0, |
315 | JSWindowResizeIgnore |
316 | }; |
317 | |
318 | /** |
319 | * This enum specifies the policy for window.focus |
320 | * |
321 | * @since 4.8.2 |
322 | */ |
323 | enum JSWindowFocusPolicy { |
324 | JSWindowFocusAllow=0, |
325 | JSWindowFocusIgnore |
326 | }; |
327 | |
328 | /** |
329 | * Destructor |
330 | */ |
331 | virtual ~HtmlSettingsInterface() {} |
332 | |
333 | /** |
334 | * Returns the value of the browser engine's attribute @p type. |
335 | */ |
336 | virtual QVariant htmlSettingsProperty(HtmlSettingsType type) const = 0; |
337 | |
338 | /** |
339 | * Sets the value of the browser engine's attribute @p type to @p value. |
340 | */ |
341 | virtual bool setHtmlSettingsProperty(HtmlSettingsType type, const QVariant& value) = 0; |
342 | |
343 | /** |
344 | * A convenience function that returns the javascript advice for @p text. |
345 | * |
346 | * If text is not either "accept" or "reject", this function returns |
347 | * @ref JavaScriptDunno. |
348 | * |
349 | * @since 4.8.2 |
350 | */ |
351 | static JavaScriptAdvice textToJavascriptAdvice(const QString& text); |
352 | |
353 | /** |
354 | * A convenience function Returns the text for the given JavascriptAdvice @p advice. |
355 | * |
356 | * If @p advice is not either JavaScriptAccept or JavaScriptReject, this |
357 | * function returns a NULL string. |
358 | * |
359 | * @since 4.8.2 |
360 | */ |
361 | static const char* javascriptAdviceToText(JavaScriptAdvice advice); |
362 | |
363 | /** |
364 | * A convenience function that splits @p text into @p domain, @p javaAdvice |
365 | * and @p jScriptAdvice. |
366 | * |
367 | * If @p text is empty or does not contain the proper delimiter (':'), this |
368 | * function will set @p domain to @p text and the other two parameters to |
369 | * JavaScriptDunno. |
370 | * |
371 | * @since 4.8.2 |
372 | */ |
373 | static void splitDomainAdvice(const QString& text, |
374 | QString& domain, |
375 | JavaScriptAdvice& javaAdvice, |
376 | JavaScriptAdvice& javaScriptAdvice); |
377 | }; |
378 | |
379 | } // namespace KParts |
380 | |
381 | inline void qSwap( KParts::SelectorInterface::Element & lhs, KParts::SelectorInterface::Element & rhs ) |
382 | { |
383 | lhs.swap( rhs ); |
384 | } |
385 | |
386 | Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::SelectorInterface::QueryMethods) |
387 | |
388 | Q_DECLARE_TYPEINFO(KParts::SelectorInterface::Element, Q_MOVABLE_TYPE); |
389 | |
390 | Q_DECLARE_INTERFACE(KParts::SelectorInterface, |
391 | "org.kde.KParts.SelectorInterface" ) |
392 | Q_DECLARE_INTERFACE(KParts::HtmlSettingsInterface, |
393 | "org.kde.KParts.HtmlSettingsInterface" ) |
394 | |
395 | |
396 | #endif /* KPARTS_HTMLEXTENSION_H */ |
397 | |