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

source code of kparts/src/navigationextension.h