KDEGames

kgametheme.h
1/*
2 SPDX-FileCopyrightText: 2012 Stefan Majewsky <majewsky@gmx.net>
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
46 * AuthorEmail=john.doe@example.com
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
59class 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)
77 Q_DISABLE_COPY(KGameTheme)
78
79public:
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()
104 /// @see description()
105 void setDescription(const QString &description);
106 /// @return the short license identifier, as SPDX expression
108 /// @see license()
109 void setLicense(const QString &license);
110 /// @return a short copyright statement
112 /// @see copyrightText()
113 void setCopyrightText(const QString &copyrightText);
114 /// @return the version of the theme.
116 /// @see version()
117 void setVersion(const QString &version);
118 /// @return the website of the theme.
120 /// @see website()
121 void setWebsite(const QString &website);
122 /// @return the website where people can report a bug found in this theme.
124 /// @see bugReportUrl()
125 void setBugReportUrl(const QString &bugReportUrl);
126 /// @return the name of the theme author
128 /// @see author()
129 void setAuthor(const QString &author);
130 /// @return the email address of the theme author
132 /// @see authorEmail()
133 void setAuthorEmail(const QString &authorEmail);
134
135 /// @return the path of the SVG file which holds the theme contents
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
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);
155 /// This signal is never emitted. It is provided because QML likes to
156 /// complain about properties without NOTIFY signals, even readonly ones.
158
159private:
160 std::unique_ptr<class KGameThemePrivate> const d_ptr;
161 Q_DECLARE_PRIVATE(KGameTheme)
162};
163
164Q_DECLARE_METATYPE(const KGameTheme *)
165
166#endif // KGAMETHEME_H
A theme describes the visual appearance of a game.
Definition kgametheme.h:60
void setBugReportUrl(const QString &bugReportUrl)
QString bugReportUrl() const
void setDescription(const QString &description)
QString license() const
~KGameTheme() override
Destructor.
void setWebsite(const QString &website)
QString website() const
void readOnlyProperty()
This signal is never emitted.
void setPreviewPath(const QString &path)
void setGraphicsPath(const QString &path)
QString name() const
void setName(const QString &name)
QString authorEmail() const
QString description() const
void setVersion(const QString &version)
QString author() const
void setCopyrightText(const QString &copyrightText)
QString copyrightText() const
void setAuthorEmail(const QString &authorEmail)
void setLicense(const QString &license)
void setAuthor(const QString &author)
QString previewPath() const
QString graphicsPath() const
QString version() const
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 4 2024 11:58:10 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.