1/* This file is part of the KDE project
2 Copyright (C) 2006 Matt Broadstone (mbroadst@gmail.com)
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
20#ifndef KTEXTEDITOR_CONFIGINTERFACE_H
21#define KTEXTEDITOR_CONFIGINTERFACE_H
22
23#include <ktexteditor_export.h>
24#include <QStringList>
25#include <QVariant>
26
27namespace KTextEditor
28{
29/**
30 * \brief Config interface extension for the Document and View.
31 *
32 * \ingroup kte_group_view_extensions
33 * \ingroup kte_group_doc_extensions
34 *
35 * \section config_intro Introduction
36 *
37 * The ConfigInterface provides methods to access and modify the low level
38 * config information for a given Document or View. Examples of this config data can be
39 * displaying the icon bar, showing line numbers, etc. This generally allows
40 * access to settings that otherwise are only accessible during runtime.
41 *
42 * \section config_access Accessing the Interface
43 *
44 * The ConfigInterface is supposed to be an extension interface for a Document or View,
45 * i.e. the Document or View inherits the interface \e provided that the
46 * KTextEditor library in use implements the interface. Use qobject_cast to access
47 * the interface:
48 * \code
49 * // ptr is of type KTextEditor::Document* or KTextEditor::View*
50 * auto iface = qobject_cast<KTextEditor::ConfigInterface*>(ptr);
51 *
52 * if (iface) {
53 * // the implementation supports the interface
54 * // do stuff
55 * } else {
56 * // the implementation does not support the interface
57 * }
58 * \endcode
59 *
60 * \section config_data Accessing Data
61 *
62 * A list of available config variables (or keys) can be obtained by calling
63 * configKeys(). For all available keys configValue() returns the corresponding
64 * value as QVariant. A value for a given key can be set by calling
65 * setConfigValue(). Right now, when using KatePart as editor component,
66 * KTextEditor::View has support for the following tuples:
67 * - line-numbers [bool], show/hide line numbers
68 * - icon-bar [bool], show/hide icon bar
69 * - folding-bar [bool], show/hide the folding bar
70 * - folding-preview [bool], enable/disable folding preview when mouse hovers
71 * on folded region
72 * - dynamic-word-wrap [bool], enable/disable dynamic word wrap
73 * - background-color [QColor], read/set the default background color
74 * - selection-color [QColor], read/set the default color for selections
75 * - search-highlight-color [QColor], read/set the background color for search
76 * - replace-highlight-color [QColor], read/set the background color for replaces
77 * - default-mark-type [uint], read/set the default mark type
78 * - allow-mark-menu [bool], enable/disable the menu shown when right clicking
79 * on the left gutter. When disabled, click on the gutter will always set
80 * or clear the mark of default type.
81 * - icon-border-color [QColor] read/set the icon border color (on the left,
82 * with the line numbers)
83 * - folding-marker-color [QColor] read/set folding marker colors (in the icon border)
84 * - line-number-color [QColor] read/set line number colors (in the icon border)
85 * - current-line-number-color [QColor] read/set current line number color (in the icon border)
86 * - modification-markers [bool] read/set whether the modification markers are shown
87 * - word-count [bool] enable/disable the counting of words and characters in the statusbar
88 * - scrollbar-minimap [bool] enable/disable scrollbar minimap
89 * - scrollbar-preview [bool] enable/disable scrollbar text preview on hover
90 * - font [QFont] change the font
91 *
92 * KTextEditor::Document has support for the following:
93 * - backup-on-save-local [bool], enable/disable backup when saving local files
94 * - backup-on-save-remote [bool], enable/disable backup when saving remote files
95 * - backup-on-save-suffix [string], set the suffix for file backups, e.g. "~"
96 * - backup-on-save-prefix [string], set the prefix for file backups, e.g. "."
97 * - replace-tabs [bool], whether to replace tabs
98 * - indent-pasted-text [bool], whether to indent pasted text
99 * - tab-width [int], read/set the width for tabs
100 * - indent-width [int], read/set the indentation width
101 * - on-the-fly-spellcheck [bool], enable/disable on the fly spellcheck
102 *
103 * Either interface should emit the \p configChanged signal when appropriate.
104 * TODO: Add to interface in KDE 5.
105 *
106 * For instance, if you want to enable dynamic word wrap of a KTextEditor::View
107 * simply call
108 * \code
109 * iface->setConfigValue("dynamic-word-wrap", true);
110 * \endcode
111 *
112 * \see KTextEditor::View, KTextEditor::Document
113 * \author Matt Broadstone \<mbroadst@gmail.com\>
114 */
115class KTEXTEDITOR_EXPORT ConfigInterface
116{
117public:
118 ConfigInterface();
119
120 /**
121 * Virtual destructor.
122 */
123 virtual ~ConfigInterface();
124
125public:
126 /**
127 * Get a list of all available keys.
128 */
129 virtual QStringList configKeys() const = 0;
130 /**
131 * Get a value for the \p key.
132 */
133 virtual QVariant configValue(const QString &key) = 0;
134 /**
135 * Set a the \p key's value to \p value.
136 */
137 virtual void setConfigValue(const QString &key, const QVariant &value) = 0;
138
139private:
140 class ConfigInterfacePrivate *const d = nullptr;
141};
142
143}
144
145Q_DECLARE_INTERFACE(KTextEditor::ConfigInterface, "org.kde.KTextEditor.ConfigInterface")
146
147#endif
148
149