kparts/partmanager.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
   3              (C) 1999 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 #ifndef __kpartmanager_h__
  21 #define __kpartmanager_h__
  22
  23 #include <QtGui/QWidget>
  24
  25 #include <kparts/kparts_export.h>
  26
  27 class KComponentData;
  28
  29 namespace KParts
  30 {
  31
  32 class Part;
  33
  34 class PartManagerPrivate;
  35
  36 /**
  37  * The part manager is an object which knows about a collection of parts
  38  * (even nested ones) and handles activation/deactivation.
  39  *
  40  * Applications that want to embed parts without merging GUIs
  41  * only use a KParts::PartManager. Those who want to merge GUIs use a
  42  * KParts::MainWindow for example, in addition to a part manager.
  43  *
  44  * Parts know about the part manager to add nested parts to it.
  45  * See also KParts::Part::manager() and KParts::Part::setManager().
  46  */
  47 class KPARTS_EXPORT PartManager : public QObject
  48 {
  49     Q_OBJECT
  50     Q_ENUMS( SelectionPolicy )
  51     Q_PROPERTY( SelectionPolicy selectionPolicy READ selectionPolicy WRITE setSelectionPolicy )
  52     Q_PROPERTY( bool allowNestedParts READ allowNestedParts WRITE setAllowNestedParts )
  53     Q_PROPERTY( bool ignoreScrollBars READ ignoreScrollBars WRITE setIgnoreScrollBars )
  54 public:
  55     /// Selection policy. The default policy of a PartManager is Direct.
  56     enum SelectionPolicy { Direct, TriState };
  57
  58     /**
  59      * This extends QFocusEvent::Reason with the non-focus-event reasons for partmanager to activate a part.
  60      * To test for "any focusin reason", use < ReasonLeftClick
  61      * NoReason usually means: explicit activation with @ref setActivePart.
  62      */
  63     enum Reason { ReasonLeftClick = 100, ReasonMidClick, ReasonRightClick, NoReason };
  64
  65     /**
  66      * Constructs a part manager.
  67      *
  68      * @param parent The toplevel widget (window / dialog) the
  69      *               partmanager should monitor for activation/selection
  70      *               events
  71      */
  72     PartManager( QWidget * parent );
  73     /**
  74      * Constructs a part manager.
  75      *
  76      * @param topLevel The toplevel widget (window / dialog ) the
  77      *                 partmanager should monitor for activation/selection
  78      *                 events
  79      * @param parent   The parent QObject.
  80      */
  81     PartManager( QWidget * topLevel, QObject *parent );
  82     virtual ~PartManager();
  83
  84     /**
  85      * Sets the selection policy of the partmanager.
  86      */
  87     void setSelectionPolicy( SelectionPolicy policy );
  88     /**
  89      * Returns the current selection policy.
  90      */
  91     SelectionPolicy selectionPolicy() const;
  92
  93     /**
  94      * Specifies whether the partmanager should handle/allow nested parts
  95      * or not.
  96      *
  97      *  This is a property the shell has to set/specify. Per
  98      * default we assume that the shell cannot handle nested
  99      * parts. However in case of a KOffice shell for example we allow
 100      * nested parts.  A Part is nested (a child part) if its parent
 101      * object inherits KParts::Part.  If a child part is activated and
 102      * nested parts are not allowed/handled, then the top parent part in
 103      * the tree is activated.
 104      */
 105     void setAllowNestedParts( bool allow );
 106     /**
 107      * @see setAllowNestedParts
 108      */
 109     bool allowNestedParts() const;
 110
 111     /**
 112      * Specifies whether the partmanager should ignore mouse click events for
 113      * scrollbars or not. If the partmanager ignores them, then clicking on the
 114      * scrollbars of a non-active/non-selected part will not change the selection
 115      * or activation state.
 116      *
 117      * The default value is false (read: scrollbars are NOT ignored).
 118      */
 119     void setIgnoreScrollBars( bool ignore );
 120     /**
 121      * @see setIgnoreScrollBars
 122      */
 123     bool ignoreScrollBars() const;
 124
 125     /**
 126      * Specifies which mouse buttons the partmanager should react upon.
 127      * By default it reacts on all mouse buttons (LMB/MMB/RMB).
 128      * @param buttonMask a combination of Qt::ButtonState values e.g. Qt::LeftButton | Qt::MidButton
 129      */
 130     void setActivationButtonMask( short int buttonMask );
 131     /**
 132      * @see setActivationButtonMask
 133      */
 134     short int activationButtonMask() const;
 135
 136     /**
 137      * @internal
 138      */
 139     virtual bool eventFilter( QObject *obj, QEvent *ev );
 140
 141     /**
 142      * Adds a part to the manager.
 143      *
 144      * Sets it to the active part automatically if @p setActive is true (default ).
 145      * Behavior fix in KDE3.4: the part's widget is shown only if setActive is true,
 146      * it used to be shown in all cases before.
 147      */
 148     virtual void addPart( Part *part, bool setActive = true );
 149
 150     /**
 151      * Removes a part from the manager (this does not delete the object) .
 152      *
 153      * Sets the active part to 0 if @p part is the activePart() .
 154      */
 155     virtual void removePart( Part *part );
 156
 157     /**
 158      * Replaces @p oldPart with @p newPart, and sets @p newPart as active if
 159      * @p setActive is true.
 160      * This is an optimised version of removePart + addPart
 161      */
 162     virtual void replacePart( Part * oldPart, Part * newPart, bool setActive = true );
 163
 164     /**
 165      * Sets the active part.
 166      *
 167      * The active part receives activation events.
 168      *
 169      * @p widget can be used to specify which widget was responsible for the activation.
 170      * This is important if you have multiple views for a document/part , like in KOffice .
 171      */
 172     virtual void setActivePart( Part *part, QWidget *widget = 0 );
 173
 174     /**
 175      * Returns the active part.
 176      **/
 177     virtual Part *activePart() const;
 178
 179     /**
 180      * Returns the active widget of the current active part (see activePart ).
 181      */
 182     virtual QWidget *activeWidget() const;
 183
 184     /**
 185      * Sets the selected part.
 186      *
 187      * The selected part receives selection events.
 188      *
 189      * @p widget can be used to specify which widget was responsible for the selection.
 190      * This is important if you have multiple views for a document/part , like in KOffice .
 191      */
 192     virtual void setSelectedPart( Part *part, QWidget *widget = 0 );
 193
 194     /**
 195      * Returns the current selected part.
 196      */
 197     virtual Part *selectedPart() const;
 198
 199     /**
 200      * Returns the selected widget of the current selected part (see selectedPart ).
 201      */
 202     virtual QWidget *selectedWidget() const;
 203
 204     /**
 205      * Returns the list of parts being managed by the partmanager.
 206      */
 207     const QList<Part *> parts() const;
 208
 209     /**
 210      * Adds the @p topLevel widget to the list of managed toplevel widgets.
 211      * Usually a PartManager only listens for events (for activation/selection)
 212      * for one toplevel widget (and its children) , the one specified in the
 213      * constructor. Sometimes however (like for example when using the KDE dockwidget
 214      * library) , it is necessary to extend this.
 215      */
 216     void addManagedTopLevelWidget( const QWidget *topLevel );
 217     /**
 218      * Removes the @p topLevel widget from the list of managed toplevel widgets.
 219      * @see addManagedTopLevelWidget
 220      */
 221     void removeManagedTopLevelWidget( const QWidget *topLevel );
 222
 223     /**
 224      * @return the reason for the last activePartChanged signal emitted.
 225      * @see Reason
 226      */
 227     int reason() const;
 228
 229 Q_SIGNALS:
 230     /**
 231      * Emitted when a new part has been added.
 232      * @see addPart()
 233      **/
 234     void partAdded( KParts::Part *part );
 235     /**
 236      * Emitted when a part has been removed.
 237      * @see removePart()
 238      **/
 239     void partRemoved( KParts::Part *part );
 240     /**
 241      * Emitted when the active part has changed.
 242      * @see setActivePart()
 243      **/
 244     void activePartChanged( KParts::Part *newPart );
 245
 246 protected:
 247     /**
 248      * Changes the active instance when the active part changes.
 249      * The active instance is used by KBugReport and KAboutDialog.
 250      * Override if you really need to - usually you don't need to.
 251      */
 252     virtual void setActiveComponent(const KComponentData &instance);
 253
 254 protected Q_SLOTS:
 255     /**
 256      * Removes a part when it is destroyed.
 257      **/
 258     void slotObjectDestroyed();
 259
 260     /**
 261      * @internal
 262      */
 263     void slotWidgetDestroyed();
 264
 265     /**
 266      * @internal
 267      */
 268     void slotManagedTopLevelWidgetDestroyed();
 269 private:
 270     Part * findPartFromWidget( QWidget * widget, const QPoint &pos );
 271     Part * findPartFromWidget( QWidget * widget );
 272
 273 private:
 274     PartManagerPrivate* const d;
 275 };
 276
 277 }
 278
 279 #endif
 280