File indexing completed on 2024-05-19 07:45:49
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0004 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef __kpartmanager_h__ 0010 #define __kpartmanager_h__ 0011 0012 #include <kparts/kparts_export.h> 0013 0014 #include <QWidget> 0015 #include <memory> 0016 0017 namespace KParts 0018 { 0019 class Part; 0020 0021 class PartManagerPrivate; 0022 0023 /** 0024 * @class PartManager partmanager.h <KParts/PartManager> 0025 * 0026 * @short The part manager is an object which knows about a collection of parts 0027 * (even nested ones) and handles activation/deactivation. 0028 * 0029 * Applications that want to embed parts without merging GUIs 0030 * only use a KParts::PartManager. Those who want to merge GUIs use a 0031 * KParts::MainWindow for example, in addition to a part manager. 0032 * 0033 * Parts know about the part manager to add nested parts to it. 0034 * See also KParts::Part::manager() and KParts::Part::setManager(). 0035 */ 0036 class KPARTS_EXPORT PartManager : public QObject 0037 { 0038 Q_OBJECT 0039 Q_PROPERTY(SelectionPolicy selectionPolicy READ selectionPolicy WRITE setSelectionPolicy) 0040 Q_PROPERTY(bool allowNestedParts READ allowNestedParts WRITE setAllowNestedParts) 0041 Q_PROPERTY(bool ignoreScrollBars READ ignoreScrollBars WRITE setIgnoreScrollBars) 0042 public: 0043 /// Selection policy. The default policy of a PartManager is Direct. 0044 enum SelectionPolicy { Direct, TriState }; 0045 Q_ENUM(SelectionPolicy) 0046 0047 /** 0048 * This extends QFocusEvent::Reason with the non-focus-event reasons for partmanager to activate a part. 0049 * To test for "any focusin reason", use < ReasonLeftClick 0050 * NoReason usually means: explicit activation with @ref setActivePart. 0051 */ 0052 enum Reason { ReasonLeftClick = 100, ReasonMidClick, ReasonRightClick, NoReason }; 0053 0054 /** 0055 * Constructs a part manager. 0056 * 0057 * @param parent The toplevel widget (window / dialog) the 0058 * partmanager should monitor for activation/selection 0059 * events 0060 */ 0061 PartManager(QWidget *parent); 0062 /** 0063 * Constructs a part manager. 0064 * 0065 * @param topLevel The toplevel widget (window / dialog ) the 0066 * partmanager should monitor for activation/selection 0067 * events 0068 * @param parent The parent QObject. 0069 */ 0070 PartManager(QWidget *topLevel, QObject *parent); 0071 ~PartManager() override; 0072 0073 /** 0074 * Sets the selection policy of the partmanager. 0075 */ 0076 void setSelectionPolicy(SelectionPolicy policy); 0077 /** 0078 * Returns the current selection policy. 0079 */ 0080 SelectionPolicy selectionPolicy() const; 0081 0082 /** 0083 * Specifies whether the partmanager should handle/allow nested parts 0084 * or not. 0085 * 0086 * This is a property the shell has to set/specify. Per 0087 * default we assume that the shell cannot handle nested 0088 * parts. However in case of a KOffice shell for example we allow 0089 * nested parts. A Part is nested (a child part) if its parent 0090 * object inherits KParts::Part. If a child part is activated and 0091 * nested parts are not allowed/handled, then the top parent part in 0092 * the tree is activated. 0093 */ 0094 void setAllowNestedParts(bool allow); 0095 /** 0096 * @see setAllowNestedParts 0097 */ 0098 bool allowNestedParts() const; 0099 0100 /** 0101 * Specifies whether the partmanager should ignore mouse click events for 0102 * scrollbars or not. If the partmanager ignores them, then clicking on the 0103 * scrollbars of a non-active/non-selected part will not change the selection 0104 * or activation state. 0105 * 0106 * The default value is false (read: scrollbars are NOT ignored). 0107 */ 0108 void setIgnoreScrollBars(bool ignore); 0109 /** 0110 * @see setIgnoreScrollBars 0111 */ 0112 bool ignoreScrollBars() const; 0113 0114 /** 0115 * Specifies which mouse buttons the partmanager should react upon. 0116 * By default it reacts on all mouse buttons (LMB/MMB/RMB). 0117 * @param buttonMask a combination of Qt::ButtonState values e.g. Qt::LeftButton | Qt::MiddleButton 0118 */ 0119 void setActivationButtonMask(short int buttonMask); 0120 /** 0121 * @see setActivationButtonMask 0122 */ 0123 short int activationButtonMask() const; 0124 0125 /** 0126 * @internal 0127 */ 0128 bool eventFilter(QObject *obj, QEvent *ev) override; 0129 0130 /** 0131 * Adds a part to the manager. 0132 * 0133 * Sets it to the active part automatically if @p setActive is true (default). 0134 */ 0135 virtual void addPart(Part *part, bool setActive = true); 0136 0137 /** 0138 * Removes a part from the manager (this does not delete the object) . 0139 * 0140 * Sets the active part to 0 if @p part is the activePart() . 0141 */ 0142 virtual void removePart(Part *part); 0143 0144 /** 0145 * Replaces @p oldPart with @p newPart, and sets @p newPart as active if 0146 * @p setActive is true. 0147 * This is an optimised version of removePart + addPart 0148 */ 0149 virtual void replacePart(Part *oldPart, Part *newPart, bool setActive = true); 0150 0151 /** 0152 * Sets the active part. 0153 * 0154 * The active part receives activation events. 0155 * 0156 * @p widget can be used to specify which widget was responsible for the activation. 0157 * This is important if you have multiple views for a document/part , like in KOffice . 0158 */ 0159 virtual void setActivePart(Part *part, QWidget *widget = nullptr); 0160 0161 /** 0162 * Returns the active part. 0163 **/ 0164 virtual Part *activePart() const; 0165 0166 /** 0167 * Returns the active widget of the current active part (see activePart ). 0168 */ 0169 virtual QWidget *activeWidget() const; 0170 0171 /** 0172 * Returns the list of parts being managed by the partmanager. 0173 */ 0174 const QList<Part *> parts() const; 0175 0176 /** 0177 * Adds the @p topLevel widget to the list of managed toplevel widgets. 0178 * Usually a PartManager only listens for events (for activation/selection) 0179 * for one toplevel widget (and its children) , the one specified in the 0180 * constructor. Sometimes however (like for example when using the KDE dockwidget 0181 * library) , it is necessary to extend this. 0182 */ 0183 void addManagedTopLevelWidget(const QWidget *topLevel); 0184 /** 0185 * Removes the @p topLevel widget from the list of managed toplevel widgets. 0186 * @see addManagedTopLevelWidget 0187 */ 0188 void removeManagedTopLevelWidget(const QWidget *topLevel); 0189 0190 /** 0191 * @return the reason for the last activePartChanged signal emitted. 0192 * @see Reason 0193 */ 0194 int reason() const; 0195 0196 Q_SIGNALS: 0197 /** 0198 * Emitted when a new part has been added. 0199 * @see addPart() 0200 **/ 0201 void partAdded(KParts::Part *part); 0202 /** 0203 * Emitted when a part has been removed. 0204 * @see removePart() 0205 **/ 0206 void partRemoved(KParts::Part *part); 0207 /** 0208 * Emitted when the active part has changed. 0209 * @see setActivePart() 0210 **/ 0211 void activePartChanged(KParts::Part *newPart); 0212 0213 protected: 0214 /** 0215 * Sets whether the PartManager ignores explicit set focus requests 0216 * from the part. 0217 * 0218 * By default this option is set to false. Set it to true to prevent 0219 * the part from sending explicit set focus requests to the client 0220 * application. 0221 * 0222 * @since 4.10 0223 */ 0224 void setIgnoreExplictFocusRequests(bool); 0225 0226 protected Q_SLOTS: 0227 /** 0228 * Removes a part when it is destroyed. 0229 **/ 0230 void slotObjectDestroyed(); 0231 0232 /** 0233 * @internal 0234 */ 0235 void slotWidgetDestroyed(); 0236 0237 /** 0238 * @internal 0239 */ 0240 void slotManagedTopLevelWidgetDestroyed(); 0241 0242 private: 0243 KPARTS_NO_EXPORT Part *findPartFromWidget(QWidget *widget, const QPoint &pos); 0244 KPARTS_NO_EXPORT Part *findPartFromWidget(QWidget *widget); 0245 0246 private: 0247 std::unique_ptr<PartManagerPrivate> const d; 0248 }; 0249 0250 } 0251 0252 #endif