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 #if KPARTS_ENABLE_DEPRECATED_SINCE(5, 90)
246  /**
247  * Load this part's plugins now.
248  * Call this at the end of the part constructor, unless you are still using the
249  * deprecated setComponentData(componentData, true)).
250  * @since 4.1
251  * @deprecated Since 5.90, the concept of KPart plugins is deprecated, see docs of @ref KParts::Plugin class
252  */
253  KPARTS_DEPRECATED_VERSION(5, 90, "The concept of KPart plugins is deprecated, see docs of KParts::Plugin class")
254  void loadPlugins();
255  using PartBase::loadPlugins;
256 #endif
257 
258  /**
259  * Set the meta data for this part.
260  *
261  * Call this at the begin of the part constructor.
262  *
263  * @since 5.77
264  */
265  void setMetaData(const KPluginMetaData &metaData);
266 
267 protected Q_SLOTS:
268  /**
269  * @internal
270  */
271  void slotWidgetDestroyed();
272 
273 protected:
274  Part(PartPrivate &dd, QObject *parent);
275 
276 private:
277  Q_DISABLE_COPY(Part)
278 };
279 
280 } // namespace
281 
282 #endif
This event is sent when a part is selected or deselected.
The part manager is an object which knows about a collection of parts (even nested ones) and handles ...
Definition: partmanager.h:36
This event is sent to a Part when its GUI has been activated or deactivated. This is related to PartA...
Base class for all parts.
Definition: partbase.h:38
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
This event is sent by the part manager when the active part changes. Each time the active part change...
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat May 21 2022 03:48:10 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.