browserextension.h

konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版本源码包.

  void setBrowserInterface( BrowserInterface *impl );
  BrowserInterface *browserInterface() const;

  /**
   * @return the status (enabled/disabled) of an action.
   * When the enableAction signal is emitted, the browserextension
   * stores the status of the action internally, so that it's possible
   * to query later for the status of the action, using this method.
   */
  bool isActionEnabled( const char * name ) const;

  /**
   * @return the text of an action, if it was set explicitely by the part.
   * When the setActionText signal is emitted, the browserextension
   * stores the text of the action internally, so that it's possible
   * to query later for the text of the action, using this method.
   * @since 3.5
   */
  QString actionText( const char * name ) const;

  typedef QMap<QCString,QCString> ActionSlotMap;
  /**
   * Returns a map containing the action names as keys and corresponding
   * SLOT()'ified method names as data entries.
   *
   * This is very useful for
   * the host component, when connecting the own signals with the
   * extension's slots.
   * Basically you iterate over the map, check if the extension implements
   * the slot and connect to the slot using the data value of your map
   * iterator.
   * Checking if the extension implements a certain slot can be done like this:
   *
   * \code
   *   extension->metaObject()->slotNames().contains( actionName + "()" )
   * \endcode
   *
   * (note that @p actionName is the iterator's key value if already
   *  iterating over the action slot map, returned by this method)
   *
   * Connecting to the slot can be done like this:
   *
   * \code
   *   connect( yourObject, SIGNAL( yourSignal() ),
   *            extension, mapIterator.data() )
   * \endcode
   *
   * (where "mapIterator" is your QMap<QCString,QCString> iterator)
   */
  static ActionSlotMap actionSlotMap();

  /**
   * @return a pointer to the static action-slot map. Preferred method to get it.
   * The map is created if it doesn't exist yet
   */
  static ActionSlotMap * actionSlotMapPtr();

  /**
   * Queries @p obj for a child object which inherits from this
   * BrowserExtension class. Convenience method.
   */
  static BrowserExtension *childObject( QObject *obj );

  /**
   * Asks the hosting browser to perform a paste (using openURLRequestDelayed)
   * @since 3.2
   */
  void pasteRequest();

