/*************************************************************************** * Copyright 2012 Stefan Majewsky * * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU Library General Public License * * version 2 as published by the Free Software Foundation * * * * This program is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU Library General Public License for more details. * * * * You should have received a copy of the GNU Library General Public * * License along with this program; if not, write to the * * Free Software Foundation, Inc., * * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * ***************************************************************************/ #ifndef KGTHEME_H #define KGTHEME_H //The complete API needs to be there when compiling libkdegames. #ifdef MAKE_KDEGAMES_LIB #define KGTHEME_PROVIDE_COMPATIBILITY_API #endif //MAKE_KDEGAMES_LIB #include #include #include #include /** * @class KgTheme kgtheme.h * * A theme describes the visual appearance of a game. Themes in kdegames usually * reference a SVGZ file which is loaded into a KGameRenderer to provide pixmaps * for use on the game canvas. * * Themes are usually managed (and discovered) by a KgThemeProvider. * * @section fileformat Default file format for theme descriptions * * Although KgTheme and KgThemeProvider do not need special theme description * files for most basic usage, there is a format for theme description files * based on the XDG Desktop File Specification. The following example shows the * recognized keys: * * @code * [KGameTheme] * VersionFormat=1 * Name=Example * Description=This theme serves as an example. * FileName=example.svgz * Author=John Doe * AuthorEmail=john.doe@example.com * Preview=example.png * @endcode * * All keys are considered optional, except perhaps for the "FileName" key: If * that is not given, the theme cannot be used with KGameRenderer. The paths in * "FileName" and "Preview" are resolved relative to the directory that contains * the theme description file. * * If the [KGameTheme] group contains any further keys, their values can be * retrieved through the KgTheme::customData() method. */ class KDEGAMES_EXPORT KgTheme : public QObject { Q_OBJECT Q_PROPERTY(QByteArray identifier READ identifier NOTIFY readOnlyProperty) //it is not intended to allow these properties to change after the initial //setup (note how KgThemeProvider returns only const KgTheme*), hence //a dummy NOTIFY signal is enough Q_PROPERTY(QString name READ name WRITE setName NOTIFY readOnlyProperty) Q_PROPERTY(QString description READ description WRITE setDescription NOTIFY readOnlyProperty) Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY readOnlyProperty) Q_PROPERTY(QString authorEmail READ authorEmail WRITE setAuthorEmail NOTIFY readOnlyProperty) Q_PROPERTY(QString graphicsPath READ graphicsPath WRITE setGraphicsPath NOTIFY readOnlyProperty) Q_PROPERTY(QString previewPath READ previewPath WRITE setPreviewPath NOTIFY readOnlyProperty) Q_DISABLE_COPY(KgTheme) public: ///Constructor. The @a identifier must be application-unique. explicit KgTheme(const QByteArray& identifier, QObject* parent = 0); ///Destructor. virtual ~KgTheme(); ///Initializes a KgTheme instance by reading a description file. ///@return whether @a path is a valid theme description file (if not, /// the theme instance is not changed by this method call) ///@note A non-static member function has been chosen over the more /// common pattern of using a static member function like /// "KgTheme::fromDesktopFile" to accommodate applications which /// want to subclass KgTheme. virtual bool readFromDesktopFile(const QString& path); #ifdef KGTHEME_PROVIDE_COMPATIBILITY_API ///Use a different group name in theme description files. For example, ///KMahjongg backgrounds and tilesets use "[KMahjonggBackground]" and ///"[KMahjonggTileset]" instead of "[KGameTheme]". static void addConfigGroupName(const QString& name); #endif ///@return the internal identifier for this theme (used e.g. for /// finding a pixmap cache or storing a theme selection) QByteArray identifier() const; ///@return the name of this theme QString name() const; ///@see name() void setName(const QString& name); ///@return an additional description beyond the name() QString description() const; ///@see description() void setDescription(const QString& description); ///@return the name of the theme author QString author() const; ///@see author() void setAuthor(const QString& author); ///@return the email address of the theme author QString authorEmail() const; ///@see authorEmail() void setAuthorEmail(const QString& authorEmail); ///@return the path of the SVG file which holds the theme contents QString graphicsPath() const; ///@see graphicsPath() void setGraphicsPath(const QString& path); ///@return the path to an image file containing a preview, or an empty /// string if no preview file is known QString previewPath() const; ///@see previewPath() void setPreviewPath(const QString& path); ///@return custom data /// ///This API is provided for theme description files which contain ///additional application-specific metadata. QMap customData() const; ///@overload that returns a single value from the customData() map QString customData(const QString& key, const QString& defaultValue = QString()) const; ///@see customData() void setCustomData(const QMap& customData); Q_SIGNALS: ///This signal is never emitted. It is provided because QML likes to ///complain about properties without NOTIFY signals, even readonly ones. void readOnlyProperty(); private: class Private; Private* const d; }; Q_DECLARE_METATYPE(const KgTheme*) #endif // KGTHEME_H