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

source code of kparts/src/navigationextension.h