1 /*
2     SPDX-FileCopyrightText: 2001-2014 Christoph Cullmann <cullmann@kde.org>
3     SPDX-FileCopyrightText: 2005-2014 Dominik Haumann <dhaumann@kde.org>
4     SPDX-FileCopyrightText: 2009 Michel Ludwig <michel.ludwig@kdemail.net>
5 
6     SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef KTEXTEDITOR_SESSIONCONFIGINTERFACE_H
10 #define KTEXTEDITOR_SESSIONCONFIGINTERFACE_H
11 
12 #include <ktexteditor_export.h>
13 
14 class KConfigGroup;
15 
16 #include <QObject>
17 
18 namespace KTextEditor
19 {
20 /**
21  * \class SessionConfigInterface sessionconfiginterface.h <KTextEditor/SessionConfigInterface>
22  *
23  * \brief Session config interface extension for the Plugin and Plugin views.
24  *
25  * \ingroup kte_group_plugin_extensions
26  *
27  * \section sessionconfig_intro Introduction
28  *
29  * The SessionConfigInterface is an extension for Plugin%s and Plugin views
30  * to add support for session-specific configuration settings.
31  * readSessionConfig() is called whenever session-specific settings are to be
32  * read from the given KConfigGroup and writeSessionConfig() whenever they are to
33  * be written, for example when a session changed or was closed.
34  *
35  * \note A \e session does not have anything to do with an X-session under Unix.
36  *       What is meant is rather a context, think of sessions in Kate or
37  *       projects in KDevelop for example.
38  *
39  * \section sessionconfig_support Adding Session Support
40  *
41  * To add support for sessions, your Plugin has to inherit the SessionConfigInterface
42  * and reimplement readSessionConfig() and writeSessionConfig().
43  *
44  * \section sessionconfig_access Accessing the SessionConfigInterface
45  *
46  * This section is for application developers such as Kate, KDevelop, etc that
47  * what to support session configuration for plugins.
48  *
49  * The SessionConfigInterface is an extension interface for a Plugin or a
50  * Plugin view, i.e. Plugin/Plugin view inherits the interface
51  * \e provided that it implements the interface. Use qobject_cast to
52  * access the interface:
53  * \code
54  * // object is of type Plugin* or, in case of a plugin view, QObject*
55  * KTextEditor::SessionConfigInterface *iface =
56  *     qobject_cast<KTextEditor::SessionConfigInterface*>( object );
57  *
58  * if( iface ) {
59  *     // interface is supported
60  *     // do stuff
61  * }
62  * \endcode
63  *
64  * \see KTextEditor::Plugin
65  * \author Christoph Cullmann \<cullmann@kde.org\>
66  */
67 class KTEXTEDITOR_EXPORT SessionConfigInterface
68 {
69 public:
70     SessionConfigInterface();
71 
72     /**
73      * Virtual destructor.
74      */
75     virtual ~SessionConfigInterface();
76 
77 public:
78     /**
79      * Read session settings from the given \p config.
80      *
81      * That means for example
82      *  - a Document should reload the file, restore all marks etc...
83      *  - a View should scroll to the last position and restore the cursor
84      *    position etc...
85      *  - a Plugin should restore session specific settings
86      *  - If no file is being loaded, because an empty new document is going to be displayed,
87      *    this function should emit ReadOnlyPart::completed
88      *
89      * \param config read the session settings from this KConfigGroup
90      * \see writeSessionConfig()
91      */
92     virtual void readSessionConfig(const KConfigGroup &config) = 0;
93 
94     /**
95      * Write session settings to the \p config.
96      * See readSessionConfig() for more details.
97      *
98      * \param config write the session settings to this KConfigGroup
99      * \see readSessionConfig()
100      */
101     virtual void writeSessionConfig(KConfigGroup &config) = 0;
102 
103 private:
104     class SessionConfigInterfacePrivate *const d = nullptr;
105 };
106 
107 }
108 
109 Q_DECLARE_INTERFACE(KTextEditor::SessionConfigInterface, "org.kde.KTextEditor.SessionConfigInterface")
110 
111 #endif
112