MauiKit Terminal

ColorScheme.h
1/*
2 This source file is part of Konsole, a terminal emulator.
3
4 Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or
9 (at your option) any later version.
10
11 This program 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
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19 02110-1301 USA.
20*/
21
22#pragma once
23
24// Qt
25#include <QHash>
26#include <QList>
27#include <QMetaType>
28#include <QIODevice>
29#include <QSet>
30#include <QSettings>
31
32// Konsole
33#include "CharacterColor.h"
34
35// std
36#include <memory>
37#include <optional>
38#include <span>
39#include <unordered_map>
40#include <vector>
41
42class QIODevice;
43
44namespace Konsole
45{
46
47std::array<ColorEntry, TABLE_COLORS> defaultColorTable();
48
49/**
50 * @brief Represents a color scheme for a terminal display.
51 *
52 * The color scheme includes the palette of colors used to draw the text and character backgrounds
53 * in the display and the opacity level of the display background.
54 */
55class ColorScheme : public QObject
56{
58
59public:
60 /**
61 * @brief Constructs a new color scheme which is initialised to the default color set
62 * for Konsole.
63 */
64 ColorScheme(QObject * parent = nullptr);
66
67 /**
68 * @brief Sets the descriptive name of the color scheme.
69 */
71
72 /**
73 * @brief Returns the descriptive name of the color scheme.
74 */
75 QString description() const;
76
77 /**
78 * @brief Sets the name of the color scheme
79 */
80 void setName(const QString& name);
81
82 /**
83 * @brief Returns the name of the color scheme
84 */
85 QString name() const;
86
87#if 0
88// Implemented upstream - in user apps
89 /** Reads the color scheme from the specified configuration source */
90 void read(KConfig& config);
91 /** Writes the color scheme to the specified configuration source */
92 void write(KConfig& config) const;
93#endif
94
95 void read(const QString & filename);
96
97 /**
98 * @brief Sets a single entry within the color palette.
99 */
100 void setColorTableEntry(int index , const ColorEntry& entry);
101 void setColor(int index, QColor color);
102
103 /**
104 * Copies the color entries which form the palette for this color scheme
105 * into @p table. @p table should be an array with TABLE_COLORS entries.
106 *
107 * @param table Array into which the color entries for this color scheme
108 * are copied.
109 * @param randomSeed Color schemes may allow certain colors in their
110 * palette to be randomized. The seed is used to pick the random color.
111 */
112 std::array<ColorEntry, TABLE_COLORS> getColorTable(uint randomSeed = 0) const;
113
114 /**
115 * Retrieves a single color entry from the table.
116 *
117 * See getColorTable()
118 */
119 ColorEntry colorEntry(int index , uint randomSeed = 0) const;
120
121 /**
122 * Convenience method. Returns the
123 * foreground color for this scheme,
124 * this is the primary color used to draw the
125 * text in this scheme.
126 */
127 QColor foregroundColor() const;
128 /**
129 * Convenience method. Returns the background color for
130 * this scheme, this is the primary color used to
131 * draw the terminal background in this scheme.
132 */
133 QColor backgroundColor() const;
134
135 /**
136 * Returns true if this color scheme has a dark background.
137 * The background color is said to be dark if it has a value of less than 127
138 * in the HSV color space.
139 */
140 bool hasDarkBackground() const;
141
142 /**
143 * Sets the opacity level of the display background. @p opacity ranges
144 * between 0 (completely transparent background) and 1 (completely
145 * opaque background).
146 *
147 * Defaults to 1.
148 *
149 * TODO: More documentation
150 */
151 void setOpacity(qreal opacity);
152 /**
153 * Returns the opacity level for this color scheme, see setOpacity()
154 * TODO: More documentation
155 */
156 qreal opacity() const;
157
158 /**
159 * Enables randomization of the background color. This will cause
160 * the palette returned by getColorTable() and colorEntry() to
161 * be adjusted depending on the value of the random seed argument
162 * to them.
163 */
164 void setRandomizedBackgroundColor(bool randomize);
165
166 /** Returns true if the background color is randomized. */
167 bool randomizedBackgroundColor() const;
168
169 static QString colorNameForIndex(int index);
170 static QString translatedColorNameForIndex(int index);
171
172private:
173 // specifies how much a particular color can be randomized by
174 class RandomizationRange
175 {
176 public:
177 RandomizationRange() : hue(0) , saturation(0) , value(0) {}
178
179 bool isNull() const
180 {
181 return ( hue == 0 && saturation == 0 && value == 0 );
182 }
183
184 quint16 hue;
185 quint8 saturation;
186 quint8 value;
187 };
188
189 // returns the active color table. if none has been set specifically,
190 // this is the default color table.
191 const std::span<const ColorEntry> colorTable() const;
192
193#if 0
194// implemented upstream - user apps
195 // reads a single colour entry from a KConfig source
196 // and sets the palette entry at 'index' to the entry read.
197 void readColorEntry(KConfig& config , int index);
198 // writes a single colour entry to a KConfig source
199 void writeColorEntry(KConfig& config , const QString& colorName, const ColorEntry& entry,const RandomizationRange& range) const;
200#endif
201
202 void readColorEntry(QSettings *s, int index);
203
204 // sets the amount of randomization allowed for a particular color
205 // in the palette. creates the randomization table if
206 // it does not already exist
207 void setRandomizationRange( int index , quint16 hue , quint8 saturation , quint8 value );
208
209 QString _description;
210 QString _name;
211 qreal _opacity;
212 std::optional<std::vector<ColorEntry>> _table; // pointer to custom color table or 0 if the default // color scheme is being used
213
214
215 static const quint16 MAX_HUE = 340;
216
217 std::optional<std::vector<RandomizationRange>> _randomTable; // pointer to randomization table or 0
218 // if no colors in the color scheme support
219 // randomization
220
221 static const char* const colorNames[TABLE_COLORS];
222 static const char* const translatedColorNames[TABLE_COLORS];
223
224 static const ColorEntry defaultTable[]; // table of default color entries
225
227 void colorChanged(int index);
228};
229
230/**
231 * A color scheme which uses colors from the standard KDE color palette.
232 *
233 * This is designed primarily for the benefit of users who are using specially
234 * designed colors.
235 *
236 * TODO Implement and make it the default on systems with specialized KDE
237 * color schemes.
238 */
240{
241public:
243};
244
245/**
246 * Manages the color schemes available for use by terminal displays.
247 * See ColorScheme
248 */
250{
251public:
252
253 /**
254 * Constructs a new ColorSchemeManager and loads the list
255 * of available color schemes.
256 *
257 * The color schemes themselves are not loaded until they are first
258 * requested via a call to findColorScheme()
259 */
261 /**
262 * Destroys the ColorSchemeManager and saves any modified color schemes to disk.
263 */
265
266 /**
267 * Returns the default color scheme for Konsole
268 */
269 const ColorScheme *defaultColorScheme() const;
270
271 /**
272 * Returns the color scheme with the given name or 0 if no
273 * scheme with that name exists. If @p name is empty, the
274 * default color scheme is returned.
275 *
276 * The first time that a color scheme with a particular name is
277 * requested, the configuration information is loaded from disk.
278 */
279 const ColorScheme* findColorScheme(const QString& name);
280
281#if 0
282 /**
283 * Adds a new color scheme to the manager. If @p scheme has the same name as
284 * an existing color scheme, it replaces the existing scheme.
285 *
286 * TODO - Ensure the old color scheme gets deleted
287 */
288 void addColorScheme(ColorScheme* scheme);
289#endif
290 /**
291 * Deletes a color scheme. Returns true on successful deletion or false otherwise.
292 */
293 bool deleteColorScheme(const QString& name);
294
295 /**
296 * Returns a list of the all the available color schemes.
297 * This may be slow when first called because all of the color
298 * scheme resources on disk must be located, read and parsed.
299 *
300 * Subsequent calls will be inexpensive.
301 */
303
304 /** Returns the global color scheme manager instance. */
306
307 /** @brief Loads a custom color scheme under given \em path.
308 *
309 * The \em path may refer to either KDE 4 .colorscheme or KDE 3
310 * .schema file
311 *
312 * The loaded color scheme is available under the name equal to
313 * the base name of the \em path via the allColorSchemes() and
314 * findColorScheme() methods after this call if loaded successfully.
315 *
316 * @param[in] path The path to KDE 4 .colorscheme or KDE 3 .schema.
317 * @return Whether the color scheme is loaded successfully.
318 */
319 bool loadCustomColorScheme(const QString& path);
320
321 /**
322 * @brief Allows to add a custom location of color schemes.
323 *
324 * @param[in] custom_dir Custom location of color schemes (must end with /).
325 */
326 void addCustomColorSchemeDir(const QString& custom_dir);
327
328private:
329 // loads a color scheme from a KDE 4+ .colorscheme file
330 bool loadColorScheme(const QString& path);
331
332 // returns a list of paths of color schemes in the KDE 4+ .colorscheme file format
333 QList<QString> listColorSchemes();
334 // returns a list of paths of color schemes in the .schema file format
335 // used in KDE 3
336 QList<QString> listKDE3ColorSchemes();
337 // loads all of the color schemes
338 void loadAllColorSchemes();
339 // finds the path of a color scheme
340 QString findColorSchemePath(const QString& name) const;
341
342 std::unordered_map<QString, std::unique_ptr<ColorScheme>> _colorSchemes;
343 QSet<ColorScheme*> _modifiedSchemes;
344
345 bool _haveLoadedAll;
346 static const ColorScheme _defaultColorScheme;
347};
348
349}
350
351Q_DECLARE_METATYPE(const Konsole::ColorScheme*)
A color scheme which uses colors from the standard KDE color palette.
An entry in a terminal display's color palette.
Manages the color schemes available for use by terminal displays.
ColorSchemeManager()
Constructs a new ColorSchemeManager and loads the list of available color schemes.
QList< ColorScheme * > allColorSchemes()
Returns a list of the all the available color schemes.
static ColorSchemeManager * instance()
Returns the global color scheme manager instance.
const ColorScheme * defaultColorScheme() const
Returns the default color scheme for Konsole.
const ColorScheme * findColorScheme(const QString &name)
Returns the color scheme with the given name or 0 if no scheme with that name exists.
~ColorSchemeManager()
Destroys the ColorSchemeManager and saves any modified color schemes to disk.
bool deleteColorScheme(const QString &name)
Deletes a color scheme.
void addCustomColorSchemeDir(const QString &custom_dir)
Allows to add a custom location of color schemes.
bool loadCustomColorScheme(const QString &path)
Loads a custom color scheme under given path.
Represents a color scheme for a terminal display.
Definition ColorScheme.h:56
qreal opacity() const
Returns the opacity level for this color scheme, see setOpacity() TODO: More documentation.
void setColorTableEntry(int index, const ColorEntry &entry)
Sets a single entry within the color palette.
QColor foregroundColor() const
Convenience method.
QString description() const
Returns the descriptive name of the color scheme.
void setName(const QString &name)
Sets the name of the color scheme.
void setOpacity(qreal opacity)
Sets the opacity level of the display background.
bool hasDarkBackground() const
Returns true if this color scheme has a dark background.
std::array< ColorEntry, TABLE_COLORS > getColorTable(uint randomSeed=0) const
Copies the color entries which form the palette for this color scheme into table.
void setRandomizedBackgroundColor(bool randomize)
Enables randomization of the background color.
bool randomizedBackgroundColor() const
Returns true if the background color is randomized.
QColor backgroundColor() const
Convenience method.
QString name() const
Returns the name of the color scheme.
ColorEntry colorEntry(int index, uint randomSeed=0) const
Retrieves a single color entry from the table.
ColorScheme(QObject *parent=nullptr)
Constructs a new color scheme which is initialised to the default color set for Konsole.
void setDescription(const QString &description)
Sets the descriptive name of the color scheme.
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Wed Nov 6 2024 12:10:56 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.