File indexing completed on 2024-07-21 03:47:02

0001 /*
0002     This file is part of the KDE games kwin4 program
0003     SPDX-FileCopyrightText: 2006 Martin Heni <kde@heni-online.de>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef THEME_MANAGER_H
0009 #define THEME_MANAGER_H
0010 
0011 // KF
0012 #include <KConfig>
0013 // Qt
0014 #include <QHash>
0015 #include <QObject>
0016 #include <QPoint>
0017 #include <QSvgRenderer>
0018 
0019 class ThemeManager;
0020 
0021 /**
0022  * Objects which are connected to the theme manger must inherit
0023  * from this class. Doing so enables the items to be refreshed
0024  * by the theme manager and allows them to retrieve theme data
0025  * from a configuration theme file.
0026  */
0027 class Themeable
0028 {
0029 public:
0030     /**
0031      * Default constructor for the interface
0032      */
0033     Themeable();
0034 
0035     /**
0036      * Constructor for the interface given the theme item unique ID string
0037      * and a reference to the theme manager. The ID string is used to refer
0038      * to the group in the configuration file.
0039      * @param id           The user defined theme id
0040      * @param thememanager The used theme manager
0041      */
0042     Themeable(const QString &id, ThemeManager *thememanager);
0043 
0044     /**
0045      * Destructor
0046      */
0047     virtual ~Themeable();
0048 
0049     /**
0050      * Retrieve the ID of the object.
0051      * @return The ID.
0052      */
0053     QString id()
0054     {
0055         return mId;
0056     }
0057 
0058     /**
0059      * Retrieve the associated theme manager of this object.
0060      * @return The theme manager.
0061      */
0062     ThemeManager *thememanager()
0063     {
0064         return mThemeManager;
0065     }
0066 
0067     /**
0068      * Retrieve the current scale (maximum extension) of the theme.
0069      * @return The current scale.
0070      */
0071     double getScale()
0072     {
0073         return mScale;
0074     }
0075 
0076     /**
0077      * Set the current scale for the object.
0078      * @param scale The new scale.
0079      */
0080     void setScale(double scale)
0081     {
0082         mScale = scale;
0083     }
0084 
0085     /**
0086      * Main theme notification method. This method is called in the
0087      * Themeable object to indicate a theme change. The object needs
0088      * to overwrite this and respond with a properly scaled redraw.
0089      */
0090     virtual void changeTheme() = 0;
0091 
0092 private:
0093     // The theme ID
0094     QString mId;
0095 
0096     // The theme manager
0097     ThemeManager *mThemeManager;
0098 
0099     // The current scale for the object (maximum extension)
0100     double mScale;
0101 };
0102 
0103 /**
0104  * The graphics theme manager. The theme manager holds a list of all Themeable
0105  * objects and notifies them in the event of a theme change so that the objects
0106  * can then redraw. It also allows access to the theme configuration file and
0107  * reads pixmaps from an SVG file given a certain size or scale. The pixmaps
0108  * are cached so that the same pixmap is retrieved from the cache on not rendered
0109  * again.
0110  */
0111 class ThemeManager : public QObject
0112 {
0113     Q_OBJECT
0114 public:
0115     /**
0116      * Constructor for the theme manager.
0117      * @param themefile   The theme configuration file
0118      * @param parent      The parent object
0119      * @param initialSize Initial theme size, can be arbitrary.
0120      */
0121     ThemeManager(const QString &themefile, QObject *parent, int initialSize = 1);
0122     ~ThemeManager() override;
0123 
0124     /**
0125      * Load a pixmap from the SVG theme file. Its filename is given in the
0126      * "general" section of the theme file as "svgfile". The pixmap is scaled
0127      * to the given size.
0128      * @param svgid  The ID of the SVG item to be rendered as pixmap
0129      * @param size   The size of the resulting pixmap
0130      * @return The new pixmap.
0131      */
0132     const QPixmap getPixmap(const QString &svgid, QSize size);
0133 
0134     /**
0135      * Gets the size of  a pixmap from the SVG theme file. Its filename is given in the
0136      * "general" section of the theme file as "svgfile". The size is scaled
0137      * to the given width. The height is relative to the width as given in the SVG
0138      * file.
0139      * @param svgid  The ID of the SVG item to be rendered as pixmap
0140      * @param width  The width of the resulting pixmap
0141      * @return The size.
0142      */
0143     QSize pixmapSize(const QString &svgid, double width) const;
0144 
0145     /**
0146      * Gets the size of a pixmap from the SVG theme file. Its filename is given in the
0147      * "general" section of the theme file as "svgfile". The size is scaled
0148      * with reference to another SVG item. This allows to generate a set of pixmaps
0149      * with related sizes.
0150      * @param svgid     The ID of the SVG item to be rendered as pixmap
0151      * @param svgref    The ID of the SVG item used as width reference
0152      * @param refwidth  The width of the resulting pixmap in relation to the reference item
0153      * @return The size.
0154      */
0155     QSize pixmapSize(const QString &svgid, const QString &svgref, double refwidth);
0156 
0157     /**
0158      * Retrieve the current scale of the theme.
0159      * @return The scale.
0160      */
0161     double getScale();
0162 
0163     /**
0164      * Retrieve the theme offset.
0165      * @return The offset.
0166      */
0167     QPoint getOffset();
0168 
0169     /**
0170      * Retrieve the current theme configuration object.
0171      * @return The configuration object.
0172      */
0173     KConfigGroup config(const QString &id);
0174 
0175     /**
0176      * Register an object with the theme manager.
0177      * @param ob The object to be registered.
0178      */
0179     void registerTheme(Themeable *ob);
0180 
0181     /**
0182      * Unregister an object with the theme manager.
0183      * @param ob The object to be unregistered.
0184      */
0185     void unregisterTheme(Themeable *ob);
0186 
0187     /**
0188      * Forces an update to a theme objects. That is its
0189      * changeTheme() method is called.
0190      * @param ob The object to be updated.
0191      */
0192     void updateTheme(Themeable *ob);
0193 
0194     /**
0195      * Forces an update to all theme objects. That is their
0196      * changeTheme() method is called. Before this a (new)
0197      * theme file is loaded and all cached pixmaps deleted. This
0198      * is used to really change one theme over to another one.
0199      * @param themefile The theme file to load
0200      */
0201     void updateTheme(const QString &themefile);
0202 
0203     /**
0204      * Change the scale of the theme and update all registered
0205      * theme objects.
0206      * @param scale The new scale (maximum extension)
0207      * @param offset The new offset of the theme (left upper corner)
0208      */
0209     void rescale(int scale, QPoint offset);
0210 
0211     /**
0212      * Retrieve the theme's apsect ratio. This is stored as
0213      * 'aspect-ratio' key in the 'general' group of the theme.
0214      * @return The aspect ratio (x/y).
0215      */
0216     double aspectRatio()
0217     {
0218         return mAspectRatio;
0219     }
0220 
0221     /**
0222      * Retrieve the translated theme's color for specified player. Colors are stored
0223      * as 'colorNamePlayer0' and 'colorNamePlayer1' key in the 'general'
0224      * group of the theme.
0225      * @return The color name for player.
0226      */
0227     QString colorNamePlayer(int player)
0228     {
0229         return mColorNamePlayer[player];
0230     }
0231 
0232     /**
0233      * Check whether the theme is properly initialized.
0234      * @return 0 if everything is alright
0235      */
0236     int checkTheme();
0237 
0238     /**
0239      * Check whether a changeTheme call was due to themefile change
0240      * or a rescaling.
0241      */
0242     bool themefileChanged();
0243 
0244 private:
0245     // The used SVG rendered
0246     QSvgRenderer *mRenderer;
0247 
0248     // Storage of all theme objects
0249     QList<Themeable *> mObjects;
0250 
0251     // The cache of all pixmap objects [id,pixmap]
0252     QHash<QString, QPixmap> mPixmapCache;
0253 
0254     // The theme configuration file
0255     KConfig *mConfig;
0256 
0257     // The current theme scale
0258     int mScale;
0259 
0260     // The current offset
0261     QPoint mOffset;
0262 
0263     // The aspect ration
0264     double mAspectRatio;
0265 
0266     // Color names for players.
0267     QString mColorNamePlayer[2];
0268 
0269     // Type of theme change
0270     bool mThemeFileChanged;
0271 };
0272 
0273 #endif