1/*
2 SPDX-FileCopyrightText: 2001-2014 Christoph Cullmann <cullmann@kde.org>
3 SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <dhaumann@kde.org>
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
15namespace KTextEditor
16{
17class ConfigPage;
18class 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, \ref kte_plugin_hosting
76 * \author Christoph Cullmann \<cullmann@kde.org\>
77 */
78class KTEXTEDITOR_EXPORT Plugin : public QObject
79{
80 Q_OBJECT
81
82public:
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
132private:
133 class PluginPrivate *const d;
134};
135
136}
137
138#endif
139

source code of ktexteditor/src/include/ktexteditor/plugin.h