1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org>
4 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org>
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
17namespace KParts
18{
19class Part;
20
21class 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 */
36class 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)
42public:
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 ~PartManager() override;
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 /**
172 * Returns the list of parts being managed by the partmanager.
173 */
174 const QList<Part *> parts() const;
175
176 /**
177 * Adds the @p topLevel widget to the list of managed toplevel widgets.
178 * Usually a PartManager only listens for events (for activation/selection)
179 * for one toplevel widget (and its children) , the one specified in the
180 * constructor. Sometimes however (like for example when using the KDE dockwidget
181 * library) , it is necessary to extend this.
182 */
183 void addManagedTopLevelWidget(const QWidget *topLevel);
184 /**
185 * Removes the @p topLevel widget from the list of managed toplevel widgets.
186 * @see addManagedTopLevelWidget
187 */
188 void removeManagedTopLevelWidget(const QWidget *topLevel);
189
190 /**
191 * @return the reason for the last activePartChanged signal emitted.
192 * @see Reason
193 */
194 int reason() const;
195
196Q_SIGNALS:
197 /**
198 * Emitted when a new part has been added.
199 * @see addPart()
200 **/
201 void partAdded(KParts::Part *part);
202 /**
203 * Emitted when a part has been removed.
204 * @see removePart()
205 **/
206 void partRemoved(KParts::Part *part);
207 /**
208 * Emitted when the active part has changed.
209 * @see setActivePart()
210 **/
211 void activePartChanged(KParts::Part *newPart);
212
213protected:
214 /**
215 * Sets whether the PartManager ignores explicit set focus requests
216 * from the part.
217 *
218 * By default this option is set to false. Set it to true to prevent
219 * the part from sending explicit set focus requests to the client
220 * application.
221 *
222 * @since 4.10
223 */
224 void setIgnoreExplictFocusRequests(bool);
225
226protected Q_SLOTS:
227 /**
228 * Removes a part when it is destroyed.
229 **/
230 void slotObjectDestroyed();
231
232 /**
233 * @internal
234 */
235 void slotWidgetDestroyed();
236
237 /**
238 * @internal
239 */
240 void slotManagedTopLevelWidgetDestroyed();
241
242private:
243 KPARTS_NO_EXPORT Part *findPartFromWidget(QWidget *widget, const QPoint &pos);
244 KPARTS_NO_EXPORT Part *findPartFromWidget(QWidget *widget);
245
246private:
247 std::unique_ptr<PartManagerPrivate> const d;
248};
249
250}
251
252#endif
253

source code of kparts/src/partmanager.h