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
29class KAboutData;
30class KConfig;
31
32namespace KTextEditor
33{
34
35class Document;
36class 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 */
102class 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 */
305KTEXTEDITOR_EXPORT Editor *editor ( const char *libname );
306
307}
308
309#endif
310
311// kate: space-indent on; indent-width 2; replace-tabs on;
312