1/* This file is part of the KDE libraries
2 Copyright (C) 2001 Christoph Cullmann <cullmann@kde.org>
3 Copyright (C) 2005 Dominik Haumann (dhdev@gmx.de) (documentation)
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21
22#ifndef KDELIBS_KTEXTEDITOR_PLUGIN_H
23#define KDELIBS_KTEXTEDITOR_PLUGIN_H
24
25#include <QtCore/QObject>
26
27#include <ktexteditor/ktexteditor_export.h>
28#include <kservice.h>
29
30class KConfig;
31
32namespace KTextEditor
33{
34
35class Document;
36class View;
37
38/**
39 * \brief KTextEditor Plugin interface.
40 *
41 * Topics:
42 * - \ref plugin_intro
43 * - \ref plugin_config
44 * - \ref plugin_sessions
45 * - \ref plugin_arch
46 *
47 * \section plugin_intro Introduction
48 *
49 * The Plugin class provides methods to create loadable plugins for all
50 * KTextEditor implementations. A plugin can handle several documents and
51 * views. For every document the plugin should handle addDocument() is called
52 * and for every view addView().
53 *
54 * \section plugin_config Configuration Management
55 *
56 * @todo write docu about config pages (new with kpluginmanager)
57 * @todo write docu about save/load settings (related to config page)
58 *
59 * \section plugin_sessions Session Management
60 *
61 * As an extension a Plugin can implement the SessionConfigInterface. This
62 * interface provides functions to read and write session related settings.
63 * If you have session dependent data additionally derive your Plugin from
64 * this interface and implement the session related functions, for example:
65 * \code
66 * class MyPlugin : public KTextEditor::Plugin,
67 * public KTextEditor::SessionConfigInterface
68 * {
69 * Q_OBJECT
70 * Q_INTERFACES(KTextEditor::SessionConfigInterface)
71 *
72 * // ...
73 * virtual void readSessionConfig (const KConfigGroup& config);
74 * virtual void writeSessionConfig (KConfigGroup& config);
75 * };
76 * \endcode
77 *
78 * \section plugin_arch Plugin Architecture
79 *
80 * After the plugin is loaded the editor implementation should call
81 * addDocument() and addView() for all documents and views the plugin should
82 * handle. If your plugin has a GUI it is common to add an extra class, like:
83 * \code
84 * class PluginView : public QObject, public KXMLGUIClient
85 * {
86 * Q_OBJECT
87 * public:
88 * // Constructor and other methods
89 * PluginView( KTextEditor::View* view )
90 * : QObject( view ), KXMLGUIClient( view ), m_view( view )
91 * { ... }
92 * // ...
93 * private:
94 * KTextEditor::View* m_view;
95 * };
96 * \endcode
97 * Your KTextEditor::Plugin derived class then will create a new PluginView
98 * for every View, i.e. for every call of addView().
99 *
100 * The method removeView() will be called whenever a View is removed/closed.
101 * If you have a PluginView for every view this is the place to remove it.
102 *
103 * \see KTextEditor::Editor, KTextEditor::Document, KTextEditor::View,
104 * KTextEditor::SessionConfigInterface
105 * \author Christoph Cullmann \<cullmann@kde.org\>
106 */
107class KTEXTEDITOR_EXPORT Plugin : public QObject
108{
109 Q_OBJECT
110
111 public:
112 /**
113 * Constructor.
114 *
115 * Create a new plugin.
116 * \param parent parent object
117 */
118 Plugin ( QObject *parent );
119
120 /**
121 * Virtual destructor.
122 */
123 virtual ~Plugin ();
124
125 /*
126 * Following methodes allow the plugin to react on view and document
127 * creation.
128 */
129 public:
130 /**
131 * Add a new \p document to the plugin.
132 * This method is called whenever the plugin should handle another
133 * \p document.
134 *
135 * For every call of addDocument() will finally follow a call of
136 * removeDocument(), i.e. the number of calls are identic.
137 *
138 * \param document new document to handle
139 * \see removeDocument(), addView()
140 */
141 virtual void addDocument (Document *document) { Q_UNUSED(document); }
142
143 /**
144 * Remove the \p document from the plugin.
145 * This method is called whenever the plugin should stop handling
146 * the \p document.
147 *
148 * For every call of addDocument() will finally follow a call of
149 * removeDocument(), i.e. the number of calls are identic.
150 *
151 * \param document document to hang the gui out from
152 * \see addDocument(), removeView()
153 */
154 virtual void removeDocument (Document *document) { Q_UNUSED(document); }
155
156 /**
157 * This method is called whenever the plugin should add its GUI to
158 * \p view.
159 * The process for the Editor can be roughly described as follows:
160 * - add documents the plugin should handle via addDocument()
161 * - for every document \e doc call addView() for \e every view for
162 * \e doc.
163 *
164 * For every call of addView() will finally follow a call of
165 * removeView(), i.e. the number of calls are identic.
166 *
167 * \note As addView() is called for \e every view in which the plugin's
168 * GUI should be visible you must \e not add the GUI by
169 * iterating over all Document::views() yourself neither use the
170 * signal Document::viewCreated().
171 *
172 * \param view view to hang the gui in
173 * \see removeView(), addDocument()
174 */
175 virtual void addView (View *view) { Q_UNUSED(view); }
176
177 /**
178 * This method is called whenever the plugin should remove its GUI from
179 * \p view.
180 *
181 * For every call of addView() will finally follow a call of
182 * removeView(), i.e. the number of calls are identic.
183 *
184 * \param view view to hang the gui out from
185 * \see addView(), removeDocument()
186 */
187 virtual void removeView (View *view) { Q_UNUSED(view); }
188
189 private:
190 class PluginPrivate* const d;
191};
192
193/**
194 * Create a plugin represented by \p service with parent object \p parent.
195 * To get the KService object you usually use KServiceTypeTrader. Example
196 * \code
197 * KService::List list = KServiceTypeTrader::self()->query("KTextEditor/Plugin");
198 *
199 * foreach(const KService::Ptr &service, list) {
200 * // do something with service
201 * }
202 * \endcode
203 * \return the plugin or NULL if it could not be loaded
204 */
205#ifndef KDE_NO_DEPRECATED
206KTEXTEDITOR_EXPORT_DEPRECATED Plugin *createPlugin ( KService::Ptr service, QObject *parent );
207#endif
208
209}
210
211#endif
212
213// kate: space-indent on; indent-width 2; replace-tabs on;
214