kparts/browserextension.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
   3                       David Faure <faure@kde.org>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License as published by the Free Software Foundation; either
   8    version 2 of the License, or (at your option) any later version.
   9
  10    This library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Library General Public License for more details.
  14
  15    You should have received a copy of the GNU Library General Public License
  16    along with this library; see the file COPYING.LIB.  If not, write to
  17    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18    Boston, MA 02110-1301, USA.
  19 */
  20
  21 #ifndef __kparts_browserextension_h__
  22 #define __kparts_browserextension_h__
  23
  24 #include <sys/types.h>
  25
  26 #include <kparts/part.h>
  27 #include <kparts/event.h>
  28
  29 #include <QtCore/QSharedDataPointer>
  30
  31 template <class T1, class T2> struct QPair;
  32 template<typename T> class Q3PtrList;
  33 template <class Key, class T> class QMap;
  34 template<typename T> class QList;
  35
  36 class KFileItem;
  37 class KFileItemList;
  38 class QDataStream;
  39 class QPoint;
  40 class QString;
  41 class QStringList;
  42
  43 namespace KParts {
  44
  45 class BrowserInterface;
  46
  47 struct BrowserArgumentsPrivate;
  48
  49 /**
  50  * BrowserArguments is a set of web-browsing-specific arguments,
  51  * which allow specifying how a URL should be opened by openUrl()
  52  * (as a complement to KParts::OpenUrlArguments which are the non-web-specific arguments)
  53  *
  54  * The arguments remain stored in the browser extension after that,
  55  * and can be used for instance to jump to the xOffset/yOffset position
  56  * once the url has finished loading.
  57  *
  58  * The parts (with a browser extension) who care about urlargs will
  59  * use those arguments, others will ignore them.
  60  *
  61  * This can also be used the other way round, when a part asks
  62  * for a URL to be opened (with openUrlRequest or createNewWindow).
  63  */
  64 struct KPARTS_EXPORT BrowserArguments
  65 {
  66   BrowserArguments();
  67   BrowserArguments( const BrowserArguments &args );
  68   BrowserArguments &operator=( const BrowserArguments &args);
  69
  70   virtual ~BrowserArguments();
  71
  72   // KDE4: a struct has the problem that the stuff added after BC-freeze uses methods
  73   // so it looks inconsistent with the member vars. -> better use methods for everything,
  74   // even if they are inline.
  75
  76
  77   /**
  78    * This buffer can be used by the part to save and restore its contents.
  79    * See KHTMLPart for instance.
  80    */
  81   QStringList docState;
  82
  83   /**
  84    * @p softReload is set when user just hits reload button. It's used
  85    * currently for two different frameset reload strategies. In case of
  86    * soft reload individual frames are reloaded instead of reloading whole
  87    * frameset.
  88    */
  89   bool softReload;
  90
  91   /**
  92    * KHTML-specific field, contents of the HTTP POST data.
  93    */
  94   QByteArray postData;
  95
  96   /**
  97    * KHTML-specific field, header defining the type of the POST data.
  98    */
  99   void setContentType( const QString & contentType );
 100   /**
 101    * KHTML-specific field, header defining the type of the POST data.
 102    */
 103   QString contentType() const;
 104   /**
 105    * KHTML-specific field, whether to do a POST instead of a GET,
 106    * for the next openURL.
 107    */
 108   void setDoPost( bool enable );
 109
 110   /**
 111    * KHTML-specific field, whether to do a POST instead of a GET,
 112    * for the next openURL.
 113    */
 114   bool doPost() const;
 115
 116   /**
 117    * Whether to lock the history when opening the next URL.
 118    * This is used during e.g. a redirection, to avoid a new entry
 119    * in the history.
 120    */
 121   void setLockHistory( bool lock );
 122   bool lockHistory() const;
 123
 124   /**
 125    * Whether the URL should be opened in a new tab instead in a new window.
 126    */
 127   void setNewTab( bool newTab );
 128   bool newTab() const;
 129
 130   /**
 131    * The frame in which to open the URL. KHTML/Konqueror-specific.
 132    */
 133   QString frameName;
 134
 135   /**
 136    * If true, the part who asks for a URL to be opened can be 'trusted'
 137    * to execute applications. For instance, the directory views can be
 138    * 'trusted' whereas HTML pages are not trusted in that respect.
 139    */
 140   bool trustedSource;
 141
 142   /**
 143    * @return true if the request was a result of a META refresh/redirect request or
 144    * HTTP redirect.
 145    */
 146   bool redirectedRequest () const;
 147
 148   /**
 149    * Set the redirect flag to indicate URL is a result of either a META redirect
 150    * or HTTP redirect.
 151    *
 152    * @param redirected
 153    */
 154   void setRedirectedRequest(bool redirected);
 155
 156   /**
 157    * Set whether the URL specifies to be opened in a new window
 158    */
 159   void setForcesNewWindow( bool forcesNewWindow );
 160
 161   /**
 162    * Whether the URL specifies to be opened in a new window
 163    */
 164   bool forcesNewWindow() const;
 165
 166 private:
 167   BrowserArgumentsPrivate *d;
 168 };
 169
 170 class WindowArgsPrivate;
 171
 172 /**
 173  * The WindowArgs are used to specify arguments to the "create new window"
 174  * call (see the createNewWindow variant that uses WindowArgs).
 175  * The primary reason for this is the javascript window.open function.
 176  */
 177 class KPARTS_EXPORT WindowArgs
 178 {
 179 public:
 180     WindowArgs();
 181     ~WindowArgs();
 182     WindowArgs( const WindowArgs &args );
 183     WindowArgs &operator=( const WindowArgs &args );
 184     WindowArgs( const QRect &_geometry, bool _fullscreen, bool _menuBarVisible,
 185                 bool _toolBarsVisible, bool _statusBarVisible, bool _resizable );
 186     WindowArgs( int _x, int _y, int _width, int _height, bool _fullscreen,
 187                 bool _menuBarVisible, bool _toolBarsVisible,
 188                 bool _statusBarVisible, bool _resizable );
 189
 190     void setX(int x);
 191     int x() const;
 192
 193     void setY(int y);
 194     int y() const;
 195
 196     void setWidth(int w);
 197     int width() const;
 198
 199     void setHeight(int h);
 200     int height() const;
 201
 202     void setFullScreen(bool fs);
 203     bool isFullScreen() const;
 204
 205     void setMenuBarVisible(bool visible);
 206     bool isMenuBarVisible() const;
 207
 208     void setToolBarsVisible(bool visible);
 209     bool toolBarsVisible() const;
 210
 211     void setStatusBarVisible(bool visible);
 212     bool isStatusBarVisible() const;
 213
 214     void setResizable(bool resizable);
 215     bool isResizable() const;
 216
 217     void setLowerWindow(bool lower);
 218     bool lowerWindow() const;
 219
 220     void setScrollBarsVisible(bool visible);
 221     bool scrollBarsVisible() const;
 222
 223 private:
 224     QSharedDataPointer<WindowArgsPrivate> d;
 225 };
 226
 227 /**
 228  * The KParts::OpenUrlEvent event informs that a given part has opened a given URL.
 229  * Applications can use this event to send this information to interested plugins.
 230  *
 231  * The event should be sent before opening the URL in the part, so that the plugins
 232  * can use part()->url() to get the old URL.
 233  */
 234 class KPARTS_EXPORT OpenUrlEvent : public Event
 235 {
 236 public:
 237   OpenUrlEvent( ReadOnlyPart *part, const KUrl &url,
 238                 const OpenUrlArguments& args = OpenUrlArguments(),
 239                 const BrowserArguments& browserArgs = BrowserArguments() );
 240   virtual ~OpenUrlEvent();
 241
 242   ReadOnlyPart *part() const;
 243   KUrl url() const;
 244   OpenUrlArguments arguments() const;
 245   BrowserArguments browserArguments() const;
 246
 247   static bool test( const QEvent *event );
 248
 249 private:
 250   class OpenUrlEventPrivate;
 251   OpenUrlEventPrivate * const d;
 252 };
 253
 254  /**
 255   * The Browser Extension is an extension (yes, no kidding) to
 256   * KParts::ReadOnlyPart, which allows a better integration of parts
 257   * with browsers (in particular Konqueror).
 258   * Remember that ReadOnlyPart only has openUrl(KUrl) and a few arguments() but not much more.
 259   * For full-fledged browsing, we need much more than that, including
 260   * enabling/disabling of standard actions (print, copy, paste...),
 261   * allowing parts to save and restore their data into the back/forward history,
 262   * allowing parts to control the location bar URL, to requests URLs
 263   * to be opened by the hosting browser, etc.
 264   *
 265   * The part developer needs to define its own class derived from BrowserExtension,
 266   * to implement the virtual methods [and the standard-actions slots, see below].
 267   *
 268   * The way to associate the BrowserExtension with the part is to simply
 269   * create the BrowserExtension as a child of the part (in QObject's terms).
 270   * The hosting application will look for it automatically.
 271   *
 272   * Another aspect of the browser integration is that a set of standard
 273   * actions are provided by the browser, but implemented by the part
 274   * (for the actions it supports).
 275   *
 276   * The following standard actions are defined by the host of the view :
 277   *
 278   * [selection-dependent actions]
 279   * @li @p cut : Copy selected items to clipboard and store 'not cut' in clipboard.
 280   * @li @p copy : Copy selected items to clipboard and store 'cut' in clipboard.
 281   * @li @p paste : Paste clipboard into view URL.
 282   * @li @p pasteTo(const KUrl &) : Paste clipboard into given URL.
 283   * @li @p searchProvider : Lookup selected text at default search provider
 284   *
 285   * [normal actions]
 286   * @li @p print : Print :-)
 287   * @li @p reparseConfiguration : Re-read configuration and apply it.
 288   * @li @p refreshMimeTypes : If the view uses mimetypes it should re-determine them.
 289   *
 290   *
 291   * The view defines a slot with the name of the action in order to implement the action.
 292   * The browser will detect the slot automatically and connect its action to it when
 293   * appropriate (i.e. when the view is active).
 294   *
 295   *
 296   * The selection-dependent actions are disabled by default and the view should
 297   * enable them when the selection changes, emitting enableAction().
 298   *
 299   * The normal actions do not depend on the selection.
 300   * You need to enable 'print' when printing is possible - you can even do that
 301   * in the constructor.
 302   *
 303   * A special case is the configuration slots, not connected to any action directly,
 304   * and having parameters.
 305   *
 306   * [configuration slot]
 307   * @li @p disableScrolling: no scrollbars
 308   */
 309 class KPARTS_EXPORT BrowserExtension : public QObject
 310 {
 311   Q_OBJECT
 312   Q_PROPERTY( bool urlDropHandling READ isURLDropHandlingEnabled WRITE setURLDropHandlingEnabled )
 313 public:
 314   /**
 315    * Constructor
 316    *
 317    * @param parent The KParts::ReadOnlyPart that this extension ... "extends" :)
 318    */
 319   explicit BrowserExtension( KParts::ReadOnlyPart *parent );
 320
 321
 322   virtual ~BrowserExtension();
 323
 324   /**
 325    * Set of flags passed via the popupMenu signal, to ask for some items in the popup menu.
 326    */
 327   enum PopupFlag {
 328       DefaultPopupItems=0x0000, /**< default value, no additional menu item */
 329       ShowNavigationItems=0x0001, /**< show "back" and "forward" (usually done when clicking the background of the view, but not an item) */
 330       ShowUp=0x0002, /**<  show "up" (same thing, but not over e.g. HTTP). Requires ShowNavigationItems. */
 331       ShowReload=0x0004, /**< show "reload" (usually done when clicking the background of the view, but not an item) */
 332       ShowBookmark=0x0008, /**< show "add to bookmarks" (usually not done on the local filesystem) */
 333       ShowCreateDirectory=0x0010, /**<  show "create directory" (usually only done on the background of the view, or
 334        *                      in hierarchical views like directory trees, where the new dir would be visible) */
 335       ShowTextSelectionItems=0x0020, /**< set when selecting text, for a popup that only contains text-related items. */
 336       NoDeletion=0x0040, /**< deletion, trashing and renaming not allowed (e.g. parent dir not writeable).
 337        *            (this is only needed if the protocol itself supports deletion, unlike e.g. HTTP) */
 338       IsLink=0x0080, /**< show "Bookmark This Link" and other link-related actions (linkactions merging group) */
 339       ShowUrlOperations=0x0100, /**< show copy, paste, as well as cut if NoDeletion is not set. */
 340       ShowProperties=0x200     /**< show "Properties" action (usually done by directory views) */
 341   };
 342
 343   Q_DECLARE_FLAGS( PopupFlags, PopupFlag )
 344
 345   /**
 346    * Set the parameters to use for opening the next URL.
 347    * This is called by the "hosting" application, to pass parameters to the part.
 348    * @see BrowserArguments
 349    */
 350   virtual void setBrowserArguments( const BrowserArguments &args );
 351
 352   /**
 353    * Retrieve the set of parameters to use for opening the URL
 354    * (this must be called from openUrl() in the part).
 355    * @see BrowserArguments
 356    */
 357   BrowserArguments browserArguments() const;
 358
 359   /**
 360    * Returns the current x offset.
 361    *
 362    * For a scrollview, implement this using contentsX().
 363    */
 364   virtual int xOffset();
 365   /**
 366    * Returns the current y offset.
 367    *
 368    * For a scrollview, implement this using contentsY().
 369    */
 370   virtual int yOffset();
 371
 372   /**
 373    * Used by the browser to save the current state of the view
 374    * (in order to restore it if going back in navigation).
 375    *
 376    * If you want to save additional properties, reimplement it
 377    * but don't forget to call the parent method (probably first).
 378    */
 379   virtual void saveState( QDataStream &stream );
 380
 381   /**
 382    * Used by the browser to restore the view in the state
 383    * it was when we left it.
 384    *
 385    * If you saved additional properties, reimplement it
 386    * but don't forget to call the parent method (probably first).
 387    */
 388   virtual void restoreState( QDataStream &stream );
 389
 390   /**
 391    * Returns whether url drop handling is enabled.
 392    * See setURLDropHandlingEnabled for more information about this
 393    * property.
 394    */
 395   bool isURLDropHandlingEnabled() const;
 396
 397   /**
 398    * Enables or disables url drop handling. URL drop handling is a property
 399    * describing whether the hosting shell component is allowed to install an
 400    * event filter on the part's widget, to listen for URI drop events.
 401    * Set it to true if you are exporting a BrowserExtension implementation and
 402    * do not provide any special URI drop handling. If set to false you can be
 403    * sure to receive all those URI drop events unfiltered. Also note that the
 404    * implementation as of Konqueror installs the event filter only on the part's
 405    * widget itself, not on child widgets.
 406    */
 407   void setURLDropHandlingEnabled( bool enable );
 408
 409   void setBrowserInterface( BrowserInterface *impl );
 410   BrowserInterface *browserInterface() const;
 411
 412   /**
 413    * @return the status (enabled/disabled) of an action.
 414    * When the enableAction signal is emitted, the browserextension
 415    * stores the status of the action internally, so that it's possible
 416    * to query later for the status of the action, using this method.
 417    */
 418   bool isActionEnabled( const char * name ) const;
 419
 420   /**
 421    * @return the text of an action, if it was set explicitly by the part.
 422    * When the setActionText signal is emitted, the browserextension
 423    * stores the text of the action internally, so that it's possible
 424    * to query later for the text of the action, using this method.
 425    */
 426   QString actionText( const char * name ) const;
 427
 428   typedef QMap<QByteArray,QByteArray> ActionSlotMap;
 429   /**
 430    * Returns a map containing the action names as keys and corresponding
 431    * SLOT()'ified method names as data entries.
 432    *
 433    * This is very useful for
 434    * the host component, when connecting the own signals with the
 435    * extension's slots.
 436    * Basically you iterate over the map, check if the extension implements
 437    * the slot and connect to the slot using the data value of your map
 438    * iterator.
 439    * Checking if the extension implements a certain slot can be done like this:
 440    *
 441    * \code
 442    *   extension->metaObject()->slotNames().contains( actionName + "()" )
 443    * \endcode
 444    *
 445    * (note that @p actionName is the iterator's key value if already
 446    *  iterating over the action slot map, returned by this method)
 447    *
 448    * Connecting to the slot can be done like this:
 449    *
 450    * \code
 451    *   connect( yourObject, SIGNAL( yourSignal() ),
 452    *            extension, mapIterator.data() )
 453    * \endcode
 454    *
 455    * (where "mapIterator" is your QMap<QCString,QCString> iterator)
 456    */
 457   static ActionSlotMap actionSlotMap();
 458
 459   /**
 460    * @return a pointer to the static action-slot map. Preferred method to get it.
 461    * The map is created if it doesn't exist yet
 462    */
 463   static ActionSlotMap * actionSlotMapPtr();
 464
 465   /**
 466    * Queries @p obj for a child object which inherits from this
 467    * BrowserExtension class. Convenience method.
 468    */
 469   static BrowserExtension *childObject( QObject *obj );
 470
 471   /**
 472    * Asks the hosting browser to perform a paste (using openUrlRequestDelayed())
 473    */
 474   void pasteRequest();
 475
 476     /**
 477      * Associates a list of actions with a predefined name known by the host's popupmenu:
 478      * "editactions" for actions related text editing,
 479      * "linkactions" for actions related to hyperlinks,
 480      * "partactions" for any other actions provided by the part
 481      */
 482     typedef QMap<QString, QList<QAction *> > ActionGroupMap;
 483
 484 Q_SIGNALS:
 485 #ifndef Q_MOC_RUN
 486 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 487 public:  // yes, those signals are public; don't tell moc or doxygen :)
 488 #endif
 489 #endif
 490   /**
 491    * Enables or disable a standard action held by the browser.
 492    *
 493    * See class documentation for the list of standard actions.
 494    */
 495   void enableAction( const char * name, bool enabled );
 496
 497   /**
 498    * Change the text of a standard action held by the browser.
 499    * This can be used to change "Paste" into "Paste Image" for instance.
 500    *
 501    * See class documentation for the list of standard actions.
 502    */
 503   void setActionText( const char * name, const QString& text );
 504
 505   /**
 506    * Asks the host (browser) to open @p url.
 507    * To set a reload, the x and y offsets, the service type etc., fill in the
 508    * appropriate fields in the @p args structure.
 509    * Hosts should not connect to this signal but to openUrlRequestDelayed().
 510    */
 511   void openUrlRequest( const KUrl &url,
 512                        const KParts::OpenUrlArguments& arguments = KParts::OpenUrlArguments(),
 513                        const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments() );
 514
 515   /**
 516    * This signal is emitted when openUrlRequest() is called, after a 0-seconds timer.
 517    * This allows the caller to terminate what it's doing first, before (usually)
 518    * being destroyed. Parts should never use this signal, hosts should only connect
 519    * to this signal.
 520    */
 521   void openUrlRequestDelayed( const KUrl &url,
 522                               const KParts::OpenUrlArguments& arguments,
 523                               const KParts::BrowserArguments &browserArguments );
 524
 525   /**
 526    * Tells the hosting browser that the part opened a new URL (which can be
 527    * queried via KParts::Part::url().
 528    *
 529    * This helps the browser to update/create an entry in the history.
 530    * The part may @em not emit this signal together with openUrlRequest().
 531    * Emit openUrlRequest() if you want the browser to handle a URL the user
 532    * asked to open (from within your part/document). This signal however is
 533    * useful if you want to handle URLs all yourself internally, while still
 534    * telling the hosting browser about new opened URLs, in order to provide
 535    * a proper history functionality to the user.
 536    * An example of usage is a html rendering component which wants to emit
 537    * this signal when a child frame document changed its URL.
 538    * Conclusion: you probably want to use openUrlRequest() instead.
 539    */
 540   void openUrlNotify();
 541
 542   /**
 543    * Updates the URL shown in the browser's location bar to @p url.
 544    */
 545   void setLocationBarUrl( const QString &url );
 546
 547   /**
 548    * Sets the URL of an icon for the currently displayed page.
 549    */
 550   void setIconUrl( const KUrl &url );
 551
 552   /**
 553    * Asks the hosting browser to open a new window for the given @p url
 554    * and return a reference to the content part.
 555    *
 556    * @p arguments is optional additional information about how to open the url,
 557    * @see KParts::OpenUrlArguments
 558    *
 559    * @p browserArguments is optional additional information for web browsers,
 560    * @see KParts::BrowserArguments
 561    *
 562    * The request for a pointer to the part is only fulfilled/processed
 563    * if the mimeType is set in the @p browserArguments.
 564    * (otherwise the request cannot be processed synchronously).
 565    */
 566     void createNewWindow( const KUrl &url,
 567                           const KParts::OpenUrlArguments& arguments = KParts::OpenUrlArguments(),
 568                           const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments(),
 569                           const KParts::WindowArgs &windowArgs = KParts::WindowArgs(),
 570                           KParts::ReadOnlyPart** part = 0 ); // TODO consider moving to BrowserHostExtension?
 571
 572   /**
 573    * Since the part emits the jobid in the started() signal,
 574    * progress information is automatically displayed.
 575    *
 576    * However, if you don't use a KIO::Job in the part,
 577    * you can use loadingProgress() and speedProgress()
 578    * to display progress information.
 579    */
 580   void loadingProgress( int percent );
 581   /**
 582    * @see loadingProgress
 583    */
 584   void speedProgress( int bytesPerSecond );
 585
 586   void infoMessage( const QString & );
 587
 588   /**
 589    * Emit this to make the browser show a standard popup menu for the files @p items.
 590    *
 591    * @param global global coordinates where the popup should be shown
 592    * @param items list of file items which the popup applies to
 593    * @param args OpenUrlArguments, mostly for metadata here
 594    * @param browserArguments BrowserArguments, mostly for referrer
 595    * @param flags enables/disables certain builtin actions in the popupmenu
 596    * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap
 597    */
 598   void popupMenu( const QPoint &global, const KFileItemList &items,
 599                   const KParts::OpenUrlArguments &args = KParts::OpenUrlArguments(),
 600                   const KParts::BrowserArguments &browserArgs = KParts::BrowserArguments(),
 601                   KParts::BrowserExtension::PopupFlags flags = KParts::BrowserExtension::DefaultPopupItems,
 602                   const KParts::BrowserExtension::ActionGroupMap& actionGroups = ActionGroupMap() );
 603
 604   /**
 605    * Emit this to make the browser show a standard popup menu for the given @p url.
 606    *
 607    * Give as much information about this URL as possible,
 608    * like @p args.mimeType and the file type @p mode
 609    *
 610    * @param global global coordinates where the popup should be shown
 611    * @param url the URL this popup applies to
 612    * @param mode the file type of the url (S_IFREG, S_IFDIR...)
 613    * @param args OpenUrlArguments, set the mimetype of the URL using setMimeType()
 614    * @param browserArguments BrowserArguments, mostly for referrer
 615    * @param flags enables/disables certain builtin actions in the popupmenu
 616    * @param actionGroups named groups of actions which should be inserted into the popup, see ActionGroupMap
 617    */
 618   void popupMenu( const QPoint &global, const KUrl &url,
 619                   mode_t mode = (mode_t)-1,
 620                   const KParts::OpenUrlArguments &args = KParts::OpenUrlArguments(),
 621                   const KParts::BrowserArguments &browserArgs = KParts::BrowserArguments(),
 622                   KParts::BrowserExtension::PopupFlags flags = KParts::BrowserExtension::DefaultPopupItems,
 623                   const KParts::BrowserExtension::ActionGroupMap& actionGroups = ActionGroupMap() );
 624
 625   /**
 626    * Inform the hosting application about the current selection.
 627    * Used when a set of files/URLs is selected (with full information
 628    * about those URLs, including size, permissions etc.)
 629    */
 630   void selectionInfo( const KFileItemList& items );
 631   /**
 632    * Inform the hosting application about the current selection.
 633    * Used when some text is selected.
 634    */
 635   void selectionInfo( const QString &text );
 636   /**
 637    * Inform the hosting application about the current selection.
 638    * Used when a set of URLs is selected.
 639    */
 640   void selectionInfo( const KUrl::List &urls );
 641
 642   /**
 643    * Inform the hosting application that the user moved the mouse over an item.
 644    * Used when the mouse is on an URL.
 645    */
 646   void mouseOverInfo( const KFileItem& item );
 647
 648   /**
 649    * Ask the hosting application to add a new HTML (aka Mozilla/Netscape)
 650    * SideBar entry.
 651    */
 652   void addWebSideBar(const KUrl &url, const QString& name);
 653
 654   /**
 655    * Ask the hosting application to move the top level widget.
 656    */
 657   void moveTopLevelWidget( int x, int y );
 658
 659   /**
 660    * Ask the hosting application to resize the top level widget.
 661    */
 662   void resizeTopLevelWidget( int w, int h );
 663
 664   /**
 665    * Ask the hosting application to focus @p part.
 666    */
 667   void requestFocus(KParts::ReadOnlyPart *part);
 668
 669   /**
 670    * Tell the host (browser) about security state of current page
 671    * enum PageSecurity { NotCrypted, Encrypted, Mixed };
 672    */
 673   void setPageSecurity( int );
 674
 675   /**
 676    * Inform the host about items that have been removed.
 677    */
 678   void itemsRemoved( const KFileItemList &items );
 679
 680 private Q_SLOTS:
 681   void slotCompleted();
 682   void slotOpenUrlRequest( const KUrl &url,
 683                            const KParts::OpenUrlArguments& arguments = KParts::OpenUrlArguments(),
 684                            const KParts::BrowserArguments &browserArguments = KParts::BrowserArguments() );
 685
 686   void slotEmitOpenUrlRequestDelayed();
 687   void slotEnableAction( const char *, bool );
 688   void slotSetActionText( const char*, const QString& );
 689
 690 public:
 691   typedef QMap<QByteArray,int> ActionNumberMap;
 692
 693 private:
 694   class BrowserExtensionPrivate;
 695   BrowserExtensionPrivate * const d;
 696 };
 697
 698 /**
 699  * An extension class for container parts, i.e. parts that contain
 700  * other parts.
 701  * For instance a KHTMLPart hosts one part per frame.
 702  */
 703 class KPARTS_EXPORT BrowserHostExtension : public QObject
 704 {
 705   Q_OBJECT
 706 public:
 707   BrowserHostExtension( KParts::ReadOnlyPart *parent );
 708
 709   virtual ~BrowserHostExtension();
 710
 711   /**
 712    * Returns a list of the names of all hosted child objects.
 713    *
 714    * Note that this method does not query the child objects recursively.
 715    */
 716   virtual QStringList frameNames() const;
 717
 718   /**
 719    * Returns a list of pointers to all hosted child objects.
 720    *
 721    * Note that this method does not query the child objects recursively.
 722    */
 723   virtual const QList<KParts::ReadOnlyPart*> frames() const;
 724
 725   /**
 726    * Returns the part that contains @p frame and that may be accessed
 727    * by @p callingPart
 728    */
 729   virtual BrowserHostExtension *findFrameParent(KParts::ReadOnlyPart *callingPart, const QString &frame);
 730
 731   /**
 732    * Opens the given url in a hosted child frame. The frame name is specified in the
 733    * frameName variable in the @p browserArguments parameter (see KParts::BrowserArguments ) .
 734    */
 735   virtual bool openUrlInFrame( const KUrl &url,
 736                                const KParts::OpenUrlArguments& arguments,
 737                                const KParts::BrowserArguments &browserArguments );
 738
 739   /**
 740    * Queries @p obj for a child object which inherits from this
 741    * BrowserHostExtension class. Convenience method.
 742    */
 743   static BrowserHostExtension *childObject( QObject *obj );
 744
 745 private:
 746   class BrowserHostExtensionPrivate;
 747   BrowserHostExtensionPrivate * const d;
 748 };
 749
 750 /**
 751  * An extension class for LiveConnect, i.e. a call from JavaScript
 752  * from a HTML page which embeds this part.
 753  * A part can have an object hierarchie by using objid as a reference
 754  * to an object.
 755  */
 756 class KPARTS_EXPORT LiveConnectExtension : public QObject
 757 {
 758   Q_OBJECT
 759 public:
 760   enum Type {
 761       TypeVoid=0, TypeBool, TypeFunction, TypeNumber, TypeObject, TypeString
 762   };
 763   typedef QList<QPair<Type, QString> > ArgList;
 764
 765   LiveConnectExtension( KParts::ReadOnlyPart *parent );
 766
 767   virtual ~LiveConnectExtension();
 768   /**
 769    * get a field value from objid, return true on success
 770    */
 771   virtual bool get( const unsigned long objid, const QString & field, Type & type, unsigned long & retobjid, QString & value );
 772   /**
 773    * put a field value in objid, return true on success
 774    */
 775   virtual bool put( const unsigned long objid, const QString & field, const QString & value );
 776   /**
 777    * calls a function of objid, return true on success
 778    */
 779   virtual bool call( const unsigned long objid, const QString & func, const QStringList & args, Type & type, unsigned long & retobjid, QString & value );
 780   /**
 781    * notifies the part that there is no reference anymore to objid
 782    */
 783   virtual void unregister( const unsigned long objid );
 784
 785   static LiveConnectExtension *childObject( QObject *obj );
 786 Q_SIGNALS:
 787 #ifndef Q_MOC_RUN
 788 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 789 public:  // yes, those signals are public; don't tell moc or doxygen :)
 790 #endif
 791 #endif
 792   /**
 793    * notify a event from the part of object objid
 794    */
 795   void partEvent( const unsigned long objid, const QString & event, const KParts::LiveConnectExtension::ArgList & args );
 796
 797 private:
 798   class LiveConnectExtensionPrivate;
 799   LiveConnectExtensionPrivate * const d;
 800 };
 801
 802 }
 803
 804 Q_DECLARE_OPERATORS_FOR_FLAGS( KParts::BrowserExtension::PopupFlags )
 805
 806 #endif
 807