plasma/theme.h

   1 /*
   2  *   Copyright 2006-2007 Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program 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
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_THEME_H
  21 #define PLASMA_THEME_H
  22
  23 #include <QtCore/QObject>
  24 #include <QtGui/QFont>
  25 #include <QtGui/QFontMetrics>
  26
  27 #include <ksharedconfig.h>
  28
  29 #include <plasma/plasma_export.h>
  30 #include <plasma/packagestructure.h>
  31
  32 namespace Plasma
  33 {
  34
  35 class ThemePrivate;
  36
  37 /**
  38  * @class Theme plasma/theme.h <Plasma/Theme>
  39  *
  40  * @short Interface to the Plasma theme
  41  *
  42  * Accessed via Plasma::Theme::defaultTheme() e.g:
  43  * \code
  44  * QString imagePath = Plasma::Theme::defaultTheme()->imagePath("widgets/clock")
  45  * \endcode
  46  *
  47  * Plasma::Theme provides access to a common and standardized set of graphic
  48  * elements stored in SVG format. This allows artists to create single packages
  49  * of SVGs that will affect the look and feel of all workspace components.
  50  *
  51  * Plasma::Svg uses Plasma::Theme internally to locate and load the appropriate
  52  * SVG data. Alternatively, Plasma::Theme can be used directly to retrieve
  53  * file system paths to SVGs by name.
  54  */
  55 class PLASMA_EXPORT Theme : public QObject
  56 {
  57     Q_OBJECT
  58     Q_PROPERTY(QString themeName READ themeName)
  59
  60     public:
  61         enum ColorRole {
  62             TextColor = 0, /**<  the text color to be used by items resting on the background */
  63             HighlightColor = 1, /**<  the text higlight color to be used by items resting
  64                                    on the background */
  65             BackgroundColor = 2, /**< the default background color */
  66             ButtonTextColor = 4, /** text color for buttons */
  67             ButtonBackgroundColor = 8 /** background color for buttons*/
  68         };
  69
  70         enum FontRole {
  71             DefaultFont = 0, /**< The standard text font */
  72             DesktopFont /**< The standard text font */
  73         };
  74
  75         /**
  76          * Singleton pattern accessor
  77          **/
  78         static Theme *defaultTheme();
  79
  80         /**
  81          * Default constructor. Usually you want to use the singleton instead.
  82          */
  83         explicit Theme(QObject *parent = 0);
  84         ~Theme();
  85
  86         /**
  87          * @return a package structure representing a Theme
  88          */
  89         static PackageStructure::Ptr packageStructure();
  90
  91         /**
  92          * Sets the current theme being used.
  93          */
  94         void setThemeName(const QString &themeName);
  95
  96         /**
  97          * @return the name of the theme.
  98          */
  99         QString themeName() const;
 100
 101         /**
 102          * Retrieve the path for an SVG image in the current theme.
 103          *
 104          * @arg name the name of the file in the theme directory (without the
 105          *           ".svg" part or a leading slash)
 106          * @return the full path to the requested file for the current theme
 107          */
 108         Q_INVOKABLE QString imagePath(const QString &name) const;
 109
 110         /**
 111          * Retreives the default wallpaper associated with this theme.
 112          *
 113          * @arg size the target height and width of the wallpaper; if an invalid size
 114          *           is passed in, then a default size will be provided instead.
 115          * @return the full path to the wallpaper image
 116          */
 117         Q_INVOKABLE QString wallpaperPath(const QSize &size = QSize()) const;
 118
 119         /**
 120          * Checks if this theme has an image named in a certain way
 121          *
 122          * @arg name the name of the file in the theme directory (without the
 123          *           ".svg" part or a leading slash)
 124          * @return true if the image exists for this theme
 125          */
 126         Q_INVOKABLE bool currentThemeHasImage(const QString &name) const;
 127
 128         /**
 129          * Returns the color scheme configurationthat goes along this theme.
 130          * This can be used with KStatefulBrush and KColorScheme to determine
 131          * the proper colours to use along with the visual elements in this theme.
 132          */
 133         Q_INVOKABLE KSharedConfigPtr colorScheme() const;
 134
 135         /**
 136          * Returns the text color to be used by items resting on the background
 137          *
 138          * @arg role which role (usage pattern) to get the color for
 139          */
 140         Q_INVOKABLE QColor color(ColorRole role) const;
 141
 142         /**
 143          * Sets the default font to be used with themed items. Defaults to
 144          * the application wide default font.
 145          *
 146          * @arg font the new font
 147          * @arg role which role (usage pattern) to set the font for
 148          */
 149         Q_INVOKABLE void setFont(const QFont &font, FontRole role = DefaultFont);
 150
 151         /**
 152          * Returns the font to be used by themed items
 153          *
 154          * @arg role which role (usage pattern) to get the font for
 155          */
 156         Q_INVOKABLE QFont font(FontRole role) const;
 157
 158         /**
 159          * Returns the font metrics for the font to be used by themed items
 160          */
 161         Q_INVOKABLE QFontMetrics fontMetrics() const;
 162
 163         /**
 164          * Returns if the window manager effects (e.g. translucency, compositing) is active or not
 165          */
 166         Q_INVOKABLE bool windowTranslucencyEnabled() const;
 167
 168         /**
 169          * Tells the theme whether to follow the global settings or use application
 170          * specific settings
 171          *
 172          * @arg useGlobal pass in true to follow the global settings
 173          */
 174         void setUseGlobalSettings(bool useGlobal);
 175
 176         /**
 177          * @return true if the global settings are followed, false if application
 178          * specific settings are used.
 179          */
 180         bool useGlobalSettings() const;
 181
 182         /**
 183          * Tries to load pixmap with the specified key from cache.
 184          * @return true when pixmap was found and loaded from cache, false otherwise
 185          **/
 186         bool findInCache(const QString &key, QPixmap &pix);
 187
 188         /**
 189          * Insert specified pixmap into the cache.
 190          * If the cache already contains pixmap with the specified key then it is
 191          *  overwritten.
 192          **/
 193         void insertIntoCache(const QString& key, const QPixmap& pix);
 194
 195         /**
 196          * Sets the maximum size of the cache (in kilobytes). If cache gets bigger
 197          * the limit then some entries are removed
 198          * Setting cache limit to 0 disables automatic cache size limiting.
 199          *
 200          * Note that the cleanup might not be done immediately, so the cache might
 201          *  temporarily (for a few seconds) grow bigger than the limit.
 202          **/
 203         void setCacheLimit(int kbytes);
 204
 205         /**
 206          * Tries to load the rect of a sub element from a disk cache
 207          *
 208          * @arg image path of the image we want to check
 209          * @arg element sub element we want to retrieve
 210          * @arg rect output parameter of the element rect found in cache
 211          *           if not found or if we are sure it doesn't exist it will be QRect()
 212          * @return true if the element was found in cache or if we are sure the element doesn't exist
 213          **/
 214         bool findInRectsCache(const QString &image, const QString &element, QRectF &rect) const;
 215
 216         /**
 217          * Inserts a rectangle of a sub element of an image into a disk cache
 218          *
 219          * @arg image path of the image we want to insert information
 220          * @arg element sub element we want insert the rect
 221          * @arg rect element rectangle
 222          **/
 223         void insertIntoRectsCache(const QString& image, const QString &element, const QRectF &rect);
 224
 225         /**
 226          * Discards all the information about a given image from the rectangle disk cache
 227          *
 228          * @arg image the path to the image the cache is assoiated with
 229          **/
 230         void invalidateRectsCache(const QString &image);
 231
 232         /**
 233          * Frees up memory used by cached information for a given image without removing
 234          * the permenant record of it on disk.
 235          * @see invalidateRectsCache
 236          *
 237          * @arg image the path to the image the cache is assoiated with
 238          */
 239         void releaseRectsCache(const QString &image);
 240
 241     Q_SIGNALS:
 242         /**
 243          * Emitted when the user changes the theme. SVGs should be reloaded at
 244          * that point
 245          */
 246         void themeChanged();
 247
 248     public Q_SLOTS:
 249         /**
 250          * Notifies the Theme object that the theme settings have changed
 251          * and should be read from the config file
 252          **/
 253         void settingsChanged();
 254
 255     private:
 256         friend class ThemeSingleton;
 257         friend class ThemePrivate;
 258         ThemePrivate *const d;
 259
 260         Q_PRIVATE_SLOT(d, void compositingChanged())
 261         Q_PRIVATE_SLOT(d, void discardCache())
 262         Q_PRIVATE_SLOT(d, void colorsChanged())
 263 };
 264
 265 } // Plasma namespace
 266
 267 #endif // multiple inclusion guard
 268