File indexing completed on 2024-05-12 07:51:58
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0004 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef KPARTS_NAVIGATIONEXTENSION 0010 #define KPARTS_NAVIGATIONEXTENSION 0011 0012 #include <kparts/openurlarguments.h> 0013 #include <kparts/readonlypart.h> 0014 0015 #include <memory> 0016 0017 #include <QAction> 0018 #include <qplatformdefs.h> //mode_t 0019 0020 template<class Key, class T> 0021 class QMap; 0022 template<typename T> 0023 class QList; 0024 0025 class KFileItem; 0026 class KFileItemList; 0027 class QDataStream; 0028 class QPoint; 0029 0030 namespace KParts 0031 { 0032 class NavigationExtensionPrivate; 0033 0034 /** 0035 * @class NavigationExtension navigationextension.h <KParts/NavigationExtension> 0036 * 0037 * @short An extension to KParts::ReadOnlyPart, which allows a better integration of parts 0038 * with browsers (in particular Konqueror). 0039 * 0040 * Remember that ReadOnlyPart only has openUrl(QUrl) and a few arguments() but not much more. 0041 * For full-fledged browsing, we need much more than that, including 0042 * enabling/disabling of standard actions (print, copy, paste...), 0043 * allowing parts to save and restore their data into the back/forward history, 0044 * allowing parts to control the location bar URL, to requests URLs 0045 * to be opened by the hosting browser, etc. 0046 * 0047 * The part developer needs to define its own class derived from BrowserExtension, 0048 * to implement the virtual methods [and the standard-actions slots, see below]. 0049 * 0050 * The way to associate the BrowserExtension with the part is to simply 0051 * create the BrowserExtension as a child of the part (in QObject's terms). 0052 * The hosting application will look for it automatically. 0053 * 0054 * Another aspect of the browser integration is that a set of standard 0055 * actions are provided by the browser, but implemented by the part 0056 * (for the actions it supports). 0057 * 0058 * The following standard actions are defined by the host of the view: 0059 * 0060 * [selection-dependent actions] 0061 * @li @p cut : Copy selected items to clipboard and store 'not cut' in clipboard. 0062 * @li @p copy : Copy selected items to clipboard and store 'cut' in clipboard. 0063 * @li @p paste : Paste clipboard into view URL. 0064 * @li @p pasteTo(const QUrl &) : Paste clipboard into given URL. 0065 * @li @p searchProvider : Lookup selected text at default search provider 0066 * 0067 * [normal actions] 0068 * @li None anymore. 0069 * 0070 * 0071 * The view defines a slot with the name of the action in order to implement the action. 0072 * The browser will detect the slot automatically and connect its action to it when 0073 * appropriate (i.e. when the view is active). 0074 * 0075 * 0076 * The selection-dependent actions are disabled by default and the view should 0077 * enable them when the selection changes, emitting enableAction(). 0078 * 0079 * The normal actions do not depend on the selection. 0080 * 0081 * A special case is the configuration slots, not connected to any action directly. 0082 * 0083 * [configuration slot] 0084 * @li @p reparseConfiguration : Re-read configuration and apply it. 0085 * @li @p disableScrolling: no scrollbars 0086 */ 0087 class KPARTS_EXPORT NavigationExtension : public QObject 0088 { 0089 Q_OBJECT 0090 Q_PROPERTY(bool urlDropHandling READ isURLDropHandlingEnabled WRITE setURLDropHandlingEnabled) 0091 public: 0092 /** 0093 * Constructor 0094 * 0095 * @param parent The KParts::ReadOnlyPart that this extension ... "extends" :) 0096 */ 0097 explicit NavigationExtension(KParts::ReadOnlyPart *parent); 0098 0099 ~NavigationExtension() override; 0100 0101 /** 0102 * Set of flags passed via the popupMenu signal, to ask for some items in the popup menu. 0103 * @see PopupFlags 0104 */ 0105 enum PopupFlag { 0106 DefaultPopupItems = 0x0000, /**< default value, no additional menu item */ 0107 ShowBookmark = 0x0008, /**< show "add to bookmarks" (usually not done on the local filesystem) */ 0108 ShowCreateDirectory = 0x0010, /**< show "create directory" (usually only done on the background of the view, or 0109 * in hierarchical views like directory trees, where the new dir would be visible) */ 0110 ShowTextSelectionItems = 0x0020, /**< set when selecting text, for a popup that only contains text-related items. */ 0111 NoDeletion = 0x0040, /**< deletion, trashing and renaming not allowed (e.g. parent dir not writeable). 0112 * (this is only needed if the protocol itself supports deletion, unlike e.g. HTTP) */ 0113 IsLink = 0x0080, /**< show "Bookmark This Link" and other link-related actions (linkactions merging group) */ 0114 ShowUrlOperations = 0x0100, /**< show copy, paste, as well as cut if NoDeletion is not set. */ 0115 ShowProperties = 0x200, /**< show "Properties" action (usually done by directory views) */ 0116 }; 0117 0118 /** 0119 * Stores a combination of #PopupFlag values. 0120 */ 0121 Q_DECLARE_FLAGS(PopupFlags, PopupFlag) 0122 0123 /** 0124 * Returns the current x offset. 0125 * 0126 * For a scrollview, implement this using contentsX(). 0127 */ 0128 virtual int xOffset(); 0129 /** 0130 * Returns the current y offset. 0131 * 0132 * For a scrollview, implement this using contentsY(). 0133 */ 0134 virtual int yOffset(); 0135 0136 /** 0137 * Used by the browser to save the current state of the view 0138 * (in order to restore it if going back in navigation). 0139 * 0140 * If you want to save additional properties, reimplement it 0141 * but don't forget to call the parent method (probably first). 0142 */ 0143 virtual void saveState(QDataStream &stream); 0144 0145 /** 0146 * Used by the browser to restore the view in the state 0147 * it was when we left it. 0148 * 0149 * If you saved additional properties, reimplement it 0150 * but don't forget to call the parent method (probably first). 0151 */ 0152 virtual void restoreState(QDataStream &stream); 0153 0154 /** 0155 * Returns whether url drop handling is enabled. 0156 * See setURLDropHandlingEnabled for more information about this 0157 * property. 0158 */ 0159 bool isURLDropHandlingEnabled() const; 0160 0161 /** 0162 * Enables or disables url drop handling. URL drop handling is a property 0163 * describing whether the hosting shell component is allowed to install an 0164 * event filter on the part's widget, to listen for URI drop events. 0165 * Set it to true if you are exporting a BrowserExtension implementation and 0166 * do not provide any special URI drop handling. If set to false you can be 0167 * sure to receive all those URI drop events unfiltered. Also note that the 0168 * implementation as of Konqueror installs the event filter only on the part's 0169 * widget itself, not on child widgets. 0170 */ 0171 void setURLDropHandlingEnabled(bool enable); 0172 0173 /** 0174 * @return the status (enabled/disabled) of an action. 0175 * When the enableAction signal is emitted, the browserextension 0176 * stores the status of the action internally, so that it's possible 0177 * to query later for the status of the action, using this method. 0178 */ 0179 bool isActionEnabled(const char *name) const; 0180 0181 /** 0182 * @return the text of an action, if it was set explicitly by the part. 0183 * When the setActionText signal is emitted, the browserextension 0184 * stores the text of the action internally, so that it's possible 0185 * to query later for the text of the action, using this method. 0186 */ 0187 QString actionText(const char *name) const; 0188 0189 typedef QMap<QByteArray, QByteArray> ActionSlotMap; 0190 0191 /** 0192 * Returns a pointer to the static map containing the action names as keys and corresponding 0193 * SLOT()'ified method names as data entries. 0194 * The map is created if it doesn't exist yet. 0195 * 0196 * This is very useful for 0197 * the host component, when connecting the own signals with the 0198 * extension's slots. 0199 * Basically you iterate over the map, check if the extension implements 0200 * the slot and connect to the slot using the data value of your map 0201 * iterator. 0202 * Checking if the extension implements a certain slot can be done like this: 0203 * 0204 * \code 0205 * extension->metaObject()->slotNames().contains( actionName + "()" ) 0206 * \endcode 0207 * 0208 * (note that @p actionName is the iterator's key value if already 0209 * iterating over the action slot map, returned by this method) 0210 * 0211 * Connecting to the slot can be done like this: 0212 * 0213 * \code 0214 * connect( yourObject, SIGNAL( yourSignal() ), 0215 * extension, mapIterator.data() ) 0216 * \endcode 0217 * 0218 * (where "mapIterator" is your ActionSlotMap iterator) 0219 */ 0220 static ActionSlotMap *actionSlotMap(); 0221 0222 /** 0223 * Queries @p obj for a child object which inherits from this 0224 * BrowserExtension class. Convenience method. 0225 */ 0226 static NavigationExtension *childObject(QObject *obj); 0227 0228 /** 0229 * Asks the hosting browser to perform a paste (using openUrlRequestDelayed()) 0230 */ 0231 void pasteRequest(); 0232 0233 /** 0234 * Associates a list of actions with a predefined name known by the host's popupmenu: 0235 * "editactions" for actions related text editing, 0236 * "linkactions" for actions related to hyperlinks, 0237 * "partactions" for any other actions provided by the part 0238 */ 0239 typedef QMap<QString, QList<QAction *>> ActionGroupMap; 0240 0241 Q_SIGNALS: 0242 /** 0243 * Enables or disable a standard action held by the browser. 0244 * 0245 * See class documentation for the list of standard actions. 0246 */ 0247 void enableAction(const char *name, bool enabled); 0248 0249 /** 0250 * Change the text of a standard action held by the browser. 0251 * This can be used to change "Paste" into "Paste Image" for instance. 0252 * 0253 * See class documentation for the list of standard actions. 0254 */ 0255 void setActionText(const char *name, const QString &text); 0256 0257 /** 0258 * Asks the host (browser) to open @p url. 0259 * To set a reload, the x and y offsets, the service type etc., fill in the 0260 * appropriate fields in the @p args structure. 0261 * Hosts should not connect to this signal but to openUrlRequestDelayed(). 0262 */ 0263 void openUrlRequest(const QUrl &url, const KParts::OpenUrlArguments &arguments = KParts::OpenUrlArguments()); 0264 0265 /** 0266 * This signal is emitted when openUrlRequest() is called, after a 0-seconds timer. 0267 * This allows the caller to terminate what it's doing first, before (usually) 0268 * being destroyed. Parts should never use this signal, hosts should only connect 0269 * to this signal. 0270 */ 0271 void openUrlRequestDelayed(const QUrl &url, const KParts::OpenUrlArguments &arguments); 0272 0273 /** 0274 * Tells the hosting browser that the part opened a new URL (which can be 0275 * queried via KParts::Part::url(). 0276 * 0277 * This helps the browser to update/create an entry in the history. 0278 * The part may @em not emit this signal together with openUrlRequest(). 0279 * Emit openUrlRequest() if you want the browser to handle a URL the user 0280 * asked to open (from within your part/document). This signal however is 0281 * useful if you want to handle URLs all yourself internally, while still 0282 * telling the hosting browser about new opened URLs, in order to provide 0283 * a proper history functionality to the user. 0284 * An example of usage is a html rendering component which wants to emit 0285 * this signal when a child frame document changed its URL. 0286 * Conclusion: you probably want to use openUrlRequest() instead. 0287 */ 0288 void openUrlNotify(); 0289 0290 /** 0291 * Updates the URL shown in the browser's location bar to @p url. 0292 */ 0293 void setLocationBarUrl(const QString &url); 0294 0295 /** 0296 * Sets the URL of an icon for the currently displayed page. 0297 */ 0298 void setIconUrl(const QUrl &url); 0299 0300 /** 0301 * Asks the hosting browser to open a new window for the given @p url 0302 * and return a reference to the content part. 0303 */ 0304 void createNewWindow(const QUrl &url); 0305 0306 /** 0307 * Since the part emits the jobid in the started() signal, 0308 * progress information is automatically displayed. 0309 * 0310 * However, if you don't use a KIO::Job in the part, 0311 * you can use loadingProgress() and speedProgress() 0312 * to display progress information. 0313 */ 0314 void loadingProgress(int percent); 0315 /** 0316 * @see loadingProgress 0317 */ 0318 void speedProgress(int bytesPerSecond); 0319 0320 void infoMessage(const QString &); 0321 0322 /** 0323 * Emit this to make the browser show a standard popup menu for the files @p items. 0324 * 0325 * @param global global coordinates where the popup should be shown 0326 * @param items list of file items which the popup applies to 0327 * @param args OpenUrlArguments, mostly for metadata here 0328 * @param flags enables/disables certain builtin actions in the popupmenu 0329 * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap 0330 */ 0331 void popupMenu(const QPoint &global, 0332 const KFileItemList &items, 0333 const KParts::OpenUrlArguments &arguments = KParts::OpenUrlArguments(), 0334 KParts::NavigationExtension::PopupFlags flags = KParts::NavigationExtension::DefaultPopupItems, 0335 const KParts::NavigationExtension::ActionGroupMap &actionGroups = ActionGroupMap()); 0336 0337 /** 0338 * Emit this to make the browser show a standard popup menu for the given @p url. 0339 * 0340 * Give as much information about this URL as possible, 0341 * like @p args.mimeType and the file type @p mode 0342 * 0343 * @param global global coordinates where the popup should be shown 0344 * @param url the URL this popup applies to 0345 * @param mode the file type of the url (S_IFREG, S_IFDIR...) 0346 * @param args OpenUrlArguments, set the mimetype of the URL using setMimeType() 0347 * @param flags enables/disables certain builtin actions in the popupmenu 0348 * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap 0349 */ 0350 void popupMenu(const QPoint &global, 0351 const QUrl &url, 0352 mode_t mode = static_cast<mode_t>(-1), 0353 const KParts::OpenUrlArguments &arguments = KParts::OpenUrlArguments(), 0354 KParts::NavigationExtension::PopupFlags flags = KParts::NavigationExtension::DefaultPopupItems, 0355 const KParts::NavigationExtension::ActionGroupMap &actionGroups = ActionGroupMap()); 0356 0357 /** 0358 * Inform the hosting application about the current selection. 0359 * Used when a set of files/URLs is selected (with full information 0360 * about those URLs, including size, permissions etc.) 0361 */ 0362 void selectionInfo(const KFileItemList &items); 0363 0364 /** 0365 * Inform the hosting application that the user moved the mouse over an item. 0366 * Used when the mouse is on an URL. 0367 */ 0368 void mouseOverInfo(const KFileItem &item); 0369 0370 /** 0371 * Ask the hosting application to add a new HTML (aka Mozilla/Netscape) 0372 * SideBar entry. 0373 */ 0374 void addWebSideBar(const QUrl &url, const QString &name); 0375 0376 /** 0377 * Ask the hosting application to move the top level widget. 0378 */ 0379 void moveTopLevelWidget(int x, int y); 0380 0381 /** 0382 * Ask the hosting application to resize the top level widget. 0383 */ 0384 void resizeTopLevelWidget(int w, int h); 0385 0386 /** 0387 * Ask the hosting application to focus @p part. 0388 */ 0389 void requestFocus(KParts::ReadOnlyPart *part); 0390 0391 /** 0392 * Tell the host (browser) about security state of current page 0393 * enum PageSecurity { NotCrypted, Encrypted, Mixed }; 0394 */ 0395 void setPageSecurity(int); 0396 0397 /** 0398 * Inform the host about items that have been removed. 0399 */ 0400 void itemsRemoved(const KFileItemList &items); 0401 0402 private Q_SLOTS: 0403 KPARTS_NO_EXPORT void slotOpenUrlRequest(const QUrl &url, const KParts::OpenUrlArguments &arguments = KParts::OpenUrlArguments()); 0404 0405 KPARTS_NO_EXPORT void slotEmitOpenUrlRequestDelayed(); 0406 KPARTS_NO_EXPORT void slotEnableAction(const char *, bool); 0407 KPARTS_NO_EXPORT void slotSetActionText(const char *, const QString &); 0408 0409 public: 0410 typedef QMap<QByteArray, int> ActionNumberMap; 0411 0412 private: 0413 std::unique_ptr<NavigationExtensionPrivate> const d; 0414 }; 0415 0416 Q_DECLARE_OPERATORS_FOR_FLAGS(NavigationExtension::PopupFlags) 0417 0418 } 0419 0420 #endif