KDEGames

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