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 * The KParts namespace,
21 */
22namespace KParts
23{
24class PartManager;
25class PartPrivate;
26class PartActivateEvent;
27class 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 */
56class KPARTS_EXPORT Part : public QObject, public PartBase
57{
58 Q_OBJECT
59
60 KPARTS_DECLARE_PRIVATE(Part)
61
62public:
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
127Q_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
142protected:
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
176protected Q_SLOTS:
177 /**
178 * @internal
179 */
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