KTextEditor

plugin.h
1 /*
2  SPDX-FileCopyrightText: 2001-2014 Christoph Cullmann <[email protected]>
3  SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KTEXTEDITOR_PLUGIN_H
9 #define KTEXTEDITOR_PLUGIN_H
10 
11 #include <QObject>
12 
13 #include <ktexteditor_export.h>
14 
15 namespace KTextEditor
16 {
17 class ConfigPage;
18 class MainWindow;
19 
20 /**
21  * \class Plugin plugin.h <KTextEditor/Plugin>
22  *
23  * \brief KTextEditor Plugin interface.
24  *
25  * Topics:
26  * - \ref plugin_intro
27  * - \ref plugin_config_pages
28  * - \ref plugin_sessions
29  *
30  * \section plugin_intro Introduction
31  *
32  * The Plugin class provides methods to create loadable plugins for the
33  * KTextEditor framework. The Plugin class itself a function createView()
34  * that is called for each MainWindow. In createView(), the plugin is
35  * responsible to create tool views through MainWindow::createToolView(),
36  * hook itself into the menus and toolbars through KXMLGuiClient, and attach
37  * itself to View%s or Document%s.
38  *
39  * \section plugin_config_pages Plugin Config Pages
40  *
41  * If your plugin needs config pages, override the functions configPages()
42  * and configPage() in your plugin as follows:
43  * \code
44  * class MyPlugin : public KTextEditor::Plugin
45  * {
46  * Q_OBJECT
47  * public:
48  * // ...
49  * int configPages() const override;
50  * ConfigPage *configPage(int number, QWidget *parent) override;
51  * };
52  * \endcode
53  * The host application will call configPage() for each config page.
54  *
55  * \section plugin_sessions Session Management
56  *
57  * As an extension a Plugin can implement the SessionConfigInterface. This
58  * interface provides functions to read and write session related settings.
59  * If you have session dependent data additionally derive your Plugin from
60  * this interface and implement the session related functions, for example:
61  * \code
62  * class MyPlugin : public KTextEditor::Plugin,
63  * public KTextEditor::SessionConfigInterface
64  * {
65  * Q_OBJECT
66  * Q_INTERFACES(KTextEditor::SessionConfigInterface)
67  * public:
68  * // ...
69  * void readSessionConfig (const KConfigGroup& config) override;
70  * void writeSessionConfig (KConfigGroup& config) override;
71  * };
72  * \endcode
73  *
74  * \see KTextEditor::SessionConfigInterface, KTextEditor::ConfigPage,
75  * KTextEditor::MainWindow
76  * \author Christoph Cullmann <[email protected]>
77  */
78 class KTEXTEDITOR_EXPORT Plugin : public QObject
79 {
80  Q_OBJECT
81 
82 public:
83  /**
84  * Constructor.
85  *
86  * Create a new application plugin.
87  * \param parent parent object
88  */
89  Plugin(QObject *parent);
90 
91  /**
92  * Virtual destructor.
93  */
94  ~Plugin() override;
95 
96  /**
97  * Create a new View for this plugin for the given KTextEditor::MainWindow.
98  * This may be called arbitrary often by the application to create as much
99  * views as MainWindow%s exist. The application will take care to delete
100  * a view whenever a MainWindow is closed, so you do not need to handle
101  * deletion of the view yourself in the plugin.
102  *
103  * \note Session configuration: The host application will try to cast the
104  * returned QObject with \p qobject_cast into the SessionConfigInterface.
105  * This way, not only your Plugin, but also each Plugin view can have
106  * session related settings.
107  *
108  * \param mainWindow the MainWindow for which a view should be created
109  * \return the new created view or NULL
110  * @see SessionConfigInterface
111  */
112  virtual QObject *createView(KTextEditor::MainWindow *mainWindow) = 0;
113 
114  /**
115  * Get the number of available config pages.
116  * If a number < 1 is returned, it does not support config pages.
117  * \return number of config pages, default implementation says 0
118  * \see configPage()
119  */
120  virtual int configPages() const;
121 
122  /**
123  * Get the config page with the \p number, config pages from 0 to
124  * configPages()-1 are available if configPages() > 0.
125  * \param number index of config page
126  * \param parent parent widget for config page
127  * \return created config page or NULL, if the number is out of bounds, default implementation returns NULL
128  * \see configPages()
129  */
130  virtual ConfigPage *configPage(int number, QWidget *parent);
131 
132 private:
133  class PluginPrivate *const d;
134 };
135 
136 }
137 
138 #endif
The KTextEditor namespace contains all the public API that is required to use the KTextEditor compone...
Definition: katetextblock.h:22
KTextEditor Plugin interface.
Definition: plugin.h:78
Config page interface for the Editor and Plugins.
Definition: configpage.h:43
This class allows the application that embeds the KTextEditor component to allow it to access parts o...
Definition: mainwindow.h:43
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Fri Nov 26 2021 22:59:21 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.