1 | /*************************************************************************** |
2 | * Copyright 2012 Stefan Majewsky <majewsky@gmx.net> * |
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 * |
6 | * version 2 as published by the Free Software Foundation * |
7 | * * |
8 | * This program is distributed in the hope that it will be useful, * |
9 | * but WITHOUT ANY WARRANTY; without even the implied warranty of * |
10 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * |
11 | * GNU Library General Public License for more details. * |
12 | * * |
13 | * You should have received a copy of the GNU Library General Public * |
14 | * License along with this program; if not, write to the * |
15 | * Free Software Foundation, Inc., * |
16 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * |
17 | ***************************************************************************/ |
18 | |
19 | #ifndef KGTHEMEPROVIDER_H |
20 | #define KGTHEMEPROVIDER_H |
21 | |
22 | #include <QtCore/QObject> |
23 | #include <QtDeclarative> |
24 | |
25 | #include <kgtheme.h> |
26 | #include <libkdegames_export.h> |
27 | |
28 | /** |
29 | * @class KgThemeProvider kgthemeprovider.h <KgThemeProvider> |
30 | * |
31 | * A theme provider manages KgTheme instances, and maintains a selection of |
32 | * the currentTheme(). It can automatically coordinate its selection with a |
33 | * KGameRenderer instance. |
34 | * |
35 | * @note KgThemeProvider instances store selections in the application config, |
36 | * in the group [KgTheme]. This is documented here because this |
37 | * information is relevant for kconfig_ |
38 | */ |
39 | class KDEGAMES_EXPORT KgThemeProvider : public QObject |
40 | { |
41 | Q_OBJECT |
42 | Q_PROPERTY(const KgTheme* currentTheme READ currentTheme WRITE setCurrentTheme NOTIFY currentThemeChanged) |
43 | Q_PROPERTY(QString name READ name NOTIFY nameChanged) |
44 | Q_PROPERTY(QString currentThemeName READ currentThemeName NOTIFY currentThemeNameChanged) |
45 | Q_DISABLE_COPY(KgThemeProvider) |
46 | public: |
47 | ///Constructor. If you don't want KgThemeProvider to store the current |
48 | ///theme selection in the application config file automatically, set |
49 | ///@a configKey to an empty QByteArray. |
50 | /// |
51 | ///If there are multiple KgThemeProvider instances, make sure they use |
52 | ///different config keys to avoid collisions. |
53 | explicit KgThemeProvider(const QByteArray& configKey = QByteArray("Theme" ), QObject* parent = 0); |
54 | ///Destructor. |
55 | virtual ~KgThemeProvider(); |
56 | |
57 | ///@return the name of the KgThemeProvider object. This name can be |
58 | ///used as QML element ID to reference the object inside QML. |
59 | ///@since 4.11 |
60 | QString name() const; |
61 | |
62 | ///@return the themes in this provider |
63 | QList<const KgTheme*> themes() const; |
64 | ///@return the default theme, or 0 if the provider does not contain any |
65 | ///themes |
66 | const KgTheme* defaultTheme() const; |
67 | ///@see defaultTheme() |
68 | /// |
69 | ///Usually this will be set automatically by discoverThemes(). Call this |
70 | ///before the first call to currentTheme(), it won't have any effect |
71 | ///afterwards. @a theme must already have been added to this instance. |
72 | void setDefaultTheme(const KgTheme* theme); |
73 | ///@return the currently selected theme, or 0 if the provider does not |
74 | ///contain any themes |
75 | /// |
76 | ///After the KgThemeProvider instance has been created, the current |
77 | ///theme will not be determined until this method is called |
78 | ///for the first time. This allows the application developer to set up |
79 | ///the theme provider before it restores the theme selection from the |
80 | ///configuration file. |
81 | const KgTheme* currentTheme() const; |
82 | |
83 | ///@return the name of the current theme |
84 | ///@since 4.11 |
85 | QString currentThemeName() const; |
86 | |
87 | ///Adds a @a theme to this instance. The theme provider takes ownership |
88 | ///of @a theme. |
89 | void addTheme(KgTheme* theme); |
90 | ///This method reads theme description files from a standard location. |
91 | ///The first two arguments are passed to KStandardDirs like this: |
92 | ///@code |
93 | ///KGlobal::dirs()->findAllResources(resource, directory + "/*.desktop"); |
94 | ///@endcode |
95 | ///The typical usage is to install theme description files in |
96 | ///@code ${DATA_INSTALL_DIR}/themes @endcode and then call: |
97 | ///@code |
98 | ///themeProvider.discoverThemes("appdata", QLatin1String("themes")); |
99 | ///@endcode |
100 | ///If a @a themeClass's QMetaObject is given, the created themes will be |
101 | ///instances of this KgTheme subclass. The @a themeClass must export |
102 | ///(with the Q_INVOKABLE marker) a constructor with the same signature |
103 | ///as the KgTheme constructor. |
104 | void discoverThemes(const QByteArray& resource, const QString& directory, const QString& defaultThemeName = QLatin1String("default" ), const QMetaObject* themeClass = 0); |
105 | ///After this provider has been set up with discoverThemes(), this |
106 | ///method may be used to read additional themes which were added since |
107 | ///the discoverThemes() call. This is esp. useful for KNewStuff |
108 | ///integration. |
109 | void rediscoverThemes(); |
110 | |
111 | ///Generate a preview pixmap for the given theme. The application will |
112 | ///typically want to reimplement this to load the given theme into a |
113 | ///KGameRenderer and then arrange some sprites into a preview. |
114 | /// |
115 | ///@a size is the maximal allowed size. |
116 | /// |
117 | ///The default implementation tries to load a preview image from |
118 | ///KgTheme::previewPath(), and resizes the result to fit in @a size. |
119 | virtual QPixmap generatePreview(const KgTheme* theme, const QSize& size); |
120 | |
121 | ///Registers this KgThemeProvider with @param engine's root context with ID |
122 | ///@param name and constructs a KgImageProvider corresponding |
123 | ///to this KgThemeProvider and adds it to the QML engine, also |
124 | ///with @param name, which will receive sprite requests |
125 | ///@since 4.11 |
126 | void setDeclarativeEngine(const QString& name, QDeclarativeEngine* engine); |
127 | Q_SIGNALS: |
128 | ///Emitted when the current theme changes. @see setCurrentTheme |
129 | void currentThemeChanged(const KgTheme* theme); |
130 | ///Emitted when the name of the provider changes. |
131 | ///@since 4.11 |
132 | void nameChanged(const QString& name); |
133 | ///Emitts the new theme name when the current theme changes. |
134 | ///@since 4.11 |
135 | void currentThemeNameChanged(const QString& themeName); |
136 | public Q_SLOTS: |
137 | ///Select a new theme. The given theme must already have been added to |
138 | ///this instance. |
139 | void setCurrentTheme(const KgTheme* theme); |
140 | private: |
141 | class Private; |
142 | Private* const d; |
143 | Q_PRIVATE_SLOT(d, void updateThemeName()); |
144 | }; |
145 | |
146 | Q_DECLARE_METATYPE(KgThemeProvider*) |
147 | QML_DECLARE_TYPE(KgThemeProvider*) |
148 | |
149 | #endif // KGTHEMEPROVIDER_H |
150 | |