1 | /* This file is part of the KDE libraries |
2 | * Copyright (C) 2005 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 | #ifndef KDELIBS_KTEXTEDITOR_EDITOR_H |
21 | #define KDELIBS_KTEXTEDITOR_EDITOR_H |
22 | |
23 | #include <ktexteditor/ktexteditor_export.h> |
24 | // our main baseclass of the KTextEditor::Editor |
25 | #include <QtCore/QObject> |
26 | |
27 | #include <kicon.h> |
28 | |
29 | class KAboutData; |
30 | class KConfig; |
31 | |
32 | namespace KTextEditor |
33 | { |
34 | |
35 | class Document; |
36 | class ConfigPage; |
37 | |
38 | /** |
39 | * \brief Accessor interface for Editor part. |
40 | * |
41 | * Topics: |
42 | * - \ref editor_intro |
43 | * - \ref editor_config |
44 | * - \ref editor_notes |
45 | * - \ref editor_extensions |
46 | * |
47 | * \section editor_intro Introduction |
48 | * |
49 | * The Editor part can be accessed via the KTextEditor::Factory or the |
50 | * KTextEditor::EditorChooser and provides |
51 | * general information and configuration methods for the Editor |
52 | * implementation, for example KAboutData by using aboutData(). |
53 | * |
54 | * The Editor implementation has a list of all opened documents. Get this |
55 | * list with documents(). To create a new Document call createDocument(). The |
56 | * signal documentCreated() is emitted whenever the Editor created a new |
57 | * document. |
58 | * |
59 | * \section editor_config Editor Configuration |
60 | * |
61 | * If the Editor implementation supports a config dialog |
62 | * configDialogSupported() returns \e true, then the config dialog can be |
63 | * shown with configDialog(). Instead of using the config dialog, the config |
64 | * pages can be embedded into the application's config dialog. To do this, |
65 | * configPages() returns the number of |
66 | * config pages the Editor implementation provides and configPage() returns |
67 | * the requested page. Further, a config page has a short descriptive name, |
68 | * get it with configPageName(). You can get more detailed name by using |
69 | * configPageFullName(). Also every config page has a pixmap, get it with |
70 | * configPagePixmap(). The configuration can be saved and loaded with |
71 | * readConfig() and writeConfig(). |
72 | * |
73 | * \note We recommend to embedd the config pages into the main application's |
74 | * config dialog instead of using a separate config dialog, if the config |
75 | * dialog does not look cluttered then. This way, all settings are grouped |
76 | * together in one place. |
77 | * |
78 | * \section editor_notes Implementation Notes |
79 | * |
80 | * Usually only one instance of the Editor exists. The Kate Part |
81 | * implementation internally uses a static accessor to make sure that only one |
82 | * Kate Part Editor object exists. So several factories still use the same |
83 | * Editor. |
84 | * |
85 | * readConfig() and writeConfig() should be forwarded to all loaded plugins |
86 | * as well, see KTextEditor::Plugin::readConfig() and |
87 | * KTextEditor::Plugin::writeConfig(). |
88 | * |
89 | * \section editor_extensions Editor Extension Interfaces |
90 | * |
91 | * There is only a single extension interface for the Editor: the |
92 | * CommandInterface. With the CommandInterface it is possible to add and |
93 | * remove new command line commands which are valid for all documents. Common |
94 | * use cases are for example commands like \e find or setting document |
95 | * variables. For further details read the detailed descriptions in the class |
96 | * KTextEditor::CommandInterface. |
97 | * |
98 | * \see KTextEditor::Factory, KTextEditor::Document, KTextEditor::ConfigPage |
99 | * KTextEditor::Plugin, KTextEditor::CommandInterface |
100 | * \author Christoph Cullmann \<cullmann@kde.org\> |
101 | */ |
102 | class KTEXTEDITOR_EXPORT Editor : public QObject |
103 | { |
104 | Q_OBJECT |
105 | |
106 | public: |
107 | /** |
108 | * Constructor. |
109 | * |
110 | * Create the Editor object with \p parent. |
111 | * \param parent parent object |
112 | */ |
113 | Editor ( QObject *parent ); |
114 | |
115 | /** |
116 | * Virtual destructor. |
117 | */ |
118 | virtual ~Editor (); |
119 | |
120 | /** |
121 | * Switch editor to simple mode for average users |
122 | */ |
123 | public: |
124 | /** |
125 | * Switch the editor to a simple mode which will hide advanced |
126 | * stuff from average user or switch it back to normal mode. |
127 | * This mode will only affect documents/views created after the |
128 | * change. |
129 | * \param on turn simple mode on or not |
130 | */ |
131 | void setSimpleMode (bool on); |
132 | |
133 | /** |
134 | * Query the editor whether simple mode is on or not. |
135 | * \return \e true if simple mode is on, otherwise \e false |
136 | * \see setSimpleMode() |
137 | */ |
138 | bool simpleMode () const; |
139 | |
140 | /* |
141 | * Methods to create and manage the documents. |
142 | */ |
143 | public: |
144 | /** |
145 | * Create a new document object with \p parent. |
146 | * \param parent parent object |
147 | * \return new KTextEditor::Document object |
148 | * \see documents() |
149 | */ |
150 | virtual Document *createDocument ( QObject *parent ) = 0; |
151 | |
152 | /** |
153 | * Get a list of all documents of this editor. |
154 | * \return list of all existing documents |
155 | * \see createDocument() |
156 | */ |
157 | virtual const QList<Document*> &documents () = 0; |
158 | |
159 | /* |
160 | * General Information about this editor. |
161 | */ |
162 | public: |
163 | /** |
164 | * Get the about data of this Editor part. |
165 | * \return about data |
166 | */ |
167 | virtual const KAboutData *aboutData () const = 0; |
168 | |
169 | /** |
170 | * Get the current default encoding for this Editor part. |
171 | * \return default encoding |
172 | * \since 4.5 |
173 | */ |
174 | const QString &defaultEncoding () const; |
175 | |
176 | protected: |
177 | /** |
178 | * Set the current default encoding for this Editor part. |
179 | * Editor part implementation should call this internally on creation and config changes. |
180 | * \param defaultEncoding new default encoding |
181 | * \since 4.5 |
182 | */ |
183 | void setDefaultEncoding (const QString &defaultEncoding); |
184 | |
185 | /* |
186 | * Configuration management. |
187 | */ |
188 | public: |
189 | /** |
190 | * Read editor configuration from KConfig \p config. |
191 | * |
192 | * \note Implementation Notes: If \p config is NULL you should use |
193 | * kapp->config() as a fallback solution. Additionally the |
194 | * readConfig() call should be forwarded to every loaded plugin. |
195 | * \param config config object |
196 | * \see writeConfig() |
197 | */ |
198 | virtual void readConfig (KConfig *config = 0) = 0; |
199 | |
200 | /** |
201 | * Write editor configuration to KConfig \p config. |
202 | * |
203 | * \note Implementation Notes: If \p config is NULL you should use |
204 | * kapp->config() as a fallback solution. Additionally the |
205 | * writeConfig() call should be forwarded to every loaded plugin. |
206 | * \param config config object |
207 | * \see readConfig() |
208 | */ |
209 | virtual void writeConfig (KConfig *config = 0) = 0; |
210 | |
211 | /** |
212 | * Check, whether this editor has a configuration dialog. |
213 | * \return \e true, if the editor has a configuration dialog, |
214 | * otherwise \e false |
215 | * \see configDialog() |
216 | */ |
217 | virtual bool configDialogSupported () const = 0; |
218 | |
219 | /** |
220 | * Show the editor's config dialog, changes will be applied to the |
221 | * editor, but not saved anywhere automagically, call \p writeConfig() |
222 | * to save them. |
223 | * |
224 | * \note Instead of using the config dialog, the config pages can be |
225 | * embedded into your own config dialog by using configPages() and |
226 | * configPage(). |
227 | * \param parent parent widget |
228 | * \see configDialogSupported() |
229 | */ |
230 | virtual void configDialog (QWidget *parent) = 0; |
231 | |
232 | /** |
233 | * Get the number of available config pages. |
234 | * If the editor returns a number < 1, it does not support config pages |
235 | * and the embedding application should use configDialog() instead. |
236 | * \return number of config pages |
237 | * \see configPage(), configDialog() |
238 | */ |
239 | virtual int configPages () const = 0; |
240 | |
241 | /** |
242 | * Get the config page with the \p number, config pages from 0 to |
243 | * configPages()-1 are available if configPages() > 0. |
244 | * \param number index of config page |
245 | * \param parent parent widget for config page |
246 | * \return created config page or NULL, if the number is out of bounds |
247 | * \see configPages() |
248 | */ |
249 | virtual ConfigPage *configPage (int number, QWidget *parent) = 0; |
250 | |
251 | /** |
252 | * Get a readable name for the config page \p number. The name should be |
253 | * translated. |
254 | * \param number index of config page |
255 | * \return name of given page index |
256 | * \see configPageFullName(), configPagePixmap() |
257 | */ |
258 | virtual QString configPageName (int number) const = 0; |
259 | |
260 | /** |
261 | * Get a readable full name for the config page \e number. The name |
262 | * should be translated. |
263 | * |
264 | * Example: If the name is "Filetypes", the full name could be |
265 | * "Filetype Specific Settings". For "Shortcuts" the full name would be |
266 | * something like "Shortcut Configuration". |
267 | * \param number index of config page |
268 | * \return full name of given page index |
269 | * \see configPageName(), configPagePixmap() |
270 | */ |
271 | virtual QString configPageFullName (int number) const = 0; |
272 | |
273 | /** |
274 | * Get a pixmap with \p size for the config page \p number. |
275 | * \param number index of config page |
276 | * \return pixmap for the given page index |
277 | * \see configPageName(), configPageFullName() |
278 | */ |
279 | virtual KIcon configPageIcon (int number) const = 0; |
280 | |
281 | Q_SIGNALS: |
282 | /** |
283 | * The \p editor emits this signal whenever a \p document was successfully |
284 | * created. |
285 | * \param editor editor which created the new document |
286 | * \param document the newly created document instance |
287 | * \see createDocument() |
288 | */ |
289 | void documentCreated (KTextEditor::Editor *editor, |
290 | KTextEditor::Document *document); |
291 | |
292 | private: |
293 | class EditorPrivate* const d; |
294 | }; |
295 | |
296 | |
297 | /** |
298 | * Helper function for the EditorChooser. |
299 | * Usually you do not have to use this function. Instead, use |
300 | * KTextEditor::EditorChooser::editor(). |
301 | * \param libname library name, for example "katepart" |
302 | * \return the Editor object on success, otherwise NULL |
303 | * \see KTextEditor::EditorChooser::editor() |
304 | */ |
305 | KTEXTEDITOR_EXPORT Editor *editor ( const char *libname ); |
306 | |
307 | } |
308 | |
309 | #endif |
310 | |
311 | // kate: space-indent on; indent-width 2; replace-tabs on; |
312 | |