apps/konsole/src/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 #ifndef COLORSCHEME_H
  23 #define COLORSCHEME_H
  24
  25 // Qt
  26 #include <QtCore/QHash>
  27 #include <QtCore/QList>
  28 #include <QtCore/QMetaType>
  29 #include <QtCore/QIODevice>
  30 #include <QtCore/QSet>
  31
  32 // Konsole
  33 #include "CharacterColor.h"
  34
  35 class QIODevice;
  36 class KConfig;
  37
  38 namespace Konsole
  39 {
  40
  41 /**
  42  * Represents a color scheme for a terminal display.
  43  *
  44  * The color scheme includes the palette of colors used to draw the text and character backgrounds
  45  * in the display and the opacity level of the display background.
  46  */
  47 class ColorScheme
  48 {
  49 public:
  50     /**
  51      * Constructs a new color scheme which is initialised to the default color set
  52      * for Konsole.
  53      */
  54     ColorScheme();
  55     ColorScheme(const ColorScheme& other);
  56     ~ColorScheme();
  57
  58     /** Sets the descriptive name of the color scheme. */
  59     void setDescription(const QString& description);
  60     /** Returns the descriptive name of the color scheme. */
  61     QString description() const;
  62
  63     /** Sets the name of the color scheme */
  64     void setName(const QString& name);
  65     /** Returns the name of the color scheme */
  66     QString name() const;
  67
  68     /** Reads the color scheme from the specified configuration source */
  69     void read(KConfig& config);
  70     /** Writes the color scheme to the specified configuration source */
  71     void write(KConfig& config) const;
  72
  73     /** Sets a single entry within the color palette. */
  74     void setColorTableEntry(int index , const ColorEntry& entry);
  75
  76     /**
  77      * Copies the color entries which form the palette for this color scheme
  78      * into @p table.  @p table should be an array with TABLE_COLORS entries.
  79      *
  80      * @param table Array into which the color entries for this color scheme
  81      * are copied.
  82      * @param randomSeed Color schemes may allow certain colors in their
  83      * palette to be randomized.  The seed is used to pick the random color.
  84      */
  85     void getColorTable(ColorEntry* table, uint randomSeed = 0) const;
  86
  87     /**
  88      * Retrieves a single color entry from the table.
  89      *
  90      * See getColorTable()
  91      */
  92     ColorEntry colorEntry(int index , uint randomSeed = 0) const;
  93
  94     /**
  95      * Convenience method.  Returns the
  96      * foreground color for this scheme,
  97      * this is the primary color used to draw the
  98      * text in this scheme.
  99      */
 100     QColor foregroundColor() const;
 101     /**
 102      * Convenience method.  Returns the background color for
 103      * this scheme, this is the primary color used to
 104      * draw the terminal background in this scheme.
 105      */
 106     QColor backgroundColor() const;
 107
 108     /**
 109      * Returns true if this color scheme has a dark background.
 110      * The background color is said to be dark if it has a value of less than 127
 111      * in the HSV color space.
 112      */
 113     bool hasDarkBackground() const;
 114
 115     /**
 116      * Sets the opacity level of the display background. @p opacity ranges
 117      * between 0 (completely transparent background) and 1 (completely
 118      * opaque background).
 119      *
 120      * Defaults to 1.
 121      *
 122      * TODO: More documentation
 123      */
 124     void setOpacity(qreal opacity);
 125     /**
 126      * Returns the opacity level for this color scheme, see setOpacity()
 127      * TODO: More documentation
 128      */
 129     qreal opacity() const;
 130
 131     /**
 132      * Enables randomization of the background color.  This will cause
 133      * the palette returned by getColorTable() and colorEntry() to
 134      * be adjusted depending on the value of the random seed argument
 135      * to them.
 136      */
 137     void setRandomizedBackgroundColor(bool randomize);
 138
 139     /** Returns true if the background color is randomized. */
 140     bool randomizedBackgroundColor() const;
 141
 142     static QString colorNameForIndex(int index);
 143     static QString translatedColorNameForIndex(int index);
 144
 145 private:
 146     // specifies how much a particular color can be randomized by
 147     class RandomizationRange
 148     {
 149     public:
 150         RandomizationRange() : hue(0) , saturation(0) , value(0) {}
 151
 152         bool isNull() const
 153         {
 154             return ( hue == 0 && saturation == 0 && value == 0 );
 155         }
 156
 157         quint16 hue;
 158         quint8  saturation;
 159         quint8  value;
 160     };
 161
 162     // returns the active color table.  if none has been set specifically,
 163     // this is the default color table.
 164     const ColorEntry* colorTable() const;
 165
 166     // reads a single colour entry from a KConfig source
 167     // and sets the palette entry at 'index' to the entry read.
 168     void readColorEntry(KConfig& config , int index);
 169     // writes a single colour entry to a KConfig source
 170     void writeColorEntry(KConfig& config , const QString& colorName, const ColorEntry& entry,const RandomizationRange& range) const;
 171
 172     // sets the amount of randomization allowed for a particular color
 173     // in the palette.  creates the randomization table if
 174     // it does not already exist
 175     void setRandomizationRange( int index , quint16 hue , quint8 saturation , quint8 value );
 176
 177     QString _description;
 178     QString _name;
 179     qreal _opacity;
 180     ColorEntry* _table; // pointer to custom color table or 0 if the default
 181                         // color scheme is being used
 182
 183
 184     static const quint16 MAX_HUE = 340;
 185
 186     RandomizationRange* _randomTable;   // pointer to randomization table or 0
 187                                         // if no colors in the color scheme support
 188                                         // randomization
 189
 190     static const char* colorNames[TABLE_COLORS];
 191     static const char* translatedColorNames[TABLE_COLORS];
 192
 193     static const ColorEntry defaultTable[]; // table of default color entries
 194 };
 195
 196 /**
 197  * A color scheme which uses colors from the standard KDE color palette.
 198  *
 199  * This is designed primarily for the benefit of users who are using specially
 200  * designed colors.
 201  *
 202  * TODO Implement and make it the default on systems with specialized KDE
 203  * color schemes.
 204  */
 205 class AccessibleColorScheme : public ColorScheme
 206 {
 207 public:
 208     AccessibleColorScheme();
 209 };
 210
 211 /**
 212  * Reads a color scheme stored in the .schema format used in the KDE 3 incarnation
 213  * of Konsole
 214  *
 215  * Only the basic essentials ( title and color palette entries ) are currently
 216  * supported.  Additional options such as background image and background
 217  * blend colors are ignored.
 218  */
 219 class KDE3ColorSchemeReader
 220 {
 221 public:
 222     /**
 223      * Constructs a new reader which reads from the specified device.
 224      * The device should be open in read-only mode.
 225      */
 226     KDE3ColorSchemeReader( QIODevice* device );
 227
 228     /**
 229      * Reads and parses the contents of the .schema file from the input
 230      * device and returns the ColorScheme defined within it.
 231      *
 232      * Returns a null pointer if an error occurs whilst parsing
 233      * the contents of the file.
 234      */
 235     ColorScheme* read();
 236
 237 private:
 238     // reads a line from the file specifying a colour palette entry
 239     // format is: color [index] [red] [green] [blue] [transparent] [bold]
 240     bool readColorLine(const QString& line , ColorScheme* scheme);
 241     bool readTitleLine(const QString& line , ColorScheme* scheme);
 242
 243     QIODevice* _device;
 244 };
 245
 246 /**
 247  * Manages the color schemes available for use by terminal displays.
 248  * See ColorScheme
 249  */
 250 class ColorSchemeManager
 251 {
 252 public:
 253
 254     /**
 255      * Constructs a new ColorSchemeManager and loads the list
 256      * of available color schemes.
 257      *
 258      * The color schemes themselves are not loaded until they are first
 259      * requested via a call to findColorScheme()
 260      */
 261     ColorSchemeManager();
 262     /**
 263      * Destroys the ColorSchemeManager and saves any modified color schemes to disk.
 264      */
 265     ~ColorSchemeManager();
 266
 267     /**
 268      * Returns the default color scheme for Konsole
 269      */
 270     const ColorScheme* defaultColorScheme() const;
 271
 272     /**
 273      * Returns the color scheme with the given name or 0 if no
 274      * scheme with that name exists.  If @p name is empty, the
 275      * default color scheme is returned.
 276      *
 277      * The first time that a color scheme with a particular name is
 278      * requested, the configuration information is loaded from disk.
 279      */
 280     const ColorScheme* findColorScheme(const QString& name);
 281
 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
 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      */
 302     QList<const ColorScheme*> allColorSchemes();
 303
 304     /** Returns the global color scheme manager instance. */
 305     static ColorSchemeManager* instance();
 306
 307 private:
 308     // loads a color scheme from a KDE 4+ .colorscheme file
 309     bool loadColorScheme(const QString& path);
 310     // loads a color scheme from a KDE 3 .schema file
 311     bool loadKDE3ColorScheme(const QString& path);
 312     // returns a list of paths of color schemes in the KDE 4+ .colorscheme file format
 313     QList<QString> listColorSchemes();
 314     // returns a list of paths of color schemes in the .schema file format
 315     // used in KDE 3
 316     QList<QString> listKDE3ColorSchemes();
 317     // loads all of the color schemes
 318     void loadAllColorSchemes();
 319     // finds the path of a color scheme
 320     QString findColorSchemePath(const QString& name) const;
 321
 322     QHash<QString,const ColorScheme*> _colorSchemes;
 323     QSet<ColorScheme*> _modifiedSchemes;
 324
 325     bool _haveLoadedAll;
 326
 327     static const ColorScheme _defaultColorScheme;
 328 };
 329
 330 }
 331
 332 Q_DECLARE_METATYPE(const Konsole::ColorScheme*)
 333
 334 #endif //COLORSCHEME_H