KParts

part.h
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 _KPARTS_PART_H
10 #define _KPARTS_PART_H
11 
12 #include <KPluginMetaData>
13 #include <kparts/partbase.h>
14 
15 class QWidget;
16 class QEvent;
17 class QPoint;
18 
19 /**
20  * The KParts namespace,
21  */
22 namespace KParts
23 {
24 class PartManager;
25 class PartPrivate;
26 class PartActivateEvent;
27 class GUIActivateEvent;
28 
29 /**
30  * @class Part part.h <KParts/Part>
31  *
32  * @short Base class for parts.
33  *
34  * A "part" is a GUI component, featuring:
35  * @li A widget embeddedable in any application.
36  * @li GUI elements that will be merged in the "host" user interface
37  * (menubars, toolbars... ).
38  *
39  * <b>About the widget:</b>\n
40  *
41  * Note that KParts::Part does not inherit QWidget.
42  * This is due to the fact that the "visual representation"
43  * will probably not be a mere QWidget, but an elaborate one.
44  * That's why when implementing your KParts::Part (or derived)
45  * you should call KParts::Part::setWidget() in your constructor.
46  *
47  * <b>About the GUI elements:</b>\n
48  *
49  * Those elements trigger actions, defined by the part ( action()).
50  * The layout of the actions in the GUI is defined by an XML file ( setXMLFile()).
51  *
52  * See also ReadOnlyPart and ReadWritePart, which define the
53  * framework for a "viewer" part and for an "editor"-like part.
54  * Use Part directly only if your part doesn't fit into those.
55  */
56 class KPARTS_EXPORT Part : public QObject, public PartBase
57 {
58  Q_OBJECT
59 
60  KPARTS_DECLARE_PRIVATE(Part)
61 
62 public:
63  /**
64  * Constructor.
65  *
66  * @param parent Parent object of the part.
67  * @param data KPluginMetaData associated with this part, see Part::metaData()
68  */
69  explicit Part(QObject *parent = nullptr, const KPluginMetaData &data = {});
70 
71  /**
72  * Destructor.
73  */
74  ~Part() override;
75 
76  /**
77  * @return The widget defined by this part, set by setWidget().
78  */
79  virtual QWidget *widget();
80 
81  /**
82  * @internal
83  * Used by the part manager.
84  */
85  virtual void setManager(PartManager *manager);
86 
87  /**
88  * Returns the part manager handling this part, if any (0L otherwise).
89  */
90  PartManager *manager() const;
91 
92  /**
93  * By default, the widget is deleted by the part when the part is deleted.
94  * The hosting application can call setAutoDeleteWidget(false) to
95  * disable this behavior, given that the widget is usually deleted by
96  * its parent widget anyway.
97  * This is a method for the hosting application only, Part subclasses
98  * should never call this.
99  */
100  void setAutoDeleteWidget(bool autoDeleteWidget);
101 
102  /**
103  * By default, the part deletes itself when its widget is deleted.
104  * The hosting application can call setAutoDeletePart(false) to
105  * disable this behavior, to be able to delete the widget and then the part,
106  * independently.
107  * This is a method for the hosting application only, Part subclasses
108  * should never call this.
109  */
110  void setAutoDeletePart(bool autoDeletePart);
111 
112  /**
113  * Returns the part (this, or a child part) at the given global position.
114  * This is called by the part manager to ask whether a part should be activated
115  * when clicking somewhere. In most cases the default implementation is enough.
116  * Reimplement this if your part has child parts in some areas (like in khtml or koffice)
117  * @param widget the part widget being clicked - usually the same as widget(), except in koffice.
118  * @param globalPos the mouse coordinates in global coordinates
119  */
120  virtual Part *hitTest(QWidget *widget, const QPoint &globalPos);
121 
122  /**
123  * @since 5.77
124  */
125  KPluginMetaData metaData() const;
126 
127 Q_SIGNALS:
128  /**
129  * Emitted by the part, to set the caption of the window(s)
130  * hosting this part
131  *
132  * @note this signal has only an effect on the window title if window title
133  * handling is enabled @see KParts::MainWindow::setWindowTitleHandling
134  */
135  void setWindowCaption(const QString &caption);
136  /**
137  * Emitted by the part, to set a text in the statusbar of the window(s)
138  * hosting this part
139  */
140  void setStatusBarText(const QString &text);
141 
142 protected:
143  /**
144  * Set the main widget.
145  *
146  * Call this in the Part-inherited class constructor.
147  */
148  virtual void setWidget(QWidget *widget);
149 
150  /**
151  * @internal
152  */
153  void customEvent(QEvent *event) override;
154 
155  /**
156  * Convenience method which is called when the Part received a PartActivateEvent .
157  * Reimplement this if you don't want to reimplement event and test for the event yourself
158  * or even install an event filter.
159  */
160  virtual void partActivateEvent(PartActivateEvent *event);
161 
162  /**
163  * Convenience method which is called when the Part received a
164  * GUIActivateEvent .
165  * Reimplement this if you don't want to reimplement event and
166  * test for the event yourself or even install an event filter.
167  */
168  virtual void guiActivateEvent(GUIActivateEvent *event);
169 
170  /**
171  * Convenience method for KXMLGUIFactory::container.
172  * @return a container widget owned by the Part's GUI.
173  */
174  QWidget *hostContainer(const QString &containerName);
175 
176 protected Q_SLOTS:
177  /**
178  * @internal
179  */
180  void slotWidgetDestroyed();
181 
182 protected:
183  KPARTS_NO_EXPORT Part(PartPrivate &dd, QObject *parent);
184 
185 private:
186  Q_DISABLE_COPY(Part)
187 };
188 
189 } // namespace
190 
191 #endif
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:34
Base class for parts.
Definition: part.h:56
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-2024 The KDE developers.
Generated on Thu Feb 15 2024 03:48:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.