// KDE invents support for public signals...
#undef signals
#define signals public
signals:
#undef signals
#define signals protected
  /**
   * Enables or disable a standard action held by the browser.
   *
   * See class documentation for the list of standard actions.
   */
  void enableAction( const char * name, bool enabled );

  /**
   * Change the text of a standard action held by the browser.
   * This can be used to change "Paste" into "Paste Image" for instance.
   *
   * See class documentation for the list of standard actions.
   * @since 3.5
   */
  void setActionText( const char * name, const QString& text );

  /**
   * Asks the host (browser) to open @p url.
   * To set a reload, the x and y offsets, the service type etc., fill in the
   * appropriate fields in the @p args structure.
   * Hosts should not connect to this signal but to openURLRequestDelayed.
   */
  void openURLRequest( const KURL &url, const KParts::URLArgs &args = KParts::URLArgs() );

  /**
   * This signal is emitted when openURLRequest is called, after a 0-seconds timer.
   * This allows the caller to terminate what it's doing first, before (usually)
   * being destroyed. Parts should never use this signal, hosts should only connect
   * to this signal.
   */
  void openURLRequestDelayed( const KURL &url, const KParts::URLArgs &args = KParts::URLArgs() );

  /**
   * Tells the hosting browser that the part opened a new URL (which can be
   * queried via KParts::Part::url().
   *
   * This helps the browser to update/create an entry in the history.
   * The part may @em not emit this signal together with openURLRequest().
   * Emit openURLRequest() if you want the browser to handle a URL the user
   * asked to open (from within your part/document). This signal however is
   * useful if you want to handle URLs all yourself internally, while still
   * telling the hosting browser about new opened URLs, in order to provide
   * a proper history functionality to the user.
   * An example of usage is a html rendering component which wants to emit
   * this signal when a child frame document changed its URL.
   * Conclusion: you probably want to use openURLRequest() instead.
   */
  void openURLNotify();

  /**
   * Updates the URL shown in the browser's location bar to @p url.
   */
  void setLocationBarURL( const QString &url );

  /**
   * Sets the URL of an icon for the currently displayed page.
   */
  void setIconURL( const KURL &url );

  /**
   * Asks the hosting browser to open a new window for the given @p url.
   *
   * The @p args argument is optional additional information for the
   * browser,
   * @see KParts::URLArgs
   */
  void createNewWindow( const KURL &url, const KParts::URLArgs &args = KParts::URLArgs() );

  /**
   * Asks the hosting browser to open a new window for the given @p url
   * and return a reference to the content part.
   * The request for a reference to the part is only fullfilled/processed
   * if the serviceType is set in the @p args . (otherwise the request cannot be
   * processed synchroniously.
   */
  void createNewWindow( const KURL &url, const KParts::URLArgs &args,
                        const KParts::WindowArgs &windowArgs, KParts::ReadOnlyPart *&part );

  /**
   * Since the part emits the jobid in the started() signal,
   * progress information is automatically displayed.
   *
   * However, if you don't use a KIO::Job in the part,
   * you can use loadingProgress() and speedProgress()
   * to display progress information.
   */
  void loadingProgress( int percent );
  /**
   * @see loadingProgress
   */
  void speedProgress( int bytesPerSecond );

  void infoMessage( const QString & );

  /**
   * Emit this to make the browser show a standard popup menu
   * at the point @p global for the files @p items.
   */
  void popupMenu( const QPoint &global, const KFileItemList &items );

  /**
   * Emit this to make the browser show a standard popup menu
   * at the point @p global for the files @p items.
   *
   * The GUI described by @p client is being merged with the popupmenu of the host
   */
  void popupMenu( KXMLGUIClient *client, const QPoint &global, const KFileItemList &items );

  void popupMenu( KXMLGUIClient *client, const QPoint &global, const KFileItemList &items, const KParts::URLArgs &args, KParts::BrowserExtension::PopupFlags i );

  /**
   * Emit this to make the browser show a standard popup menu
   * at the point @p global for the given @p url.
   *
   * Give as much information
   * about this URL as possible, like the @p mimeType and the file type
   * (@p mode: S_IFREG, S_IFDIR...)
   */
  void popupMenu( const QPoint &global, const KURL &url,
                  const QString &mimeType, mode_t mode = (mode_t)-1 );

  /**
   * Emit this to make the browser show a standard popup menu
   * at the point @p global for the given @p url.
   *
   * Give as much information
   * about this URL as possible, like the @p mimeType and the file type
   * (@p mode: S_IFREG, S_IFDIR...)
   * The GUI described by @p client is being merged with the popupmenu of the host
   */
  void popupMenu( KXMLGUIClient *client,
                  const QPoint &global, const KURL &url,
                  const QString &mimeType, mode_t mode = (mode_t)-1 );

  /**
   * Emit this to make the browser show a standard popup menu
   * at the point @p global for the given @p url.
   *
   * Give as much information
   * about this URL as possible, like @p args.mimeType and the file type
   * (@p mode: S_IFREG, S_IFDIR...)
   * The GUI described by @p client is being merged with the popupmenu of the host
   */
  void popupMenu( KXMLGUIClient *client,
                  const QPoint &global, const KURL &url,
                  const KParts::URLArgs &args, KParts::BrowserExtension::PopupFlags i, mode_t mode = (mode_t)-1 );

  /**
   * Inform the hosting application about the current selection.
   * Used when a set of files/URLs is selected (with full information
   * about those URLs, including size, permissions etc.)
   */
  void selectionInfo( const KFileItemList &items );
  /**
   * Inform the hosting application about the current selection.
   * Used when some text is selected.
   */
  void selectionInfo( const QString &text );
  /**
   * Inform the hosting application about the current selection.
   * Used when a set of URLs is selected.
   */
  void selectionInfo( const KURL::List &urls );

  /**
   * Inform the hosting application that the user moved the mouse over an item.
   * Used when the mouse is on an URL.
   */
  void mouseOverInfo( const KFileItem* item );

  /**
   * Ask the hosting application to add a new HTML (aka Mozilla/Netscape)
   * SideBar entry.
   */
  void addWebSideBar(const KURL &url, const QString& name);

  /**
   * Ask the hosting application to move the top level widget.
   */
  void moveTopLevelWidget( int x, int y );

  /**
   * Ask the hosting application to resize the top level widget.
   */
  void resizeTopLevelWidget( int w, int h );

  /**
   * Ask the hosting application to focus @p part.
   * @since 3.4
   */
  void requestFocus(KParts::ReadOnlyPart *part);

  /**
   * Tell the host (browser) about security state of current page
   * enum PageSecurity { NotCrypted, Encrypted, Mixed };
   * @since 3.4
   */
  void setPageSecurity( int );

