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
28class KConfig;
29class QString;
30
31namespace 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 */
88class 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/*
150class EditorChooserBackEnd: public ComponentChooserPlugin {
151
152Q_OBJECT
153public:
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
164public 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