1 | /* This file is part of the KDE libraries |
2 | * Copyright (C) 2005 Joseph Wenninger <jowenn@kde.org> |
3 | * |
4 | * This library is free software; you can redistribute it and/or |
5 | * modify it under the terms of the GNU Library General Public |
6 | * License as published by the Free Software Foundation; either |
7 | * version 2 of the License, or (at your option) any later version. |
8 | * |
9 | * This library is distributed in the hope that it will be useful, |
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | * Library General Public License for more details. |
13 | * |
14 | * You should have received a copy of the GNU Library General Public License |
15 | * along with this library; see the file COPYING.LIB. If not, write to |
16 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | * Boston, MA 02110-1301, USA. |
18 | */ |
19 | #ifndef _EDITOR_CHOOSER_H_ |
20 | #define _EDITOR_CHOOSER_H_ |
21 | |
22 | #include <ktexteditor/ktexteditor_export.h> |
23 | #include <ktexteditor/document.h> |
24 | #include <ktexteditor/editor.h> |
25 | |
26 | #include <QtGui/QWidget> |
27 | |
28 | class KConfig; |
29 | class QString; |
30 | |
31 | namespace KTextEditor |
32 | { |
33 | |
34 | /** |
35 | * \brief Editor Component Chooser. |
36 | * |
37 | * Topics: |
38 | * - \ref chooser_intro |
39 | * - \ref chooser_gui |
40 | * - \ref chooser_editor |
41 | * |
42 | * \section chooser_intro Introduction |
43 | * |
44 | * The EditorChooser is responsible for two different tasks: It provides |
45 | * - a GUI, with which the user can choose the preferred editor part |
46 | * - a static accessor, with which the current selected editor part can be |
47 | * obtained. |
48 | * |
49 | * \section chooser_gui The GUI Editor Chooser |
50 | * The EditorChooser is a simple widget with a group box containing an |
51 | * information label and a combo box which lists all available KTextEditor |
52 | * implementations. To give the user the possibility to choose a text editor |
53 | * implementation, create an instance of this class and put it into the GUI: |
54 | * \code |
55 | * KTextEditor::EditorChooser* ec = new KTextEditor::EditorChooser(parent); |
56 | * // read the settings from the application's KConfig object |
57 | * ec->readAppSetting(); |
58 | * // optionally connect the signal changed() |
59 | * // plug the widget into a layout |
60 | * layout->addWidget(ec); |
61 | * \endcode |
62 | * Later, for example when the user clicks the Apply-button: |
63 | * \code |
64 | * // save the user's choice |
65 | * ec->writeAppSetting(); |
66 | * \endcode |
67 | * After this, the static accessor editor() will return the new editor part |
68 | * object. Now, either the application has to be restarted, or you need code |
69 | * that closes all current documents so that you can safely switch and use the |
70 | * new editor part. Restarting is probably much easier. |
71 | * |
72 | * \note If you do not put the EditorChooser into the GUI, the default editor |
73 | * component will be used. The default editor is configurable in KDE's |
74 | * control center in |
75 | * "KDE Components > Component Chooser > Embedded Text Editor". |
76 | * |
77 | * \section chooser_editor Accessing the Editor Part |
78 | * The call of editor() will return the currently used editor part, either the |
79 | * KDE default or the one configured with the EditorChooser's GUI |
80 | * (see \ref chooser_gui). Example: |
81 | * \code |
82 | * KTextEditor::Editor* editor = KTextEditor::EditorChooser::editor(); |
83 | * \endcode |
84 | * |
85 | * \see KTextEditor::Editor |
86 | * \author Joseph Wenninger \<jowenn@kde.org\> |
87 | */ |
88 | class KTEXTEDITOR_EXPORT EditorChooser: public QWidget |
89 | { |
90 | friend class PrivateEditorChooser; |
91 | |
92 | Q_OBJECT |
93 | |
94 | public: |
95 | /** |
96 | * Constructor. |
97 | * |
98 | * Create an editor chooser widget. |
99 | * \param parent the parent widget |
100 | */ |
101 | EditorChooser(QWidget *parent=0); |
102 | /** |
103 | * Destructor. |
104 | */ |
105 | virtual ~EditorChooser(); |
106 | |
107 | /* void writeSysDefault();*/ |
108 | |
109 | /** |
110 | * Read the configuration from the application's config file. The group |
111 | * is handeled internally (it is called "KTEXTEDITOR:", but it is possible |
112 | * to add a string to extend the group name with \p postfix. |
113 | * \param postfix config group postfix string |
114 | * \see writeAppSetting() |
115 | */ |
116 | void readAppSetting(const QString& postfix=QString()); |
117 | /** |
118 | * Write the configuration to the application's config file. |
119 | * \param postfix config group postfix string |
120 | * \see readAppSetting() |
121 | */ |
122 | void writeAppSetting(const QString& postfix=QString()); |
123 | |
124 | /** |
125 | * Static accessor to get the Editor instance of the currently used |
126 | * KTextEditor component. |
127 | * |
128 | * That Editor instance can be qobject-cast to specific extensions. |
129 | * If the result of the cast is not NULL, that extension is supported: |
130 | * |
131 | * \param postfix config group postfix string |
132 | * \param fallBackToKatePart if \e true, the returned Editor component |
133 | * will be a katepart if no other implementation can be found |
134 | * \return Editor controller or NULL, if no editor component could be |
135 | * found |
136 | */ |
137 | static KTextEditor::Editor *editor (const QString& postfix=QString(), bool fallBackToKatePart = true); |
138 | |
139 | Q_SIGNALS: |
140 | /** |
141 | * This signal is emitted whenever the selected item in the combo box |
142 | * changed. |
143 | */ |
144 | void changed(); |
145 | private: |
146 | class PrivateEditorChooser *d; |
147 | }; |
148 | |
149 | /* |
150 | class EditorChooserBackEnd: public ComponentChooserPlugin { |
151 | |
152 | Q_OBJECT |
153 | public: |
154 | EditorChooserBackEnd(QObject *parent=0, const char *name=0); |
155 | virtual ~EditorChooserBackEnd(); |
156 | |
157 | virtual QWidget *widget(QWidget *); |
158 | virtual const QStringList &choices(); |
159 | virtual void saveSettings(); |
160 | |
161 | void readAppSetting(KConfig *cfg,const QString& postfix); |
162 | void writeAppSetting(KConfig *cfg,const QString& postfix); |
163 | |
164 | public Q_SLOTS: |
165 | virtual void madeChoice(int pos,const QString &choice); |
166 | |
167 | }; |
168 | */ |
169 | |
170 | } |
171 | #endif |
172 | |
173 | // kate: space-indent on; indent-width 2; replace-tabs on; |
174 | |