Source: part.h


Annotated List
Files
Globals
Hierarchy
Index
#ifndef _KPART_H
#define _KPART_H

#include <qstring.h>
#include <qdom.h>
#include <qguardedptr.h>
#include <kurl.h>

#include <kparts/xmlgui.h>

class KInstance;
class QWidget;
class QAction;
class QActionCollection;
class QEvent;

namespace KParts
{

class PartManager;
class Plugin;
class PartPrivate;
class PartActivateEvent;
class PartSelectEvent;
class GUIActivateEvent;
class PartBasePrivate;

class PartBase : public XMLGUIServant
{
public:
  PartBase( QObject *partObj );
  virtual ~PartBase();

  QAction* action( const char* name );
  QActionCollection* actionCollection() const;

  virtual QAction *action( const QDomElement &element );

  /**
   * @return The instance (@ref KInstance) for this part.
   */
  virtual KInstance *instance() const;

  /**
   * @return The parsed XML in a @ref QDomDocument, set by @ref setXMLFile() or @ref setXML()
   */
  virtual QDomDocument document() const;

protected:  
  /**
   * Set the instance (@ref KInstance) for this part.
   *
   * Call this first in the inherited class constructor.
   * (At least before @ref setXMLFile().)
   */
  virtual void setInstance( KInstance *instance, bool loadPlugins = true );

    /**
     * Set the name of the rc file containing the XML for the part.
     *
     * Call this in the Part-inherited class constructor.
     *
     * @param file Either an absolute path for the file, or simply the filename,
     *             which will then be assumed to be installed in the "data" resource,
     *             under a directory named like the instance.
     **/
    virtual void setXMLFile( QString file );

    /**
     * Set the XML for the part.
     *
     * Call this in the Part-inherited class constructor if you
     *  don't call @ref setXMLFile().
     **/
    virtual void setXML( const QString &document );

private:
    PartBasePrivate *d;
    QObject *m_obj;
};

/**
 * Base class for parts.
 *
 * A "part" is a GUI component, featuring
 * @li a widget embeddedable in any application
 * @li GUI elements that will be merged in the "host" user interface
 * (menubars, toolbars... )
 *
 * About the widget :
 * Note that @ref KParts::Part does not inherit @ref QWidget.
 * This is due to the fact that the "visual representation"
 * will probably not be a mere @ref QWidget, but an elaborate one.
 * That's why when implementing your @ref KParts::Part (or derived)
 * you should call @ref KParts::Part::setWidget() in your constructor.
 *
 * About the GUI elements :
 * Those elements trigger actions, defined by the part (@ref action()).
 * The layout of the actions in the GUI is defined by an XML file (@ref setXMLFile()).
 *
 * This class is an abstract interface that you need to inherit from.
 * See also @ref PartReadOnly and @ref PartReadWrite, which define the
 * framework for a "viewer" part and for an "editor"-like part.
 * Use Part directly only if your part doesn't fit into those.
 */
class Part : public QObject, public PartBase
{
  Q_OBJECT
public:
    Part( QObject *parent = 0, const char* name = 0 );
    virtual ~Part();

    /**
     * Embed this part into a host widget.
     *
     * You don't need to do this if you created the widget with the
     * correct parent widget - this is just a @ref QWidget::reparent().
     * Note that the @ref Part is still the holder
     * of the @ref QWidget, meaning that if you delete the @ref Part,
     * then the widget gets destroyed as well, and vice-versa.
     * This method is deprecated since creating the widget with the correct
     * parent is simpler anyway.
     * @deprecated
     */
    virtual void embed( QWidget * parentWidget );

    /**
     * @return The widget defined by this part, set by @ref setWidget().
     */
    virtual QWidget *widget();

    // Only called by PartManager - should be protected and using friend ?
    virtual void setManager( PartManager * manager );
    /**
     * @return The part manager handling this part, if any (0L otherwise).
     */
    PartManager * manager();

    /**
     * @internal
     */
    virtual Part *hitTest( QWidget *widget, const QPoint &globalPos );

    virtual void setSelectable( bool selectable );
    virtual bool isSelectable() const;

signals:
    /**
     * Emitted by the part, to set the caption of the window(s)
     * hosting this part
     */
    void setWindowCaption( const QString & caption );
    /**
     * Emited by the part, to set a text in the statusbar of the window(s)
     * hosting this part
     */
    void setStatusBarText( const QString & text );

protected:

    /**
     * Set the main widget.
     *
     * Call this in the Part-inherited class constructor.
     */
    virtual void setWidget( QWidget * widget );

    virtual bool event( QEvent *event );

    virtual void partActivateEvent( PartActivateEvent *event );
    virtual void partSelectEvent( PartSelectEvent *event );
    virtual void guiActivateEvent( GUIActivateEvent *event );

    QWidget *hostContainer( const QString &containerName );

private slots:
    void slotWidgetDestroyed();

private:
    QGuardedPtr<QWidget> m_widget;

    PartManager * m_manager;

    PartPrivate *d;
};

class ReadOnlyPartPrivate;

/**
 * Base class for any "viewer" part.
 *
 * This class takes care of network transparency for you,
 * in the simplest way (synchronously).
 * To use the built-in network transparency, you only need to implement
 * @ref openFile(), not @ref openURL().
 * To prevent network transparency, or to implement it another way
 * (e.g. asynchronously), override openURL().
 *
 * KParts Application can use the signals to show feedback while the URL is being loaded.
 *
 * ReadOnlyPart handles the window caption by setting it to the current URL
 * (set in @ref openURL, and each time the part is activated).
 * If you want another caption, set it in @ref openFile and
 * (if the part might ever be used with a part manager) in @ref guiActivateEvent
 */
class ReadOnlyPart : public Part
{
  Q_OBJECT
public:
  /**
   * Constructor
   * See also @ref Part for the setXXX methods to call.
   */
  ReadOnlyPart( QObject *parent = 0, const char *name = 0 );
  /**
   * Destructor
   */
  virtual ~ReadOnlyPart();

