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

source code of kparts/src/part.h