summaryrefslogtreecommitdiffstats
path: root/kparts/partmanager.h
diff options
context:
space:
mode:
Diffstat (limited to 'kparts/partmanager.h')
-rw-r--r--kparts/partmanager.h289
1 files changed, 289 insertions, 0 deletions
diff --git a/kparts/partmanager.h b/kparts/partmanager.h
new file mode 100644
index 000000000..95e70895c
--- /dev/null
+++ b/kparts/partmanager.h
@@ -0,0 +1,289 @@
+// -*- mode: c++; c-basic-offset: 2 -*-
+/* This file is part of the KDE project
+ Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
+ (C) 1999 David Faure <faure@kde.org>
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Library General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Library General Public License for more details.
+
+ You should have received a copy of the GNU Library General Public License
+ along with this library; see the file COPYING.LIB. If not, write to
+ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
+*/
+#ifndef __kpartmanager_h__
+#define __kpartmanager_h__
+
+#include <qobject.h>
+#include <qwidget.h>
+#include <qptrlist.h>
+
+#include <kdelibs_export.h>
+
+class KInstance;
+
+namespace KParts
+{
+
+class Part;
+
+class PartManagerPrivate;
+
+/**
+ * The part manager is an object which knows about a collection of parts
+ * (even nested ones) and handles activation/deactivation.
+ *
+ * Applications that want to embed parts without merging GUIs
+ * only use a KParts::PartManager. Those who want to merge GUIs use a
+ * KParts::MainWindow for example, in addition to a part manager.
+ *
+ * Parts know about the part manager to add nested parts to it.
+ * See also KParts::Part::manager() and KParts::Part::setManager().
+ */
+class KPARTS_EXPORT PartManager : public QObject
+{
+ Q_OBJECT
+ Q_ENUMS( SelectionPolicy )
+ Q_PROPERTY( SelectionPolicy selectionPolicy READ selectionPolicy WRITE setSelectionPolicy )
+ Q_PROPERTY( bool allowNestedParts READ allowNestedParts WRITE setAllowNestedParts )
+ Q_PROPERTY( bool ignoreScrollBars READ ignoreScrollBars WRITE setIgnoreScrollBars )
+public:
+ /// Selection policy. The default policy of a PartManager is Direct.
+ enum SelectionPolicy { Direct, TriState };
+
+ /**
+ * This extends QFocusEvent::Reason with the non-focus-event reasons for partmanager to activate a part.
+ * To test for "any focusin reason", use < ReasonLeftClick.
+ * NoReason usually means: explicit activation with @ref setActivePart.
+ * @since 3.3
+ */
+ enum Reason { ReasonLeftClick = 100, ReasonMidClick, ReasonRightClick, NoReason };
+
+ /**
+ * Constructs a part manager.
+ *
+ * @param parent The toplevel widget (window / dialog) the
+ * partmanager should monitor for activation/selection
+ * events
+ * @param name The object's name, if any.
+ */
+ PartManager( QWidget * parent, const char * name = 0L );
+ /**
+ * Constructs a part manager.
+ *
+ * @param topLevel The toplevel widget (window / dialog ) the
+ * partmanager should monitor for activation/selection
+ * events
+ * @param parent The parent QObject.
+ * @param name The object's name, if any.
+ */
+ PartManager( QWidget * topLevel, QObject *parent, const char *name = 0 );
+ virtual ~PartManager();
+
+ /**
+ * Sets the selection policy of the partmanager.
+ */
+ void setSelectionPolicy( SelectionPolicy policy );
+ /**
+ * Returns the current selection policy.
+ */
+ SelectionPolicy selectionPolicy() const;
+
+ /**
+ * Specifies whether the partmanager should handle/allow nested parts
+ * or not.
+ *
+ * This is a property the shell has to set/specify. Per
+ * default we assume that the shell cannot handle nested
+ * parts. However in case of a KOffice shell for example we allow
+ * nested parts. A Part is nested (a child part) if its parent
+ * object inherits KParts::Part. If a child part is activated and
+ * nested parts are not allowed/handled, then the top parent part in
+ * the tree is activated.
+ */
+ void setAllowNestedParts( bool allow );
+ /**
+ * @see setAllowNestedParts
+ */
+ bool allowNestedParts() const;
+
+ /**
+ * Specifies whether the partmanager should ignore mouse click events for
+ * scrollbars or not. If the partmanager ignores them, then clicking on the
+ * scrollbars of a non-active/non-selected part will not change the selection
+ * or activation state.
+ *
+ * The default value is false (read: scrollbars are NOT ignored).
+ */
+ void setIgnoreScrollBars( bool ignore );
+ /**
+ * @see setIgnoreScrollBars
+ */
+ bool ignoreScrollBars() const;
+
+ /**
+ * Specifies which mouse buttons the partmanager should react upon.
+ * By default it reacts on all mouse buttons (LMB/MMB/RMB).
+ * @param buttonMask a combination of Qt::ButtonState values e.g. Qt::LeftButton | Qt::MidButton
+ */
+ void setActivationButtonMask( short int buttonMask );
+ /**
+ * @see setActivationButtonMask
+ */
+ short int activationButtonMask() const;
+
+ /**
+ * @internal
+ */
+ virtual bool eventFilter( QObject *obj, QEvent *ev );
+
+ /**
+ * Adds a part to the manager.
+ *
+ * Sets it to the active part automatically if @p setActive is true (default ).
+ * Behavior fix in KDE3.4: the part's widget is shown only if @p setActive is true,
+ * it used to be shown in all cases before.
+ */
+ virtual void addPart( Part *part, bool setActive = true );
+
+ /**
+ * Removes a part from the manager (this does not delete the object) .
+ *
+ * Sets the active part to 0 if @p part is the activePart() .
+ */
+ virtual void removePart( Part *part );
+
+ /**
+ * Replaces @p oldPart with @p newPart, and sets @p newPart as active if
+ * @p setActive is true.
+ * This is an optimised version of removePart + addPart
+ */
+ virtual void replacePart( Part * oldPart, Part * newPart, bool setActive = true );
+
+ /**
+ * Sets the active part.
+ *
+ * The active part receives activation events.
+ *
+ * @p widget can be used to specify which widget was responsible for the activation.
+ * This is important if you have multiple views for a document/part, like in KOffice.
+ */
+ virtual void setActivePart( Part *part, QWidget *widget = 0L );
+
+ /**
+ * Returns the active part.
+ **/
+ virtual Part *activePart() const;
+
+ /**
+ * Returns the active widget of the current active part (see activePart()).
+ */
+ virtual QWidget *activeWidget() const;
+
+ /**
+ * Sets the selected part.
+ *
+ * The selected part receives selection events.
+ *
+ * @p widget can be used to specify which widget was responsible for the selection.
+ * This is important if you have multiple views for a document/part, like in KOffice.
+ */
+ virtual void setSelectedPart( Part *part, QWidget *widget = 0L );
+
+ /**
+ * Returns the current selected part.
+ */
+ virtual Part *selectedPart() const;
+
+ /**
+ * Returns the selected widget of the current selected part (see selectedPart()).
+ */
+ virtual QWidget *selectedWidget() const;
+
+ /**
+ * Returns the list of parts being managed by the partmanager.
+ */
+ const QPtrList<Part> *parts() const;
+
+ /**
+ * Adds the @p topLevel widget to the list of managed toplevel widgets.
+ * Usually a PartManager only listens for events (for activation/selection)
+ * for one toplevel widget (and its children), the one specified in the
+ * constructor. Sometimes however (like for example when using the KDE dockwidget
+ * library), it is necessary to extend this.
+ */
+ void addManagedTopLevelWidget( const QWidget *topLevel );
+ /**
+ * Removes the @p topLevel widget from the list of managed toplevel widgets.
+ * @see addManagedTopLevelWidget
+ */
+ void removeManagedTopLevelWidget( const QWidget *topLevel );
+
+ /**
+ * @return the reason for the last activePartChanged signal emitted.
+ * @see Reason
+ * @since 3.3
+ */
+ int reason() const;
+
+signals:
+ /**
+ * Emitted when a new part has been added.
+ * @see addPart()
+ **/
+ void partAdded( KParts::Part *part );
+ /**
+ * Emitted when a part has been removed.
+ * @see removePart()
+ **/
+ void partRemoved( KParts::Part *part );
+ /**
+ * Emitted when the active part has changed.
+ * @see setActivePart()
+ **/
+ void activePartChanged( KParts::Part *newPart );
+
+protected:
+ /**
+ * Changes the active instance when the active part changes.
+ * The active instance is used by KBugReport and KAboutDialog.
+ * Override if you really need to - usually you don't need to.
+ */
+ virtual void setActiveInstance( KInstance * instance );
+
+protected slots:
+ /**
+ * Removes a part when it is destroyed.
+ **/
+ void slotObjectDestroyed();
+
+ /**
+ * @internal
+ */
+ void slotWidgetDestroyed();
+
+ /**
+ * @internal
+ */
+ void slotManagedTopLevelWidgetDestroyed();
+private:
+ Part * findPartFromWidget( QWidget * widget, const QPoint &pos );
+ Part * findPartFromWidget( QWidget * widget );
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ PartManagerPrivate *d;
+};
+
+}
+
+#endif
+