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
28class KUrl;
29
30namespace KParts
31{
32
33class ReadOnlyPart;
34class HtmlExtensionPrivate;
35class 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 */
45class KPARTS_EXPORT HtmlExtension : public QObject
46{
47 Q_OBJECT
48public:
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
74private:
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 */
89class KPARTS_EXPORT SelectorInterface
90{
91public:
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&lt;KParts::HtmlSettingsInterface&gt;(extension);
240 * const bool autoLoadImages = settings->attribute(KParts::AutoLoadImages);
241 * </code>
242 *
243 * @since 4.8.1
244 */
245class KPARTS_EXPORT HtmlSettingsInterface
246{
247public:
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
381inline void qSwap( KParts::SelectorInterface::Element & lhs, KParts::SelectorInterface::Element & rhs )
382{
383 lhs.swap( rhs );
384}
385
386Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::SelectorInterface::QueryMethods)
387
388Q_DECLARE_TYPEINFO(KParts::SelectorInterface::Element, Q_MOVABLE_TYPE);
389
390Q_DECLARE_INTERFACE(KParts::SelectorInterface,
391 "org.kde.KParts.SelectorInterface")
392Q_DECLARE_INTERFACE(KParts::HtmlSettingsInterface,
393 "org.kde.KParts.HtmlSettingsInterface")
394
395
396#endif /* KPARTS_HTMLEXTENSION_H */
397