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 | /** |
255 | * Sets whether the PartManager ignores explict set focus requests |
256 | * from the part. |
257 | * |
258 | * By default this option is set to false. Set it to true to prevent |
259 | * the part from sending explicit set focus requests to the client |
260 | * application. |
261 | * |
262 | * @since 4.10 |
263 | */ |
264 | void setIgnoreExplictFocusRequests(bool); |
265 | |
266 | protected Q_SLOTS: |
267 | /** |
268 | * Removes a part when it is destroyed. |
269 | **/ |
270 | void slotObjectDestroyed(); |
271 | |
272 | /** |
273 | * @internal |
274 | */ |
275 | void slotWidgetDestroyed(); |
276 | |
277 | /** |
278 | * @internal |
279 | */ |
280 | void slotManagedTopLevelWidgetDestroyed(); |
281 | private: |
282 | Part * findPartFromWidget( QWidget * widget, const QPoint &pos ); |
283 | Part * findPartFromWidget( QWidget * widget ); |
284 | |
285 | private: |
286 | PartManagerPrivate* const d; |
287 | }; |
288 | |
289 | } |
290 | |
291 | #endif |
292 | |
293 | |