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 | Copyright (C) 2009 Michel Ludwig (michel.ludwig@kdemail.net) |
5 | |
6 | This library is free software; you can redistribute it and/or |
7 | modify it under the terms of the GNU Library General Public |
8 | License as published by the Free Software Foundation; either |
9 | version 2 of the License, or (at your option) any later version. |
10 | |
11 | This library is distributed in the hope that it will be useful, |
12 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | Library General Public License for more details. |
15 | |
16 | You should have received a copy of the GNU Library General Public License |
17 | along with this library; see the file COPYING.LIB. If not, write to |
18 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | Boston, MA 02110-1301, USA. |
20 | */ |
21 | |
22 | #ifndef KDELIBS_KTEXTEDITOR_SESSIONCONFIGINTERFACE_H |
23 | #define KDELIBS_KTEXTEDITOR_SESSIONCONFIGINTERFACE_H |
24 | |
25 | #include <ktexteditor/ktexteditor_export.h> |
26 | |
27 | class KConfigGroup; |
28 | |
29 | #include <QtCore/QObject> |
30 | |
31 | namespace KTextEditor |
32 | { |
33 | |
34 | /** |
35 | * \brief Session config interface extension for the Document, View and Plugin. |
36 | * |
37 | * \ingroup kte_group_doc_extensions |
38 | * \ingroup kte_group_view_extensions |
39 | * \ingroup kte_group_plugin_extensions |
40 | * |
41 | * \section sessionconfig_intro Introduction |
42 | * |
43 | * The SessionConfigInterface is an extension for Documents, Views and Plugins |
44 | * to add support for session-specific configuration settings. |
45 | * readSessionConfig() is called whenever session-specific settings are to be |
46 | * read from the given KConfig* and writeSessionConfig() whenever they are to |
47 | * be written, for example when a session changed or was closed. |
48 | * |
49 | * \note A \e session does not have anything to do with an X-session under Unix. |
50 | * What is meant is rather a context, think of sessions in Kate or |
51 | * projects in KDevelop for example. |
52 | * |
53 | * \section sessionconfig_support Adding Session Support |
54 | * |
55 | * To add support for sessions a KTextEditor implementation has to derive the |
56 | * Document and View class from SessionConfigInterface and reimplement |
57 | * readSessionConfig() and writeSessionConfig(). |
58 | * |
59 | * The same applies to a Plugin, read the detailed description for plugins. |
60 | * |
61 | * \section sessionconfig_access Accessing the SessionConfigInterface |
62 | * |
63 | * The SessionConfigInterface is supposed to be an extension interface for a |
64 | * Document, a View or a Plugin, i.e. the Document/View/Plugin inherits the |
65 | * interface \e provided that it implements the interface. Use qobject_cast to |
66 | * access the interface: |
67 | * \code |
68 | * // object is of type KTextEditor::Document* or View* or Plugin* |
69 | * KTextEditor::SessionConfigInterface *iface = |
70 | * qobject_cast<KTextEditor::SessionConfigInterface*>( object ); |
71 | * |
72 | * if( iface ) { |
73 | * // interface is supported |
74 | * // do stuff |
75 | * } |
76 | * \endcode |
77 | * |
78 | * \see KTextEditor::Document, KTextEditor::View, KTextEditor::Plugin |
79 | * \author Christoph Cullmann \<cullmann@kde.org\> |
80 | * \note KDE5: Replace this interface with ParameterizedSessionConfigInterface |
81 | */ |
82 | class KTEXTEDITOR_EXPORT SessionConfigInterface |
83 | { |
84 | public: |
85 | SessionConfigInterface(); |
86 | |
87 | /** |
88 | * Virtual destructor. |
89 | */ |
90 | virtual ~SessionConfigInterface(); |
91 | |
92 | // |
93 | // SLOTS !!! |
94 | // |
95 | public: |
96 | /** |
97 | * Read session settings from the given \p config. |
98 | * |
99 | * That means for example |
100 | * - a Document should reload the file, restore all marks etc... |
101 | * - a View should scroll to the last position and restore the cursor |
102 | * position etc... |
103 | * - a Plugin should restore session specific settings |
104 | * - If no file is being loaded, because an empty new document is going to be displayed, |
105 | * this function should emit ReadOnlyPart::completed |
106 | * |
107 | * \param config read the session settings from this KConfigGroup |
108 | * \see writeSessionConfig() |
109 | */ |
110 | virtual void readSessionConfig (const KConfigGroup& config) = 0; |
111 | |
112 | /** |
113 | * Write session settings to the \p config. |
114 | * See readSessionConfig() for more details. |
115 | * |
116 | * \param config write the session settings to this KConfigGroup |
117 | * \see readSessionConfig() |
118 | */ |
119 | virtual void writeSessionConfig (KConfigGroup& config) = 0; |
120 | |
121 | private: |
122 | class SessionConfigInterfacePrivate* const d; |
123 | }; |
124 | |
125 | |
126 | /** |
127 | * \brief Parameterized session config interface extension for the Document. |
128 | * |
129 | * \ingroup kte_group_doc_extensions |
130 | * |
131 | * \section parameterizedsessionconfig_intro Introduction |
132 | * |
133 | * The ParameterizedSessionConfigInterface is an extension for Documents |
134 | * to add support for session-specific configuration settings with more fine-grained |
135 | * control over the settings that are manipulated. |
136 | * The readParameterizedSessionConfig() method is called whenever session-specific settings are to be |
137 | * read from the given KConfig* and the writeParameterizedSessionConfig() method whenever they are to |
138 | * be written, for example when a session changed or was closed. |
139 | * |
140 | * \note A \e session does not have anything to do with an X-session under Unix. |
141 | * What is meant is rather a context, think of sessions in Kate or |
142 | * projects in KDevelop for example. |
143 | * |
144 | * \note ParameterizedSessionConfigInterface is meant to be an extension of SessionConfigInterface. |
145 | * Due to limitations with qobject_cast it is not possible in KDE4 to derive this interface |
146 | * from SessionConfigInterface. |
147 | * |
148 | * \section parameterizedsessionconfig_support Adding Session Support |
149 | * |
150 | * To add support for sessions a KTextEditor implementation has to derive the |
151 | * Document class from ParameterizedSessionConfigInterface and reimplement the methods defined |
152 | * in this class. |
153 | * |
154 | * \section parameterizedsessionconfig_access Accessing the ParameterizedSessionConfigInterface |
155 | * |
156 | * The ParameterizedSessionConfigInterface is supposed to be an extension interface for a |
157 | * Document i.e. the Document inherits the |
158 | * interface \e provided that it implements the interface. Use qobject_cast to |
159 | * access the interface: |
160 | * \code |
161 | * // object is of type KTextEditor::Document* |
162 | * KTextEditor::ParameterizedSessionConfigInterface *iface = |
163 | * qobject_cast<KTextEditor::ParameterizedSessionConfigInterface*>( object ); |
164 | * |
165 | * if( iface ) { |
166 | * // interface is supported |
167 | * // do stuff |
168 | * } |
169 | * \endcode |
170 | * |
171 | * \see KTextEditor::Document, KTextEditor::SessionConfigInterface |
172 | * |
173 | * \since 4.4 |
174 | * \note KDE5: Rename to SessionConfigInterface, delete old SessionConfigInterface |
175 | */ |
176 | class KTEXTEDITOR_EXPORT ParameterizedSessionConfigInterface |
177 | { |
178 | public: |
179 | ParameterizedSessionConfigInterface(); |
180 | |
181 | /** |
182 | * Virtual destructor. |
183 | */ |
184 | virtual ~ParameterizedSessionConfigInterface(); |
185 | |
186 | public: |
187 | |
188 | /** |
189 | * Flags for session restore. |
190 | * These flags allow to skip some parts of the configuration from restoration. |
191 | */ |
192 | enum SessionConfigParameter { |
193 | SkipNone = 0, |
194 | SkipUrl = 1 << 0, |
195 | SkipMode = 1 << 1, |
196 | SkipHighlighting = 1 << 2, |
197 | SkipEncoding = 1 << 3, |
198 | SkipFolding = 1 << 4 |
199 | }; |
200 | |
201 | /** |
202 | * Read session settings from the given \p config excluding the settings specified in |
203 | * \p parameters. |
204 | * |
205 | * That means for example |
206 | * - a Document should reload the file, restore all marks etc... |
207 | * - a View should scroll to the last position and restore the cursor |
208 | * position etc... |
209 | * - a Plugin should restore session specific settings |
210 | * - If no file is being loaded, because an empty new document is going to be displayed or |
211 | * 'SkipUrl' is set, this function should emit ReadOnlyPart::completed |
212 | * |
213 | * \param config read the session settings from this KConfigGroup |
214 | * \param parameters settings that should not be read (i.e. a combination of flags from SessionConfigParameter) |
215 | * \see writeParameterizedSessionConfig() |
216 | */ |
217 | virtual void readParameterizedSessionConfig (const KConfigGroup& config, |
218 | unsigned long parameters) = 0; |
219 | |
220 | /** |
221 | * Write session settings to the \p config excluding the settings specified in |
222 | * \p parameters. |
223 | * See readSessionConfig() for more details. |
224 | * |
225 | * \param config write the session settings to this KConfigGroup |
226 | * \param parameters settings that should not be written (i.e. a combination of flags from SessionConfigParameter) |
227 | * \see readParameterizedSessionConfig() |
228 | */ |
229 | virtual void writeParameterizedSessionConfig (KConfigGroup& config, |
230 | unsigned long parameters) = 0; |
231 | }; |
232 | |
233 | |
234 | } |
235 | |
236 | Q_DECLARE_INTERFACE(KTextEditor::SessionConfigInterface, "org.kde.KTextEditor.SessionConfigInterface" ) |
237 | Q_DECLARE_INTERFACE(KTextEditor::ParameterizedSessionConfigInterface, "org.kde.KTextEditor.ParameterizedSessionConfigInterface" ) |
238 | |
239 | #endif |
240 | |
241 | // kate: space-indent on; indent-width 2; replace-tabs on; |
242 | |