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
27class KComponentData;
28
29namespace KParts
30{
31
32class Part;
33
34class 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 */
47class 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 )
54public:
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
229Q_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
246protected:
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
266protected 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();
281private:
282 Part * findPartFromWidget( QWidget * widget, const QPoint &pos );
283 Part * findPartFromWidget( QWidget * widget );
284
285private:
286 PartManagerPrivate* const d;
287};
288
289}
290
291#endif
292
293