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 KGTHEME_H |
20 | #define KGTHEME_H |
21 | |
22 | //The complete API needs to be there when compiling libkdegames. |
23 | #ifdef MAKE_KDEGAMES_LIB |
24 | #define KGTHEME_PROVIDE_COMPATIBILITY_API |
25 | #endif //MAKE_KDEGAMES_LIB |
26 | |
27 | #include <QtCore/QMetaType> |
28 | #include <QtCore/QObject> |
29 | #include <QtGui/QPixmap> |
30 | |
31 | #include <libkdegames_export.h> |
32 | |
33 | /** |
34 | * @class KgTheme kgtheme.h <KgTheme> |
35 | * |
36 | * A theme describes the visual appearance of a game. Themes in kdegames usually |
37 | * reference a SVGZ file which is loaded into a KGameRenderer to provide pixmaps |
38 | * for use on the game canvas. |
39 | * |
40 | * Themes are usually managed (and discovered) by a KgThemeProvider. |
41 | * |
42 | * @section fileformat Default file format for theme descriptions |
43 | * |
44 | * Although KgTheme and KgThemeProvider do not need special theme description |
45 | * files for most basic usage, there is a format for theme description files |
46 | * based on the XDG Desktop File Specification. The following example shows the |
47 | * recognized keys: |
48 | * |
49 | * @code |
50 | * [KGameTheme] |
51 | * VersionFormat=1 |
52 | * Name=Example |
53 | * Description=This theme serves as an example. |
54 | * FileName=example.svgz |
55 | * Author=John Doe |
56 | * AuthorEmail=john.doe@example.com |
57 | * Preview=example.png |
58 | * @endcode |
59 | * |
60 | * All keys are considered optional, except perhaps for the "FileName" key: If |
61 | * that is not given, the theme cannot be used with KGameRenderer. The paths in |
62 | * "FileName" and "Preview" are resolved relative to the directory that contains |
63 | * the theme description file. |
64 | * |
65 | * If the [KGameTheme] group contains any further keys, their values can be |
66 | * retrieved through the KgTheme::customData() method. |
67 | */ |
68 | class KDEGAMES_EXPORT KgTheme : public QObject |
69 | { |
70 | Q_OBJECT |
71 | Q_PROPERTY(QByteArray identifier READ identifier NOTIFY readOnlyProperty) |
72 | //it is not intended to allow these properties to change after the initial |
73 | //setup (note how KgThemeProvider returns only const KgTheme*), hence |
74 | //a dummy NOTIFY signal is enough |
75 | Q_PROPERTY(QString name READ name WRITE setName NOTIFY readOnlyProperty) |
76 | Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY readOnlyProperty) |
77 | Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY readOnlyProperty) |
78 | Q_PROPERTY(QString authorEmail READ authorEmail WRITE setAuthorEmail NOTIFY readOnlyProperty) |
79 | Q_PROPERTY(QString graphicsPath READ graphicsPath WRITE setGraphicsPath NOTIFY readOnlyProperty) |
80 | Q_PROPERTY(QString previewPath READ previewPath WRITE setPreviewPath NOTIFY readOnlyProperty) |
81 | Q_DISABLE_COPY(KgTheme) |
82 | public: |
83 | ///Constructor. The @a identifier must be application-unique. |
84 | explicit KgTheme(const QByteArray& identifier, QObject* parent = 0); |
85 | ///Destructor. |
86 | virtual ~KgTheme(); |
87 | |
88 | ///Initializes a KgTheme instance by reading a description file. |
89 | ///@return whether @a path is a valid theme description file (if not, |
90 | /// the theme instance is not changed by this method call) |
91 | ///@note A non-static member function has been chosen over the more |
92 | /// common pattern of using a static member function like |
93 | /// "KgTheme::fromDesktopFile" to accommodate applications which |
94 | /// want to subclass KgTheme. |
95 | virtual bool readFromDesktopFile(const QString& path); |
96 | |
97 | #ifdef KGTHEME_PROVIDE_COMPATIBILITY_API |
98 | ///Use a different group name in theme description files. For example, |
99 | ///KMahjongg backgrounds and tilesets use "[KMahjonggBackground]" and |
100 | ///"[KMahjonggTileset]" instead of "[KGameTheme]". |
101 | static void addConfigGroupName(const QString& name); |
102 | #endif |
103 | |
104 | ///@return the internal identifier for this theme (used e.g. for |
105 | /// finding a pixmap cache or storing a theme selection) |
106 | QByteArray identifier() const; |
107 | |
108 | ///@return the name of this theme |
109 | QString name() const; |
110 | ///@see name() |
111 | void setName(const QString& name); |
112 | ///@return an additional description beyond the name() |
113 | QString description() const; |
114 | ///@see description() |
115 | void setDescription(const QString& description); |
116 | ///@return the name of the theme author |
117 | QString author() const; |
118 | ///@see author() |
119 | void setAuthor(const QString& author); |
120 | ///@return the email address of the theme author |
121 | QString authorEmail() const; |
122 | ///@see authorEmail() |
123 | void setAuthorEmail(const QString& authorEmail); |
124 | |
125 | ///@return the path of the SVG file which holds the theme contents |
126 | QString graphicsPath() const; |
127 | ///@see graphicsPath() |
128 | void setGraphicsPath(const QString& path); |
129 | ///@return the path to an image file containing a preview, or an empty |
130 | /// string if no preview file is known |
131 | QString previewPath() const; |
132 | ///@see previewPath() |
133 | void setPreviewPath(const QString& path); |
134 | |
135 | ///@return custom data |
136 | /// |
137 | ///This API is provided for theme description files which contain |
138 | ///additional application-specific metadata. |
139 | QMap<QString, QString> customData() const; |
140 | ///@overload that returns a single value from the customData() map |
141 | QString customData(const QString& key, const QString& defaultValue = QString()) const; |
142 | ///@see customData() |
143 | void setCustomData(const QMap<QString, QString>& customData); |
144 | Q_SIGNALS: |
145 | ///This signal is never emitted. It is provided because QML likes to |
146 | ///complain about properties without NOTIFY signals, even readonly ones. |
147 | void readOnlyProperty(); |
148 | private: |
149 | class Private; |
150 | Private* const d; |
151 | }; |
152 | |
153 | Q_DECLARE_METATYPE(const KgTheme*) |
154 | |
155 | #endif // KGTHEME_H |
156 | |