KParts

browserextension.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1999 Simon Hausmann <[email protected]>
4  SPDX-FileCopyrightText: 1999 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef __kparts_browserextension_h__
10 #define __kparts_browserextension_h__
11 
12 #include <kparts/browserarguments.h>
13 #include <kparts/openurlarguments.h>
14 #include <kparts/readonlypart.h>
15 #include <kparts/windowargs.h>
16 
17 #include <memory>
18 
19 #include <QAction>
20 #include <qplatformdefs.h> //mode_t
21 
22 template<class Key, class T>
23 class QMap;
24 template<typename T>
25 class QList;
26 
27 class KFileItem;
28 class KFileItemList;
29 class QDataStream;
30 class QPoint;
31 
32 namespace KParts
33 {
34 class BrowserInterface;
35 
36 /**
37  * @class BrowserExtension browserextension.h <KParts/BrowserExtension>
38  *
39  * @short The Browser Extension is an extension (yes, no kidding) to
40  * KParts::ReadOnlyPart, which allows a better integration of parts
41  * with browsers (in particular Konqueror).
42  *
43  * Remember that ReadOnlyPart only has openUrl(QUrl) and a few arguments() but not much more.
44  * For full-fledged browsing, we need much more than that, including
45  * enabling/disabling of standard actions (print, copy, paste...),
46  * allowing parts to save and restore their data into the back/forward history,
47  * allowing parts to control the location bar URL, to requests URLs
48  * to be opened by the hosting browser, etc.
49  *
50  * The part developer needs to define its own class derived from BrowserExtension,
51  * to implement the virtual methods [and the standard-actions slots, see below].
52  *
53  * The way to associate the BrowserExtension with the part is to simply
54  * create the BrowserExtension as a child of the part (in QObject's terms).
55  * The hosting application will look for it automatically.
56  *
57  * Another aspect of the browser integration is that a set of standard
58  * actions are provided by the browser, but implemented by the part
59  * (for the actions it supports).
60  *
61  * The following standard actions are defined by the host of the view:
62  *
63  * [selection-dependent actions]
64  * @li @p cut : Copy selected items to clipboard and store 'not cut' in clipboard.
65  * @li @p copy : Copy selected items to clipboard and store 'cut' in clipboard.
66  * @li @p paste : Paste clipboard into view URL.
67  * @li @p pasteTo(const QUrl &) : Paste clipboard into given URL.
68  * @li @p searchProvider : Lookup selected text at default search provider
69  *
70  * [normal actions]
71  * @li None anymore.
72  *
73  *
74  * The view defines a slot with the name of the action in order to implement the action.
75  * The browser will detect the slot automatically and connect its action to it when
76  * appropriate (i.e. when the view is active).
77  *
78  *
79  * The selection-dependent actions are disabled by default and the view should
80  * enable them when the selection changes, emitting enableAction().
81  *
82  * The normal actions do not depend on the selection.
83  *
84  * A special case is the configuration slots, not connected to any action directly.
85  *
86  * [configuration slot]
87  * @li @p reparseConfiguration : Re-read configuration and apply it.
88  * @li @p disableScrolling: no scrollbars
89  */
90 class KPARTS_EXPORT BrowserExtension : public QObject // TODO KF6, rename class and header to NavigationExtension. See https://phabricator.kde.org/T12224
91 {
92  Q_OBJECT
93  Q_PROPERTY(bool urlDropHandling READ isURLDropHandlingEnabled WRITE setURLDropHandlingEnabled)
94 public:
95  /**
96  * Constructor
97  *
98  * @param parent The KParts::ReadOnlyPart that this extension ... "extends" :)
99  */
100  explicit BrowserExtension(KParts::ReadOnlyPart *parent);
101 
102  virtual ~BrowserExtension();
103 
104  /**
105  * Set of flags passed via the popupMenu signal, to ask for some items in the popup menu.
106  * @see PopupFlags
107  */
108  enum PopupFlag {
109  DefaultPopupItems = 0x0000, /**< default value, no additional menu item */
110 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 27)
111  ShowNavigationItems KPARTS_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 27, "No effect anymore") =
112  0x0001, /**< @deprecated since 5.27, no effect anymore */
113  ShowUp KPARTS_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 27, "No effect anymore") = 0x0002, /**< @deprecated since 5.27, no effect anymore */
114  ShowReload KPARTS_ENUMERATOR_DEPRECATED_VERSION_BELATED(5, 82, 5, 27, "No effect anymore") = 0x0004, /**< @deprecated since 5.27, no effect anymore */
115 #endif
116  ShowBookmark = 0x0008, /**< show "add to bookmarks" (usually not done on the local filesystem) */
117  ShowCreateDirectory = 0x0010, /**< show "create directory" (usually only done on the background of the view, or
118  * in hierarchical views like directory trees, where the new dir would be visible) */
119  ShowTextSelectionItems = 0x0020, /**< set when selecting text, for a popup that only contains text-related items. */
120  NoDeletion = 0x0040, /**< deletion, trashing and renaming not allowed (e.g. parent dir not writeable).
121  * (this is only needed if the protocol itself supports deletion, unlike e.g. HTTP) */
122  IsLink = 0x0080, /**< show "Bookmark This Link" and other link-related actions (linkactions merging group) */
123  ShowUrlOperations = 0x0100, /**< show copy, paste, as well as cut if NoDeletion is not set. */
124  ShowProperties = 0x200, /**< show "Properties" action (usually done by directory views) */
125  };
126 
127  /**
128  * Stores a combination of #PopupFlag values.
129  */
130  Q_DECLARE_FLAGS(PopupFlags, PopupFlag)
131 
132  /**
133  * Set the parameters to use for opening the next URL.
134  * This is called by the "hosting" application, to pass parameters to the part.
135  * @see BrowserArguments
136  */
137  virtual void setBrowserArguments(const BrowserArguments &args);
138 
139  /**
140  * Retrieve the set of parameters to use for opening the URL
141  * (this must be called from openUrl() in the part).
142  * @see BrowserArguments
143  */
144  BrowserArguments browserArguments() const;
145 
146  /**
147  * Returns the current x offset.
148  *
149  * For a scrollview, implement this using contentsX().
150  */
151  virtual int xOffset();
152  /**
153  * Returns the current y offset.
154  *
155  * For a scrollview, implement this using contentsY().
156  */
157  virtual int yOffset();
158 
159  /**
160  * Used by the browser to save the current state of the view
161  * (in order to restore it if going back in navigation).
162  *
163  * If you want to save additional properties, reimplement it
164  * but don't forget to call the parent method (probably first).
165  */
166  virtual void saveState(QDataStream &stream);
167 
168  /**
169  * Used by the browser to restore the view in the state
170  * it was when we left it.
171  *
172  * If you saved additional properties, reimplement it
173  * but don't forget to call the parent method (probably first).
174  */
175  virtual void restoreState(QDataStream &stream);
176 
177  /**
178  * Returns whether url drop handling is enabled.
179  * See setURLDropHandlingEnabled for more information about this
180  * property.
181  */
182  bool isURLDropHandlingEnabled() const;
183 
184  /**
185  * Enables or disables url drop handling. URL drop handling is a property
186  * describing whether the hosting shell component is allowed to install an
187  * event filter on the part's widget, to listen for URI drop events.
188  * Set it to true if you are exporting a BrowserExtension implementation and
189  * do not provide any special URI drop handling. If set to false you can be
190  * sure to receive all those URI drop events unfiltered. Also note that the
191  * implementation as of Konqueror installs the event filter only on the part's
192  * widget itself, not on child widgets.
193  */
194  void setURLDropHandlingEnabled(bool enable);
195 
196  void setBrowserInterface(BrowserInterface *impl);
197  BrowserInterface *browserInterface() const;
198 
199  /**
200  * @return the status (enabled/disabled) of an action.
201  * When the enableAction signal is emitted, the browserextension
202  * stores the status of the action internally, so that it's possible
203  * to query later for the status of the action, using this method.
204  */
205  bool isActionEnabled(const char *name) const;
206 
207  /**
208  * @return the text of an action, if it was set explicitly by the part.
209  * When the setActionText signal is emitted, the browserextension
210  * stores the text of the action internally, so that it's possible
211  * to query later for the text of the action, using this method.
212  */
213  QString actionText(const char *name) const;
214 
215  typedef QMap<QByteArray, QByteArray> ActionSlotMap;
216 
217 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 83)
218  /**
219  * Returns a map containing the action names as keys and corresponding
220  * SLOT()'ified method names as data entries.
221  *
222  * This is very useful for
223  * the host component, when connecting the own signals with the
224  * extension's slots.
225  * Basically you iterate over the map, check if the extension implements
226  * the slot and connect to the slot using the data value of your map
227  * iterator.
228  * Checking if the extension implements a certain slot can be done like this:
229  *
230  * \code
231  * extension->metaObject()->slotNames().contains( actionName + "()" )
232  * \endcode
233  *
234  * (note that @p actionName is the iterator's key value if already
235  * iterating over the action slot map, returned by this method)
236  *
237  * Connecting to the slot can be done like this:
238  *
239  * \code
240  * connect( yourObject, SIGNAL( yourSignal() ),
241  * extension, mapIterator.data() )
242  * \endcode
243  *
244  * (where "mapIterator" is your ActionSlotMap iterator)
245  */
246  KPARTS_DEPRECATED_VERSION(5, 83, "Use actionSlotMapPtr instead")
247  static ActionSlotMap actionSlotMap();
248 #endif
249 
250  /**
251  * @return a pointer to the static action-slot map. Preferred method to get it.
252  * The map is created if it doesn't exist yet
253  */
254  static ActionSlotMap *actionSlotMapPtr(); // TODO KF6 Rename to actionSlotMap
255 
256  /**
257  * Queries @p obj for a child object which inherits from this
258  * BrowserExtension class. Convenience method.
259  */
260  static BrowserExtension *childObject(QObject *obj);
261 
262  /**
263  * Asks the hosting browser to perform a paste (using openUrlRequestDelayed())
264  */
265  void pasteRequest();
266 
267  /**
268  * Associates a list of actions with a predefined name known by the host's popupmenu:
269  * "editactions" for actions related text editing,
270  * "linkactions" for actions related to hyperlinks,
271  * "partactions" for any other actions provided by the part
272  */
274 
275 Q_SIGNALS:
276  /**
277  * Enables or disable a standard action held by the browser.
278  *
279  * See class documentation for the list of standard actions.
280  */
281  void enableAction(const char *name, bool enabled);
282 
283  /**
284  * Change the text of a standard action held by the browser.
285  * This can be used to change "Paste" into "Paste Image" for instance.
286  *
287  * See class documentation for the list of standard actions.
288  */
289  void setActionText(const char *name, const QString &text);
290 
291  /**
292  * Asks the host (browser) to open @p url.
293  * To set a reload, the x and y offsets, the service type etc., fill in the
294  * appropriate fields in the @p args structure.
295  * Hosts should not connect to this signal but to openUrlRequestDelayed().
296  */
297  void openUrlRequest(const QUrl &url,
299  const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments());
300 
301  /**
302  * This signal is emitted when openUrlRequest() is called, after a 0-seconds timer.
303  * This allows the caller to terminate what it's doing first, before (usually)
304  * being destroyed. Parts should never use this signal, hosts should only connect
305  * to this signal.
306  */
307  void openUrlRequestDelayed(const QUrl &url, const KParts::OpenUrlArguments &arguments, const KParts::BrowserArguments &browserArguments);
308 
309  /**
310  * Tells the hosting browser that the part opened a new URL (which can be
311  * queried via KParts::Part::url().
312  *
313  * This helps the browser to update/create an entry in the history.
314  * The part may @em not emit this signal together with openUrlRequest().
315  * Emit openUrlRequest() if you want the browser to handle a URL the user
316  * asked to open (from within your part/document). This signal however is
317  * useful if you want to handle URLs all yourself internally, while still
318  * telling the hosting browser about new opened URLs, in order to provide
319  * a proper history functionality to the user.
320  * An example of usage is a html rendering component which wants to emit
321  * this signal when a child frame document changed its URL.
322  * Conclusion: you probably want to use openUrlRequest() instead.
323  */
324  void openUrlNotify();
325 
326  /**
327  * Updates the URL shown in the browser's location bar to @p url.
328  */
329  void setLocationBarUrl(const QString &url);
330 
331  /**
332  * Sets the URL of an icon for the currently displayed page.
333  */
334  void setIconUrl(const QUrl &url);
335 
336  /**
337  * Asks the hosting browser to open a new window for the given @p url
338  * and return a reference to the content part.
339  *
340  * @p arguments is optional additional information about how to open the url,
341  * @see KParts::OpenUrlArguments
342  *
343  * @p browserArguments is optional additional information for web browsers,
344  * @see KParts::BrowserArguments
345  *
346  * The request for a pointer to the part is only fulfilled/processed
347  * if the mimeType is set in the @p browserArguments.
348  * (otherwise the request cannot be processed synchronously).
349  */
350  void createNewWindow(const QUrl &url,
352  const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments(),
353  const KParts::WindowArgs &windowArgs = KParts::WindowArgs(),
354  KParts::ReadOnlyPart **part = nullptr); // TODO consider moving to BrowserHostExtension?
355 
356  /**
357  * Since the part emits the jobid in the started() signal,
358  * progress information is automatically displayed.
359  *
360  * However, if you don't use a KIO::Job in the part,
361  * you can use loadingProgress() and speedProgress()
362  * to display progress information.
363  */
364  void loadingProgress(int percent);
365  /**
366  * @see loadingProgress
367  */
368  void speedProgress(int bytesPerSecond);
369 
370  void infoMessage(const QString &);
371 
372  /**
373  * Emit this to make the browser show a standard popup menu for the files @p items.
374  *
375  * @param global global coordinates where the popup should be shown
376  * @param items list of file items which the popup applies to
377  * @param args OpenUrlArguments, mostly for metadata here
378  * @param browserArguments BrowserArguments, mostly for referrer
379  * @param flags enables/disables certain builtin actions in the popupmenu
380  * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap
381  */
382  void popupMenu(const QPoint &global,
383  const KFileItemList &items,
385  const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments(),
387  const KParts::BrowserExtension::ActionGroupMap &actionGroups = ActionGroupMap());
388 
389  /**
390  * Emit this to make the browser show a standard popup menu for the given @p url.
391  *
392  * Give as much information about this URL as possible,
393  * like @p args.mimeType and the file type @p mode
394  *
395  * @param global global coordinates where the popup should be shown
396  * @param url the URL this popup applies to
397  * @param mode the file type of the url (S_IFREG, S_IFDIR...)
398  * @param args OpenUrlArguments, set the mimetype of the URL using setMimeType()
399  * @param browserArguments BrowserArguments, mostly for referrer
400  * @param flags enables/disables certain builtin actions in the popupmenu
401  * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap
402  */
403  void popupMenu(const QPoint &global,
404  const QUrl &url,
405  mode_t mode = static_cast<mode_t>(-1),
407  const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments(),
409  const KParts::BrowserExtension::ActionGroupMap &actionGroups = ActionGroupMap());
410 
411  /**
412  * Inform the hosting application about the current selection.
413  * Used when a set of files/URLs is selected (with full information
414  * about those URLs, including size, permissions etc.)
415  */
416  void selectionInfo(const KFileItemList &items);
417 
418 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 88)
419  /**
420  * Inform the hosting application about the current selection.
421  * Used when some text is selected.
422  * @deprecated Since 5.88, deprecated for lack of usage
423  */
424  KPARTS_DEPRECATED_VERSION(5, 88, "Deprecated for lack of usage")
425  void selectionInfo(const QString &text);
426 #endif
427 
428 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 88)
429  /**
430  * Inform the hosting application about the current selection.
431  * Used when a set of URLs is selected.
432  * @deprecated Since 5.88, use selectionInfo(KFileItemList) instead
433  */
434  KPARTS_DEPRECATED_VERSION(5, 88, "Use selectionInfo(KFileItemList) instead")
435  void selectionInfo(const QList<QUrl> &urls);
436 #endif
437 
438  /**
439  * Inform the hosting application that the user moved the mouse over an item.
440  * Used when the mouse is on an URL.
441  */
442  void mouseOverInfo(const KFileItem &item);
443 
444  /**
445  * Ask the hosting application to add a new HTML (aka Mozilla/Netscape)
446  * SideBar entry.
447  */
448  void addWebSideBar(const QUrl &url, const QString &name);
449 
450  /**
451  * Ask the hosting application to move the top level widget.
452  */
453  void moveTopLevelWidget(int x, int y);
454 
455  /**
456  * Ask the hosting application to resize the top level widget.
457  */
458  void resizeTopLevelWidget(int w, int h);
459 
460  /**
461  * Ask the hosting application to focus @p part.
462  */
463  void requestFocus(KParts::ReadOnlyPart *part);
464 
465  /**
466  * Tell the host (browser) about security state of current page
467  * enum PageSecurity { NotCrypted, Encrypted, Mixed };
468  */
469  void setPageSecurity(int);
470 
471  /**
472  * Inform the host about items that have been removed.
473  */
474  void itemsRemoved(const KFileItemList &items);
475 
476 private Q_SLOTS:
477  void slotCompleted();
478  void slotOpenUrlRequest(const QUrl &url,
480  const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments());
481 
482  void slotEmitOpenUrlRequestDelayed();
483  void slotEnableAction(const char *, bool);
484  void slotSetActionText(const char *, const QString &);
485 
486 public:
488 
489 private:
490  std::unique_ptr<class BrowserExtensionPrivate> const d;
491 };
492 
493 Q_DECLARE_OPERATORS_FOR_FLAGS(BrowserExtension::PopupFlags)
494 
495 }
496 
497 #endif
The Browser Extension is an extension (yes, no kidding) to KParts::ReadOnlyPart, which allows a bette...
The purpose of this interface is to allow a direct communication between a KPart and the hosting brow...
BrowserArguments is a set of web-browsing-specific arguments, which allow specifying how a URL should...
default value, no additional menu item
QMap< QString, QList< QAction * > > ActionGroupMap
Associates a list of actions with a predefined name known by the host&#39;s popupmenu: "editactions" for ...
PopupFlag
Set of flags passed via the popupMenu signal, to ask for some items in the popup menu.
The KParts namespace,.
The WindowArgs are used to specify arguments to the "create new window" call (see the createNewWindow...
Definition: windowargs.h:29
OpenUrlArguments is the set of arguments that specify how a URL should be opened by KParts::ReadOnlyP...
Base class for any "viewer" part.
Definition: readonlypart.h:51
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Oct 19 2021 22:56:36 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.