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 | |
30 | class KConfig; |
31 | |
32 | namespace KTextEditor |
33 | { |
34 | |
35 | class Document; |
36 | class 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 | */ |
107 | class 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 |
206 | KTEXTEDITOR_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 | |