KParts

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

KDE's Doxygen guidelines are available online.