File indexing completed on 2024-05-12 15:45:41
0001 /* 0002 SPDX-FileCopyrightText: 2001-2014 Christoph Cullmann <cullmann@kde.org> 0003 SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <dhaumann@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KTEXTEDITOR_PLUGIN_H 0009 #define KTEXTEDITOR_PLUGIN_H 0010 0011 #include <QObject> 0012 0013 #include <ktexteditor_export.h> 0014 0015 namespace KTextEditor 0016 { 0017 class ConfigPage; 0018 class MainWindow; 0019 0020 /** 0021 * \class Plugin plugin.h <KTextEditor/Plugin> 0022 * 0023 * \brief KTextEditor Plugin interface. 0024 * 0025 * Topics: 0026 * - \ref plugin_intro 0027 * - \ref plugin_config_pages 0028 * - \ref plugin_sessions 0029 * 0030 * \section plugin_intro Introduction 0031 * 0032 * The Plugin class provides methods to create loadable plugins for the 0033 * KTextEditor framework. The Plugin class itself a function createView() 0034 * that is called for each MainWindow. In createView(), the plugin is 0035 * responsible to create tool views through MainWindow::createToolView(), 0036 * hook itself into the menus and toolbars through KXMLGuiClient, and attach 0037 * itself to View%s or Document%s. 0038 * 0039 * \section plugin_config_pages Plugin Config Pages 0040 * 0041 * If your plugin needs config pages, override the functions configPages() 0042 * and configPage() in your plugin as follows: 0043 * \code 0044 * class MyPlugin : public KTextEditor::Plugin 0045 * { 0046 * Q_OBJECT 0047 * public: 0048 * // ... 0049 * int configPages() const override; 0050 * ConfigPage *configPage(int number, QWidget *parent) override; 0051 * }; 0052 * \endcode 0053 * The host application will call configPage() for each config page. 0054 * 0055 * \section plugin_sessions Session Management 0056 * 0057 * As an extension a Plugin can implement the SessionConfigInterface. This 0058 * interface provides functions to read and write session related settings. 0059 * If you have session dependent data additionally derive your Plugin from 0060 * this interface and implement the session related functions, for example: 0061 * \code 0062 * class MyPlugin : public KTextEditor::Plugin, 0063 * public KTextEditor::SessionConfigInterface 0064 * { 0065 * Q_OBJECT 0066 * Q_INTERFACES(KTextEditor::SessionConfigInterface) 0067 * public: 0068 * // ... 0069 * void readSessionConfig (const KConfigGroup& config) override; 0070 * void writeSessionConfig (KConfigGroup& config) override; 0071 * }; 0072 * \endcode 0073 * 0074 * \see KTextEditor::SessionConfigInterface, KTextEditor::ConfigPage, 0075 * KTextEditor::MainWindow 0076 * \author Christoph Cullmann \<cullmann@kde.org\> 0077 */ 0078 class KTEXTEDITOR_EXPORT Plugin : public QObject 0079 { 0080 Q_OBJECT 0081 0082 public: 0083 /** 0084 * Constructor. 0085 * 0086 * Create a new application plugin. 0087 * \param parent parent object 0088 */ 0089 Plugin(QObject *parent); 0090 0091 /** 0092 * Virtual destructor. 0093 */ 0094 ~Plugin() override; 0095 0096 /** 0097 * Create a new View for this plugin for the given KTextEditor::MainWindow. 0098 * This may be called arbitrary often by the application to create as much 0099 * views as MainWindow%s exist. The application will take care to delete 0100 * a view whenever a MainWindow is closed, so you do not need to handle 0101 * deletion of the view yourself in the plugin. 0102 * 0103 * \note Session configuration: The host application will try to cast the 0104 * returned QObject with \p qobject_cast into the SessionConfigInterface. 0105 * This way, not only your Plugin, but also each Plugin view can have 0106 * session related settings. 0107 * 0108 * \param mainWindow the MainWindow for which a view should be created 0109 * \return the new created view or NULL 0110 * @see SessionConfigInterface 0111 */ 0112 virtual QObject *createView(KTextEditor::MainWindow *mainWindow) = 0; 0113 0114 /** 0115 * Get the number of available config pages. 0116 * If a number < 1 is returned, it does not support config pages. 0117 * \return number of config pages, default implementation says 0 0118 * \see configPage() 0119 */ 0120 virtual int configPages() const; 0121 0122 /** 0123 * Get the config page with the \p number, config pages from 0 to 0124 * configPages()-1 are available if configPages() > 0. 0125 * \param number index of config page 0126 * \param parent parent widget for config page 0127 * \return created config page or NULL, if the number is out of bounds, default implementation returns NULL 0128 * \see configPages() 0129 */ 0130 virtual ConfigPage *configPage(int number, QWidget *parent); 0131 0132 private: 0133 class PluginPrivate *const d; 0134 }; 0135 0136 } 0137 0138 #endif