KGameHighscore Class
Class for managing highscore tables. More...
| Header: | #include <KGameHighscore> |
| Inherits: | QObject |
Public Functions
| KGameHighscore(bool forceLocal = true, QObject *parent = nullptr) | |
| virtual | ~KGameHighscore() override |
| QStringList | groupList() const |
| bool | hasEntry(int entry, const QString &key) const |
| bool | hasTable() const |
| QString | highscoreGroup() const |
| bool | isLocked() const |
| bool | lockForWriting(QWidget *widget = nullptr) |
| void | readCurrentConfig() |
| QString | readEntry(int entry, const QString &key, const QString &pDefault = QString()) const |
| QStringList | readList(const QString &key, int lastEntry = 20) const |
| int | readNumEntry(int entry, const QString &key, int pDefault = -1) const |
| QVariant | readPropertyEntry(int entry, const QString &key, const QVariant &pDefault) const |
| void | setHighscoreGroup(const QString &groupname = QString()) |
| void | writeAndUnlock() |
| void | writeEntry(int entry, const QString &key, const QString &value) |
| void | writeEntry(int entry, const QString &key, const QVariant &value) |
| void | writeEntry(int entry, const QString &key, int value) |
| void | writeList(const QString &key, const QStringList &list) |
Static Public Members
| void | init(const char *appname) |
Protected Functions
Detailed Description
This is the KDE class for saving and reading highscore tables. It offers the possibility for system-wide highscore tables (cmake with e.g. -DHIGHSCORE_DIRECTORY=/var/games) and a theoretically unlimited number of entries.
You can specify different "keys" for an entry - just like the KConfig keys. But it will be prefixed with the number of the entry. For example you will probably use something like this to save the name of the player on the top of the list (ie the winner):
highscore->writeEntry(1, "name", myPlayer->name());
Note that it does not really matter if you use "0" or "1" as the first entry of the list as long as your program always uses the same for the first entry. I recommend to use "1", as several convenience methods use this.
You can also specify different groups using setHighscoreGroup. Just like the keys mentioned above the groups behave like groups in KConfig but are prefixed with "KHighscore_". The default group is just "KHighscore". You might use this e.g. to create different highscore tables like
table->setHighscoreGroup("Easy");
// write the highscores for level "easy" to the table
writeEasyHighscores(table);
table->setHighscore("Player_1");
// write player specific highscores to the table
writePlayerHighscores(table);
As you can see above you can also use this to write the highscores of a single player, so the "best times" of a player. To write highscores for a specific player in a specific level you will have to use a more complex way:
QString group = QStringLiteral("%1_%2").arg(player).arg(level);
table->setGroup(group);
writeHighscore(table, player, level);
Also note that you MUST NOT mark the key or the group for translation! I.e. don't use i18n() for the keys or groups! Here is the code to read the above written entry:
QString firstName = highscore->readEntry(0, "name");
Easy, what?
Member Function Documentation
[explicit] KGameHighscore::KGameHighscore(bool forceLocal = true, QObject *parent = nullptr)
Constructor.
If forceLocal is true, the local highscore file is used even when the configuration has been set to use a system-wide file. This is convenient for converting highscores from legacy applications. parent is the parent widget for this widget.
[override virtual noexcept] KGameHighscore::~KGameHighscore()
Destructor. If necessary, writes and unlocks the highscore file.
[protected] KConfig *KGameHighscore::config() const
Returns a pointer to the KConfig object to be used. This is either KGlobal::config() (default) or a KSimpleConfig object for a system-wide highscore file.
[protected] QString KGameHighscore::group() const
Returns a groupname to be used in KConfig. Used internally to prefix the value from highscoreGroup() with "KHighscore_".
QStringList KGameHighscore::groupList() const
Returns a list of group names without the KHighscore_ prefix. For example, "KHighscore", "KHighscore_Easy", "KHighscore_Medium" will return "", "Easy", "Medium"
bool KGameHighscore::hasEntry(int entry, const QString &key) const
Returns true if the highscore table contains the entry and key pair, otherwise false.
bool KGameHighscore::hasTable() const
You can use this function to indicate whether KGameHighscore created a highscore table before and - if not - read your old (non-KGameHighscore) table instead. This way you can safely read an old table and save it using KGameHighscore without losing any data. Returns whether a highscore table exists.
QString KGameHighscore::highscoreGroup() const
Returns the currently used group. This doesn't contain the prefix ("KHighscore_") but the same as setHighscoreGroup uses. The default is QString().
See also setHighscoreGroup().
[protected] void KGameHighscore::init(bool forceLocal)
If forceLocal is true, the local highscore file is used even when the configuration has been set to use a system-wide file. This is convenient for converting highscores from legacy applications.
[static] void KGameHighscore::init(const char *appname)
This method opens the system-wide highscore file for appname using the effective group id of the game executable (which should be "games"). The effective group id is completely dropped afterwards.
Note: This method should be called in main() before creating a KApplication and doing anything else (KApplication checks that the program is not suid/sgid and will exit the program for security reason if it is the case).
bool KGameHighscore::isLocked() const
Returns true if the highscore file is locked or if a local file is used.
bool KGameHighscore::lockForWriting(QWidget *widget = nullptr)
Lock the system-wide highscore file for writing (does nothing and return true if the local file is used). You should perform writing without GUI interaction to avoid blocking and don't forget to unlock the file as soon as possible with writeAndUnlock().
If the config file cannot be locked, the method waits for 1 second and, if it failed again, displays a message box asking for retry or cancel. widget is used as the parent of the message box.
Returns false on error or if the config file is locked by another process. In such case, the config stays read-only.
void KGameHighscore::readCurrentConfig()
Read the current state of the highscore file. Remember that when it's not locked for writing, this file can change at any time. (This method is only useful for a system-wide highscore file.)
QString KGameHighscore::readEntry(int entry, const QString &key, const QString &pDefault = QString()) const
Reads an entry from the highscore table. entry is the number of the entry / the placing of the player. key is a key for this entry, for example "name" for the name of the player. Nearly the same as the usual keys in KConfig - but they are prefixed with the entry number. pDefault will be used as default value if the key+pair entry can't be found. Returns the value of this entry and key pair or pDefault if the entry and key pair doesn't exist.
QStringList KGameHighscore::readList(const QString &key, int lastEntry = 20) const
Reads a list of entries from the highscore table starting at 1 until lastEntry. If an entry between those numbers doesn't exist the function aborts reading even if after the missing entry is an existing one. The first entry of the list is the first placing, the last one is the last placing. Returns a list of the entries of this key. You could also call readEntry(i, key) where i is from 1 to 20. Note that this function depends on "1" as the first entry! key The key of the entry, for example "name" for the name of the player. Nearly the same as the usual keys in KConfig - but they are prefixed with the entry number lastEntry the last entry which will be included into the list. 1 will include a list with maximal 1 entry - 20 a list with maximal 20 entries. If lastEntry is <= 0 then reading is only stopped when when an entry does not exist.
int KGameHighscore::readNumEntry(int entry, const QString &key, int pDefault = -1) const
Read a numeric value. entry is the number of the entry / the placing of the player. key is a key for this entry, for example "name" for the name of the player. Nearly the same as the usual keys in KConfig - but they are prefixed with the entry number. pDefault will be used as default value if the key+pair entry can't be found. Returns the value of this entry and key pair or pDefault if the entry and key pair doesn't exist.
See also writeEntry.
QVariant KGameHighscore::readPropertyEntry(int entry, const QString &key, const QVariant &pDefault) const
Reads a QVariant entry. See KConfigBase documentation for allowed QVariant::Type.
Returns the value of this entry and key pair, or pDefault if the entry and key pair doesn't exist.
void KGameHighscore::setHighscoreGroup(const QString &groupname = QString())
Sets the new highscore group to groupname. The group is being prefixed with "KHighscore_" in the table. groupname is the new groupname. For example, use "easy" for the easy level of your game. If you use QString() (the default) the default group is used.
See also highscoreGroup().
void KGameHighscore::writeAndUnlock()
Effectively writes and unlocks the system-wide highscore file. If using a local highscore file, it will sync the config.
See also lockForWriting.
void KGameHighscore::writeEntry(int entry, const QString &key, const QString &value)
entry is the number of the entry / the placing of the player. key is a key for this entry, for example "name" for the name of the player. Nearly the same as the usual keys in KConfig - but they are prefixed with the entry number. value is value of this entry.
void KGameHighscore::writeEntry(int entry, const QString &key, const QVariant &value)
See KConfigBase documentation for allowed QVariant::Type.
This is an overloaded function.
void KGameHighscore::writeEntry(int entry, const QString &key, int value)
This is an overloaded function.
See also readNumEntry.
void KGameHighscore::writeList(const QString &key, const QStringList &list)
Writes a list of entries list to the highscore table.
The first entry is prefixed with "1". Using this method is a short way of calling writeEntry(i, key, list[i]) from i = 1 to list.count() key is a key for the entry, for example, "name" for the name of the player. Nearly the same as the usual keys in KConfig - but they are prefixed with the entry number.