KDEGames

kgamethemeprovider.h
1/*
2 SPDX-FileCopyrightText: 2012 Stefan Majewsky <majewsky@gmx.net>
3
4 SPDX-License-Identifier: LGPL-2.0-only
5*/
6
7#ifndef KGAMETHEMEPROVIDER_H
8#define KGAMETHEMEPROVIDER_H
9
10// own
11#include "kdegames_export.h"
12#include "kgametheme.h"
13// Qt
14#include <QObject>
15#include <QQmlEngine>
16// Std
17#include <memory>
18
19/**
20 * @class KGameThemeProvider kgamethemeprovider.h <KGameThemeProvider>
21 *
22 * A theme provider manages KGameTheme instances, and maintains a selection of
23 * the currentTheme(). It can automatically coordinate its selection with a
24 * KGameRenderer instance.
25 *
26 * @note KGameThemeProvider instances store selections in the application config,
27 * in the group [KgTheme]. This is documented here because this
28 * information is relevant for kconfig_
29 */
30class KDEGAMES_EXPORT KGameThemeProvider : public QObject
31{
32 Q_OBJECT
33 Q_PROPERTY(const KGameTheme *currentTheme READ currentTheme WRITE setCurrentTheme NOTIFY currentThemeChanged)
34 Q_PROPERTY(QString name READ name NOTIFY nameChanged)
35 Q_PROPERTY(QString currentThemeName READ currentThemeName NOTIFY currentThemeNameChanged)
37
38public:
39 /// Constructor. If you don't want KGameThemeProvider to store the current
40 /// theme selection in the application config file automatically, set
41 /// @a configKey to an empty QByteArray.
42 ///
43 /// If there are multiple KGameThemeProvider instances, make sure they use
44 /// different config keys to avoid collisions.
45 explicit KGameThemeProvider(const QByteArray &configKey = QByteArrayLiteral("Theme"), QObject *parent = nullptr);
46 /// Destructor.
47 ~KGameThemeProvider() override;
48
49 /// @return the name of the KGameThemeProvider object. This name can be
50 /// used as QML element ID to reference the object inside QML.
51 /// @since 4.11
52 QString name() const;
53
54 /// @return the themes in this provider
55 QList<const KGameTheme *> themes() const;
56 /// @return the default theme, or 0 if the provider does not contain any
57 /// themes
58 const KGameTheme *defaultTheme() const;
59 /// @see defaultTheme()
60 ///
61 /// Usually this will be set automatically by discoverThemes(). Call this
62 /// before the first call to currentTheme(), it won't have any effect
63 /// afterwards. @a theme must already have been added to this instance.
64 void setDefaultTheme(const KGameTheme *theme);
65 /// @return the currently selected theme, or 0 if the provider does not
66 /// contain any themes
67 ///
68 /// After the KGameThemeProvider instance has been created, the current
69 /// theme will not be determined until this method is called
70 /// for the first time. This allows the application developer to set up
71 /// the theme provider before it restores the theme selection from the
72 /// configuration file.
73 const KGameTheme *currentTheme() const;
74
75 /// @return the name of the current theme
76 /// @since 4.11
77 QString currentThemeName() const;
78
79 /// Adds a @a theme to this instance. The theme provider takes ownership
80 /// of @a theme.
81 void addTheme(KGameTheme *theme);
82 /// This method reads theme description files from a standard location.
83 /// The @p directory argument is passed to QStandardPaths like this:
84 /// @code
85 /// QStandardPaths::locateAll(QStandardPaths::AppDataLocation, directory, QStandardPaths::LocateDirectory)
86 /// @endcode
87 /// The typical usage is to install theme description files in
88 /// @code
89 ///${KDE_INSTALL_DATADIR}/<appname>/themes
90 /// @endcode
91 /// and then call:
92 /// @code
93 /// themeProvider.discoverThemes(QStringLiteral("themes"));
94 /// @endcode
95 /// If a @p themeClass's QMetaObject is given, the created themes will be
96 /// instances of this KGameTheme subclass. The @p themeClass must export
97 /// (with the Q_INVOKABLE marker) a constructor with the same signature
98 /// as the KGameTheme constructor.
99 /// @since 7.4
100 void discoverThemes(const QString &directory, const QString &defaultThemeName = QStringLiteral("default"), const QMetaObject *themeClass = nullptr);
101 /// After this provider has been set up with discoverThemes(), this
102 /// method may be used to read additional themes which were added since
103 /// the discoverThemes() call. This is esp. useful for KNewStuff
104 /// integration.
105 void rediscoverThemes();
106
107 /// Generate a preview pixmap for the given theme. The application will
108 /// typically want to reimplement this to load the given theme into a
109 /// KGameRenderer and then arrange some sprites into a preview.
110 ///
111 /// @a size is the maximal allowed size.
112 ///
113 /// The default implementation tries to load a preview image from
114 /// KGameTheme::previewPath(), and resizes the result to fit in @a size.
115 virtual QPixmap generatePreview(const KGameTheme *theme, QSize size);
116
117 /// Registers this KGameThemeProvider with @a engine's root context with ID
118 /// @a name and constructs a KGameImageProvider corresponding
119 /// to this KGameThemeProvider and adds it to the QML engine, also
120 /// with @a name, which will receive sprite requests
121 /// @since 4.11
122 void setDeclarativeEngine(const QString &name, QQmlEngine *engine);
123
125 /// Emitted when the current theme changes. @see setCurrentTheme
126 void currentThemeChanged(const KGameTheme *theme);
127 /// Emitted when the name of the provider changes.
128 /// @since 4.11
129 void nameChanged(const QString &name);
130 /// Emitted when the name of the current theme changes.
131 /// @since 4.11
132 void currentThemeNameChanged(const QString &themeName);
133
134public Q_SLOTS:
135 /// Select a new theme. The given theme must already have been added to
136 /// this instance.
137 void setCurrentTheme(const KGameTheme *theme);
138
139private:
140 std::unique_ptr<class KGameThemeProviderPrivate> const d_ptr;
142};
143
144Q_DECLARE_METATYPE(KGameThemeProvider *)
145QML_DECLARE_TYPE(KGameThemeProvider *)
146
147#endif // KGAMETHEMEPROVIDER_H
A theme provider manages KGameTheme instances, and maintains a selection of the currentTheme().
void currentThemeChanged(const KGameTheme *theme)
Emitted when the current theme changes.
void nameChanged(const QString &name)
Emitted when the name of the provider changes.
void currentThemeNameChanged(const QString &themeName)
Emitted when the name of the current theme changes.
A theme describes the visual appearance of a game.
Definition kgametheme.h:60
Q_PROPERTY(...)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
T qobject_cast(QObject *object)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 7 2024 12:03:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.