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
27class KConfigGroup;
28
29#include <QtCore/QObject>
30
31namespace 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 */
82class 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 */
176class 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
236Q_DECLARE_INTERFACE(KTextEditor::SessionConfigInterface, "org.kde.KTextEditor.SessionConfigInterface")
237Q_DECLARE_INTERFACE(KTextEditor::ParameterizedSessionConfigInterface, "org.kde.KTextEditor.ParameterizedSessionConfigInterface")
238
239#endif
240
241// kate: space-indent on; indent-width 2; replace-tabs on;
242