  /**
   * Only reimplement openURL if you don't want synchronous network transparency
   * Otherwise, reimplement @ref openFile() only .
   *
   * If you reimplement it, don't forget to set the caption, usually with
   * emit setWindowCaption( url.decodedURL() );
   */
  virtual bool openURL( const KURL &url );
  virtual const KURL & url() const { return m_url; }

  /**
   * Called when closing the current url (e.g. document), for instance
   * when switching to another url (note that @ref openURL calls it
   * automatically in this case).
   * If the current URL is not fully loaded yet, aborts loading.
   * Deletes the temporary file used when the url is remote.
   * @return always true, but the return value exists for reimplementations
   */
  virtual bool closeURL();

signals:
  /**
   * The part emits this when starting data.
   * If using a KIOJob, it sets the jobId in the signal, so that
   * progress information can be shown. Otherwise, jobId is 0.
   **/
  void started( int jobId );
  /**
   * Emit this when you have completed loading data.
   * Hosting apps will want to know when the process of loading the data
   *  is finished, so that they can access the data when everything is loaded.
   **/
  void completed();
  /**
   * Emit this if loading is canceled by the user or by an error.
   **/
  void canceled( const QString &errMsg );

protected slots:
  void slotJobFinished( int _id );
  void slotJobError( int, int, const char * );

protected:
  /**
   * If the part uses the standard implementation of @ref openURL,
   * it must reimplement this, to open @p m_file.
   * Otherwise simply define it to { return false; }
   */
  virtual bool openFile() = 0;

  /**
   * @internal
   */
  void abortLoad();

  /**
   * Reimplemented from Part, so that the window caption is set to
   * the current url (decoded) when the part is activated
   * This is the usual behaviour in 99% of the apps
   * Reimplement if you don't like it - test for event->activated() !
   *
   * Technical note : this is done with GUIActivateEvent and not with
   * PartActivateEvent because it's handled by the mainwindow
   * (which gets the even after the PartActivateEvent events have been sent)
   */
  virtual void guiActivateEvent( GUIActivateEvent *event );

  /**
   * Remote (or local) url - the one displayed to the user.
   */
  KURL m_url;
  /**
   * Local file - the only one the part implementation should deal with.
   */
  QString m_file;
  /**
   * If @p true, @p m_file is a temporary file that needs to be deleted later.
   */
  bool m_bTemp;

private:
  ReadOnlyPartPrivate *d;
};

/**
 * Base class for an "editor" part.
 *
 * This class handles network transparency for you.
 * Anything that can open a URL, allow modifications, and save
 * (to the same URL or a different one).
 *
 * A read-write part can be set to read-only mode, using @ref setReadWrite.
 *
 * Part writers :
 * Any part inheriting ReadWritePart should check @ref isReadWrite
 * before allowing any action that modifies the part.
 * The part probably wants to reimplement @ref setReadWrite, disable those
 * actions. Don't forget to call the parent @ref setReadWrite.
 */
class ReadWritePart : public ReadOnlyPart
{
  Q_OBJECT
public:
  /**
   * Constructor
   * See parent constructor for instructions.
   */
  ReadWritePart( QObject *parent = 0, const char *name = 0 );
  /**
   * Destructor
   * Applications using a ReadWritePart should make sure, before
   * destroying it, to call closeURL().
   * In queryClose, for instance, they should allow closing only if
   * the return value of closeURL was true. This allows to cancel.
   */
  virtual ~ReadWritePart();

  /**
   * @return true if the part is in read-write mode
   */
  virtual bool isReadWrite() { return m_bReadWrite; }

  /**
   * Changes the behaviour of this part to readonly or readwrite.
   * @param readwrite set to true to enable readwrite mode
   */
  virtual void setReadWrite ( bool readwrite = true );

  /**
   * @return true if the document has been modified.
   */
  virtual bool isModified() const { return m_bModified; }

  /**
   * Called when closing the current url (e.g. document), for instance
   * when switching to another url (note that @ref openURL calls it
   * automatically in this case).
   * If the current URL is not fully loaded yet, aborts loading.
   * Reimplemented from ReadOnlyPart, to handle modified parts
   * (and suggest saving in this case, with yes/no/cancel).
   * @return false on cancel
   */
  virtual bool closeURL();

  /**
   * Save the file to a new location.
   *
   * Calls @ref save(), no need to reimplement
   */
  virtual bool saveAs( const KURL &url );

  virtual void setModified( bool modified );

public slots:
  /**
   * Call @ref setModified() whenever the contents get modified.
   * This is a slot for convenience, so that you can connect it
   * to a signal, like textChanged().
   */
  virtual void setModified();

  /**
   * Save the file in the location from which it was opened.
   * You can connect this to the "save" action.
   * Calls @ref saveFile and @ref saveToURL, no need to reimplement.
   */
  virtual bool save();

protected:
  /**
   * Save to a local file.
   * You need to implement it, to save to @p m_file.
   * The framework takes care of re-uploading afterwards.
   */
  virtual bool saveFile() = 0;

  /**
   * Save the file.
   *
   * Uploads the file, if @p m_url is remote.
   * This will emit @ref started(), and either @ref completed() or @ref canceled(),
   * in case you want to provide feedback.
   */
  virtual bool saveToURL();

protected slots:
  void slotUploadFinished( int _id );
  void slotUploadError( int, int, const char * );

private:
  bool m_bModified;
  bool m_bReadWrite;
  bool m_bClosing;
};

};

#endif

Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:45 2000, using kdoc 2.0a33.