File indexing completed on 2024-05-19 07:45:48
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0004 SPDX-FileCopyrightText: 1999 David Faure <faure@kde.org> 0005 0006 SPDX-License-Identifier: LGPL-2.0-or-later 0007 */ 0008 0009 #ifndef _KPARTS_PART_H 0010 #define _KPARTS_PART_H 0011 0012 #include <KPluginMetaData> 0013 #include <kparts/partbase.h> 0014 0015 class QWidget; 0016 class QEvent; 0017 class QPoint; 0018 0019 /** 0020 * The KParts namespace, 0021 */ 0022 namespace KParts 0023 { 0024 class PartManager; 0025 class PartPrivate; 0026 class PartActivateEvent; 0027 class GUIActivateEvent; 0028 0029 /** 0030 * @class Part part.h <KParts/Part> 0031 * 0032 * @short Base class for parts. 0033 * 0034 * A "part" is a GUI component, featuring: 0035 * @li A widget embeddedable in any application. 0036 * @li GUI elements that will be merged in the "host" user interface 0037 * (menubars, toolbars... ). 0038 * 0039 * <b>About the widget:</b>\n 0040 * 0041 * Note that KParts::Part does not inherit QWidget. 0042 * This is due to the fact that the "visual representation" 0043 * will probably not be a mere QWidget, but an elaborate one. 0044 * That's why when implementing your KParts::Part (or derived) 0045 * you should call KParts::Part::setWidget() in your constructor. 0046 * 0047 * <b>About the GUI elements:</b>\n 0048 * 0049 * Those elements trigger actions, defined by the part ( action()). 0050 * The layout of the actions in the GUI is defined by an XML file ( setXMLFile()). 0051 * 0052 * See also ReadOnlyPart and ReadWritePart, which define the 0053 * framework for a "viewer" part and for an "editor"-like part. 0054 * Use Part directly only if your part doesn't fit into those. 0055 */ 0056 class KPARTS_EXPORT Part : public QObject, public PartBase 0057 { 0058 Q_OBJECT 0059 0060 KPARTS_DECLARE_PRIVATE(Part) 0061 0062 public: 0063 /** 0064 * Constructor. 0065 * 0066 * @param parent Parent object of the part. 0067 * @param data KPluginMetaData associated with this part, see Part::metaData() 0068 */ 0069 explicit Part(QObject *parent = nullptr, const KPluginMetaData &data = {}); 0070 0071 /** 0072 * Destructor. 0073 */ 0074 ~Part() override; 0075 0076 /** 0077 * @return The widget defined by this part, set by setWidget(). 0078 */ 0079 virtual QWidget *widget(); 0080 0081 /** 0082 * @internal 0083 * Used by the part manager. 0084 */ 0085 virtual void setManager(PartManager *manager); 0086 0087 /** 0088 * Returns the part manager handling this part, if any (0L otherwise). 0089 */ 0090 PartManager *manager() const; 0091 0092 /** 0093 * By default, the widget is deleted by the part when the part is deleted. 0094 * The hosting application can call setAutoDeleteWidget(false) to 0095 * disable this behavior, given that the widget is usually deleted by 0096 * its parent widget anyway. 0097 * This is a method for the hosting application only, Part subclasses 0098 * should never call this. 0099 */ 0100 void setAutoDeleteWidget(bool autoDeleteWidget); 0101 0102 /** 0103 * By default, the part deletes itself when its widget is deleted. 0104 * The hosting application can call setAutoDeletePart(false) to 0105 * disable this behavior, to be able to delete the widget and then the part, 0106 * independently. 0107 * This is a method for the hosting application only, Part subclasses 0108 * should never call this. 0109 */ 0110 void setAutoDeletePart(bool autoDeletePart); 0111 0112 /** 0113 * Returns the part (this, or a child part) at the given global position. 0114 * This is called by the part manager to ask whether a part should be activated 0115 * when clicking somewhere. In most cases the default implementation is enough. 0116 * Reimplement this if your part has child parts in some areas (like in khtml or koffice) 0117 * @param widget the part widget being clicked - usually the same as widget(), except in koffice. 0118 * @param globalPos the mouse coordinates in global coordinates 0119 */ 0120 virtual Part *hitTest(QWidget *widget, const QPoint &globalPos); 0121 0122 /** 0123 * @since 5.77 0124 */ 0125 KPluginMetaData metaData() const; 0126 0127 Q_SIGNALS: 0128 /** 0129 * Emitted by the part, to set the caption of the window(s) 0130 * hosting this part 0131 * 0132 * @note this signal has only an effect on the window title if window title 0133 * handling is enabled @see KParts::MainWindow::setWindowTitleHandling 0134 */ 0135 void setWindowCaption(const QString &caption); 0136 /** 0137 * Emitted by the part, to set a text in the statusbar of the window(s) 0138 * hosting this part 0139 */ 0140 void setStatusBarText(const QString &text); 0141 0142 protected: 0143 /** 0144 * Set the main widget. 0145 * 0146 * Call this in the Part-inherited class constructor. 0147 */ 0148 virtual void setWidget(QWidget *widget); 0149 0150 /** 0151 * @internal 0152 */ 0153 void customEvent(QEvent *event) override; 0154 0155 /** 0156 * Convenience method which is called when the Part received a PartActivateEvent . 0157 * Reimplement this if you don't want to reimplement event and test for the event yourself 0158 * or even install an event filter. 0159 */ 0160 virtual void partActivateEvent(PartActivateEvent *event); 0161 0162 /** 0163 * Convenience method which is called when the Part received a 0164 * GUIActivateEvent . 0165 * Reimplement this if you don't want to reimplement event and 0166 * test for the event yourself or even install an event filter. 0167 */ 0168 virtual void guiActivateEvent(GUIActivateEvent *event); 0169 0170 /** 0171 * Convenience method for KXMLGUIFactory::container. 0172 * @return a container widget owned by the Part's GUI. 0173 */ 0174 QWidget *hostContainer(const QString &containerName); 0175 0176 protected Q_SLOTS: 0177 /** 0178 * @internal 0179 */ 0180 void slotWidgetDestroyed(); 0181 0182 protected: 0183 KPARTS_NO_EXPORT Part(PartPrivate &dd, QObject *parent); 0184 0185 private: 0186 Q_DISABLE_COPY(Part) 0187 }; 0188 0189 } // namespace 0190 0191 #endif