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 */
39class 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
146Q_DECLARE_METATYPE(KgThemeProvider*)
147QML_DECLARE_TYPE(KgThemeProvider*)
148
149#endif // KGTHEMEPROVIDER_H
150