private slots:
  void slotCompleted();
  void slotOpenURLRequest( const KURL &url, const KParts::URLArgs &args );
  void slotEmitOpenURLRequestDelayed();
  void slotEnableAction( const char *, bool );
  void slotSetActionText( const char*, const QString& );

private:
  KParts::ReadOnlyPart *m_part;
  URLArgs m_args;
public:
  typedef QMap<QCString,int> ActionNumberMap;

private:
  static ActionNumberMap * s_actionNumberMap;
  static ActionSlotMap * s_actionSlotMap;
  static void createActionSlotMap();
protected:
  virtual void virtual_hook( int id, void* data );
private:
  BrowserExtensionPrivate *d;
};

/**
 * An extension class for container parts, i.e. parts that contain
 * other parts.
 * For instance a KHTMLPart hosts one part per frame.
 */
class KPARTS_EXPORT BrowserHostExtension : public QObject
{
  Q_OBJECT
public:
  BrowserHostExtension( KParts::ReadOnlyPart *parent,
                        const char *name = 0L );

  virtual ~BrowserHostExtension();

  /**
   * Returns a list of the names of all hosted child objects.
   *
   * Note that this method does not query the child objects recursively.
   */
  virtual QStringList frameNames() const;

  /**
   * Returns a list of pointers to all hosted child objects.
   *
   * Note that this method does not query the child objects recursively.
   */
  virtual const QPtrList<KParts::ReadOnlyPart> frames() const;

  /**
   * Returns the part that contains @p frame and that may be accessed
   * by @p callingPart
   * @since 3.3
   */
  BrowserHostExtension *findFrameParent(KParts::ReadOnlyPart *callingPart, const QString &frame);

  /**
   * Opens the given url in a hosted child frame. The frame name is specified in the
   * frameName variable in the urlArgs argument structure (see KParts::URLArgs ) .
   */
  virtual bool openURLInFrame( const KURL &url, const KParts::URLArgs &urlArgs );

  /**
   * Queries @p obj for a child object which inherits from this
   * BrowserHostExtension class. Convenience method.
   */
  static BrowserHostExtension *childObject( QObject *obj );

protected:
  /** This 'enum' along with the structure below is NOT part of the public API.
   * It's going to disappear in KDE 4.0 and is likely to change inbetween.
   *
   * @internal
   */
  enum { VIRTUAL_FIND_FRAME_PARENT = 0x10 };
  struct FindFrameParentParams
  {
      BrowserHostExtension *parent;
      KParts::ReadOnlyPart *callingPart;
      QString frame;
  };

  virtual void virtual_hook( int id, void* data );
private:
  class BrowserHostExtensionPrivate;
  BrowserHostExtensionPrivate *d;
};

/**
 * An extension class for LiveConnect, i.e\. a call from JavaScript
 * from a HTML page which embeds this part.
 * A part can have an object hierarchie by using objid as a reference
 * to an object.
 */
class KPARTS_EXPORT LiveConnectExtension : public QObject
{
  Q_OBJECT
public:
  enum Type {
      TypeVoid=0, TypeBool, TypeFunction, TypeNumber, TypeObject, TypeString
  };
  typedef QValueList<QPair<Type, QString> > ArgList;

  LiveConnectExtension( KParts::ReadOnlyPart *parent, const char *name = 0L );

  virtual ~LiveConnectExtension() {}
  /**
   * get a field value from objid, return true on success
   */
  virtual bool get( const unsigned long objid, const QString & field, Type & type, unsigned long & retobjid, QString & value );
  /**
   * put a field value in objid, return true on success
   */
  virtual bool put( const unsigned long objid, const QString & field, const QString & value );
  /**
   * calls a function of objid, return true on success
   */
  virtual bool call( const unsigned long objid, const QString & func, const QStringList & args, Type & type, unsigned long & retobjid, QString & value );
  /**
   * notifies the part that there is no reference anymore to objid
   */
  virtual void unregister( const unsigned long objid );

  static LiveConnectExtension *childObject( QObject *obj );
signals:
  /**
   * notify an event from the part of object objid
   */
  virtual void partEvent( const unsigned long objid, const QString & event, const ArgList & args );
};

}

#endif