KDEGames

kgtheme.h
1 /*
2  SPDX-FileCopyrightText: 2012 Stefan Majewsky <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-only
5 */
6 
7 #ifndef KGTHEME_H
8 #define KGTHEME_H
9 
10 // own
11 #include <libkdegames_export.h>
12 // Qt
13 #include <QMetaType>
14 #include <QObject>
15 #include <QLoggingCategory>
16 #include <QPixmap>
17 // Std
18 #include <memory>
19 
20 /**
21  * @class KgTheme kgtheme.h <KgTheme>
22  *
23  * A theme describes the visual appearance of a game. Themes in kdegames usually
24  * reference a SVGZ file which is loaded into a KGameRenderer to provide pixmaps
25  * for use on the game canvas.
26  *
27  * Themes are usually managed (and discovered) by a KgThemeProvider.
28  *
29  * @section fileformat Default file format for theme descriptions
30  *
31  * Although KgTheme and KgThemeProvider do not need special theme description
32  * files for most basic usage, there is a format for theme description files
33  * based on the XDG Desktop File Specification. The following example shows the
34  * recognized keys:
35  *
36  * @code
37  * [KGameTheme]
38  * VersionFormat=1
39  * Name=Example
40  * Description=This theme serves as an example.
41  * FileName=example.svgz
42  * Author=John Doe
44  * Preview=example.png
45  * @endcode
46  *
47  * All keys are considered optional, except perhaps for the "FileName" key: If
48  * that is not given, the theme cannot be used with KGameRenderer. The paths in
49  * "FileName" and "Preview" are resolved relative to the directory that contains
50  * the theme description file.
51  *
52  * If the [KGameTheme] group contains any further keys, their values can be
53  * retrieved through the KgTheme::customData() method.
54  */
55 
56 Q_DECLARE_LOGGING_CATEGORY(GAMES_LIB)
57 
58 class KDEGAMES_EXPORT KgTheme : public QObject
59 {
60  Q_OBJECT
61  Q_PROPERTY(QByteArray identifier READ identifier NOTIFY readOnlyProperty)
62  //it is not intended to allow these properties to change after the initial
63  //setup (note how KgThemeProvider returns only const KgTheme*), hence
64  //a dummy NOTIFY signal is enough
65  Q_PROPERTY(QString name READ name WRITE setName NOTIFY readOnlyProperty)
66  Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY readOnlyProperty)
67  Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY readOnlyProperty)
68  Q_PROPERTY(QString authorEmail READ authorEmail WRITE setAuthorEmail NOTIFY readOnlyProperty)
69  Q_PROPERTY(QString graphicsPath READ graphicsPath WRITE setGraphicsPath NOTIFY readOnlyProperty)
70  Q_PROPERTY(QString previewPath READ previewPath WRITE setPreviewPath NOTIFY readOnlyProperty)
71  Q_DISABLE_COPY(KgTheme)
72  public:
73  ///Constructor. The @a identifier must be application-unique.
74  explicit KgTheme(const QByteArray& identifier, QObject* parent = nullptr);
75  ///Destructor.
76  ~KgTheme() override;
77 
78  ///Initializes a KgTheme instance by reading a description file.
79  ///@return whether @a path is a valid theme description file (if not,
80  /// the theme instance is not changed by this method call)
81  ///@note A non-static member function has been chosen over the more
82  /// common pattern of using a static member function like
83  /// "KgTheme::fromDesktopFile" to accommodate applications which
84  /// want to subclass KgTheme.
85  virtual bool readFromDesktopFile(const QString& path);
86 
87  ///@return the internal identifier for this theme (used e.g. for
88  /// finding a pixmap cache or storing a theme selection)
89  QByteArray identifier() const;
90 
91  ///@return the name of this theme
92  QString name() const;
93  ///@see name()
94  void setName(const QString& name);
95  ///@return an additional description beyond the name()
96  QString description() const;
97  ///@see description()
98  void setDescription(const QString& description);
99  ///@return the name of the theme author
100  QString author() const;
101  ///@see author()
102  void setAuthor(const QString& author);
103  ///@return the email address of the theme author
104  QString authorEmail() const;
105  ///@see authorEmail()
106  void setAuthorEmail(const QString& authorEmail);
107 
108  ///@return the path of the SVG file which holds the theme contents
109  QString graphicsPath() const;
110  ///@see graphicsPath()
111  void setGraphicsPath(const QString& path);
112  ///@return the path to an image file containing a preview, or an empty
113  /// string if no preview file is known
114  QString previewPath() const;
115  ///@see previewPath()
116  void setPreviewPath(const QString& path);
117 
118  ///@return custom data
119  ///
120  ///This API is provided for theme description files which contain
121  ///additional application-specific metadata.
122  QMap<QString, QString> customData() const;
123  ///@overload that returns a single value from the customData() map
124  QString customData(const QString& key, const QString& defaultValue = QString()) const;
125  ///@see customData()
126  void setCustomData(const QMap<QString, QString>& customData);
127  Q_SIGNALS:
128  ///This signal is never emitted. It is provided because QML likes to
129  ///complain about properties without NOTIFY signals, even readonly ones.
130  void readOnlyProperty();
131  private:
132  std::unique_ptr<class KgThemePrivate> const d;
133 };
134 
135 Q_DECLARE_METATYPE(const KgTheme*)
136 
137 #endif // KGTHEME_H
const QLatin1String name
A theme describes the visual appearance of a game.
Definition: kgtheme.h:58
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Dec 7 2021 22:34:15 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.