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 KTextEditor::Plugin
22 * \inmodule KTextEditor
23 * \inheaderfile KTextEditor/Plugin
24 *
25 * \brief KTextEditor Plugin interface.
26 *
27 * \target plugin_intro
28 * \section1 Introduction
29 *
30 * The Plugin class provides methods to create loadable plugins for the
31 * KTextEditor framework. The Plugin class itself a function createView()
32 * that is called for each MainWindow. In createView(), the plugin is
33 * responsible to create tool views through MainWindow::createToolView(),
34 * hook itself into the menus and toolbars through KXMLGuiClient, and attach
35 * itself to Views or Documents.
36 *
37 * \target plugin_config_pages
38 * \section1 Plugin Config Pages
39 *
40 * If your plugin needs config pages, override the functions configPages()
41 * and configPage() in your plugin as follows:
42 * \code
43 * class MyPlugin : public KTextEditor::Plugin
44 * {
45 * Q_OBJECT
46 * public:
47 * // ...
48 * int configPages() const override;
49 * ConfigPage *configPage(int number, QWidget *parent) override;
50 * };
51 * \endcode
52 * The host application will call configPage() for each config page.
53 *
54 * \target plugin_sessions
55 * \section1 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 * \sa KTextEditor::SessionConfigInterface, KTextEditor::ConfigPage,
75 * KTextEditor::MainWindow, kte_plugin_hosting
76 */
77class KTEXTEDITOR_EXPORT Plugin : public QObject
78{
79 Q_OBJECT
80
81public:
82 /*!
83 * Constructor.
84 *
85 * Create a new application plugin.
86 *
87 * \a parent is the parent object
88 *
89 */
90 Plugin(QObject *parent);
91
92 /*!
93 * Virtual destructor.
94 */
95 ~Plugin() override;
96
97 /*!
98 * Create a new View for this plugin for the given KTextEditor::MainWindow.
99 * This may be called arbitrary often by the application to create as much
100 * views as MainWindows exist. The application will take care to delete
101 * a view whenever a MainWindow is closed, so you do not need to handle
102 * deletion of the view yourself in the plugin.
103 *
104 * \note Session configuration: The host application will try to cast the
105 * returned QObject with \a qobject_cast into the SessionConfigInterface.
106 * This way, not only your Plugin, but also each Plugin view can have
107 * session related settings.
108 *
109 * \a mainWindow is the MainWindow for which a view should be created
110 *
111 * Returns the new created view or NULL
112 * \sa SessionConfigInterface
113 */
114 virtual QObject *createView(KTextEditor::MainWindow *mainWindow) = 0;
115
116 /*!
117 * Get the number of available config pages.
118 *
119 * If a number < 1 is returned, it does not support config pages.
120 *
121 * Returns number of config pages, default implementation says 0
122 * \sa configPage()
123 */
124 virtual int configPages() const;
125
126 /*!
127 * Get the config page with the \a number, config pages from 0 to
128 * configPages()-1 are available if configPages() > 0.
129 *
130 * \a number is the index of config page
131 *
132 * \a parent is the parent widget for config page
133 *
134 * Returns created config page or NULL, if the number is out of bounds, default implementation returns NULL
135 * \sa configPages()
136 */
137 virtual ConfigPage *configPage(int number, QWidget *parent);
138
139private:
140 class PluginPrivate *const d;
141};
142
143}
144
145#endif
146

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