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 */
68class 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
153Q_DECLARE_METATYPE(const KgTheme*)
154
155#endif // KGTHEME_H
156