KParts

part.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 _KPARTS_PART_H
10 #define _KPARTS_PART_H
11 
12 #include <kparts/partbase.h>
13 
14 class KPluginMetaData;
15 class KIconLoader;
16 class QWidget;
17 class QEvent;
18 class QPoint;
19 
20 /**
21  * The KParts namespace,
22  */
23 namespace KParts
24 {
25 class PartManager;
26 class PartPrivate;
27 class PartActivateEvent;
28 
29 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 72)
30 class PartSelectEvent;
31 #endif
32 
33 class GUIActivateEvent;
34 
35 /**
36  * @class Part part.h <KParts/Part>
37  *
38  * @short Base class for parts.
39  *
40  * A "part" is a GUI component, featuring:
41  * @li A widget embeddedable in any application.
42  * @li GUI elements that will be merged in the "host" user interface
43  * (menubars, toolbars... ).
44  *
45  * <b>About the widget:</b>\n
46  *
47  * Note that KParts::Part does not inherit QWidget.
48  * This is due to the fact that the "visual representation"
49  * will probably not be a mere QWidget, but an elaborate one.
50  * That's why when implementing your KParts::Part (or derived)
51  * you should call KParts::Part::setWidget() in your constructor.
52  *
53  * <b>About the GUI elements:</b>\n
54  *
55  * Those elements trigger actions, defined by the part ( action()).
56  * The layout of the actions in the GUI is defined by an XML file ( setXMLFile()).
57  *
58  * See also ReadOnlyPart and ReadWritePart, which define the
59  * framework for a "viewer" part and for an "editor"-like part.
60  * Use Part directly only if your part doesn't fit into those.
61  */
62 class KPARTS_EXPORT Part : public QObject, public PartBase
63 {
64  Q_OBJECT
65 
66  KPARTS_DECLARE_PRIVATE(Part)
67 
68 public:
69  /**
70  * Constructor.
71  *
72  * @param parent Parent object of the part.
73  */
74  explicit Part(QObject *parent = nullptr);
75 
76  /**
77  * Destructor.
78  */
79  ~Part() override;
80 
81 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 77)
82  /**
83  * Embed this part into a host widget.
84  *
85  * You don't need to do this if you created the widget with the
86  * correct parent widget - this is just a QWidget::reparent().
87  * Note that the Part is still the holder
88  * of the QWidget, meaning that if you delete the Part,
89  * then the widget gets destroyed as well, and vice-versa.
90  * This method is not recommended since creating the widget with the correct
91  * parent is simpler anyway.
92  *
93  * @deprecated Since 5.77, for lack of usage.
94  */
95  KPARTS_DEPRECATED_VERSION(5, 77, "Deprecated for lack of usage")
96  virtual void embed(QWidget *parentWidget);
97 #endif
98 
99  /**
100  * @return The widget defined by this part, set by setWidget().
101  */
102  virtual QWidget *widget();
103 
104  /**
105  * @internal
106  * Used by the part manager.
107  */
108  virtual void setManager(PartManager *manager);
109 
110  /**
111  * Returns the part manager handling this part, if any (0L otherwise).
112  */
113  PartManager *manager() const;
114 
115  /**
116  * By default, the widget is deleted by the part when the part is deleted.
117  * The hosting application can call setAutoDeleteWidget(false) to
118  * disable this behavior, given that the widget is usually deleted by
119  * its parent widget anyway.
120  * This is a method for the hosting application only, Part subclasses
121  * should never call this.
122  */
123  void setAutoDeleteWidget(bool autoDeleteWidget);
124 
125  /**
126  * By default, the part deletes itself when its widget is deleted.
127  * The hosting application can call setAutoDeletePart(false) to
128  * disable this behavior, to be able to delete the widget and then the part,
129  * independently.
130  * This is a method for the hosting application only, Part subclasses
131  * should never call this.
132  */
133  void setAutoDeletePart(bool autoDeletePart);
134 
135  /**
136  * Returns the part (this, or a child part) at the given global position.
137  * This is called by the part manager to ask whether a part should be activated
138  * when clicking somewhere. In most cases the default implementation is enough.
139  * Reimplement this if your part has child parts in some areas (like in khtml or koffice)
140  * @param widget the part widget being clicked - usually the same as widget(), except in koffice.
141  * @param globalPos the mouse coordinates in global coordinates
142  */
143  virtual Part *hitTest(QWidget *widget, const QPoint &globalPos);
144 
145 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 72)
146  /**
147  * @param selectable Indicates whether the part is selectable or not.
148  *
149  * @deprecated Since 5.72, for lack of usage.
150  */
151  KPARTS_DEPRECATED_VERSION(5, 72, "Deprecated for lack of usage")
152  virtual void setSelectable(bool selectable);
153 #endif
154 
155 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 72)
156  /**
157  * Returns whether the part is selectable or not.
158  *
159  * @deprecated Since 5.72, for lack of usage.
160  */
161  KPARTS_DEPRECATED_VERSION(5, 72, "Deprecated for lack of usage")
162  bool isSelectable() const;
163 #endif
164 
165  /**
166  * @since 5.77
167  */
168  KPluginMetaData metaData() const;
169 
170 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 82)
171  /**
172  * Use this icon loader to load any icons that are specific to this part,
173  * i.e. icons installed into this part's own directories as opposed to standard
174  * kde icons.
175  *
176  * Make sure to call setMetaData (or deprecated setComponentData) before calling iconLoader.
177  * @deprecated since 5.82, use QIcon::fromTheme() and set QIcon::setThemeSearchPaths()
178  * or QIcon::setFallbackSearchPaths appropriately.
179  */
180  KPARTS_DEPRECATED_VERSION(5, 82, "See API docs.")
181  KIconLoader *iconLoader();
182 #endif
183 
184 Q_SIGNALS:
185  /**
186  * Emitted by the part, to set the caption of the window(s)
187  * hosting this part
188  *
189  * @note this signal has only an effect on the window title if window title
190  * handling is enabled @see KParts::MainWindow::setWindowTitleHandling
191  */
192  void setWindowCaption(const QString &caption);
193  /**
194  * Emitted by the part, to set a text in the statusbar of the window(s)
195  * hosting this part
196  */
197  void setStatusBarText(const QString &text);
198 
199 protected:
200  /**
201  * Set the main widget.
202  *
203  * Call this in the Part-inherited class constructor.
204  */
205  virtual void setWidget(QWidget *widget);
206 
207  /**
208  * @internal
209  */
210  void customEvent(QEvent *event) override;
211 
212  /**
213  * Convenience method which is called when the Part received a PartActivateEvent .
214  * Reimplement this if you don't want to reimplement event and test for the event yourself
215  * or even install an event filter.
216  */
217  virtual void partActivateEvent(PartActivateEvent *event);
218 
219 #if KPARTS_BUILD_DEPRECATED_SINCE(5, 72)
220  /**
221  * Convenience method which is called when the Part received a
222  * PartSelectEvent .
223  * Reimplement this if you don't want to reimplement event and
224  * test for the event yourself or even install an event filter.
225  *
226  * @deprecated Since 5.72, for lack of usage.
227  */
228  virtual void partSelectEvent(PartSelectEvent *event);
229 #endif
230 
231  /**
232  * Convenience method which is called when the Part received a
233  * GUIActivateEvent .
234  * Reimplement this if you don't want to reimplement event and
235  * test for the event yourself or even install an event filter.
236  */
237  virtual void guiActivateEvent(GUIActivateEvent *event);
238 
239  /**
240  * Convenience method for KXMLGUIFactory::container.
241  * @return a container widget owned by the Part's GUI.
242  */
243  QWidget *hostContainer(const QString &containerName);
244 
245  /**
246  * Load this part's plugins now.
247  * Call this at the end of the part constructor, unless you are still using the
248  * deprecated setComponentData(componentData, true)).
249  * @since 4.1
250  */
251  void loadPlugins();
252  using PartBase::loadPlugins;
253 
254  /**
255  * Set the meta data for this part.
256  *
257  * Call this at the begin of the part constructor.
258  *
259  * @since 5.77
260  */
261  void setMetaData(const KPluginMetaData &metaData);
262 
263 protected Q_SLOTS:
264  /**
265  * @internal
266  */
267  void slotWidgetDestroyed();
268 
269 protected:
270  Part(PartPrivate &dd, QObject *parent);
271 
272 private:
273  Q_DISABLE_COPY(Part)
274 };
275 
276 } // namespace
277 
278 #endif
This event is sent by the part manager when the active part changes.
Base class for parts.
Definition: part.h:62
void loadPlugins(QObject *parent, KXMLGUIClient *parentGUIClient, const KAboutData &aboutData)
Load the Plugins honoring the PluginLoadingMode.
Definition: partbase.cpp:82
Base class for all parts.
Definition: partbase.h:38
This event is sent to a Part when its GUI has been activated or deactivated.
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 event is sent when a part is selected or deselected.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Sep 25 2021 22:55:55 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.