KDEGames

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

KDE's Doxygen guidelines are available online.