• Skip to content
  • Skip to link menu
Trinity API Reference
  • Trinity API Reference
  • libtdegames
 

libtdegames

Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
KHighscore Class Reference

#include <khighscore.h>

Inherits TQObject.

Public Member Functions

 KHighscore (TQObject *parent=0)
 
 KHighscore (bool forceLocal, TQObject *parent)
 
void readCurrentConfig ()
 
bool lockForWriting (TQWidget *widget=0)
 
void writeAndUnlock ()
 
bool isLocked () const
 
 ~KHighscore ()
 
void writeEntry (int entry, const TQString &key, const TQString &value)
 
void writeEntry (int entry, const TQString &key, int value)
 
void writeEntry (int entry, const TQString &key, const TQVariant &value)
 
TQString readEntry (int entry, const TQString &key, const TQString &pDefault=TQString()) const
 
int readNumEntry (int entry, const TQString &key, int pDefault=-1) const
 
TQVariant readPropertyEntry (int entry, const TQString &key, const TQVariant &pDefault) const
 
bool hasEntry (int entry, const TQString &key) const
 
TQStringList readList (const TQString &key, int lastEntry=20) const
 
void writeList (const TQString &key, const TQStringList &list)
 
bool hasTable () const
 
void sync ()
 
void setHighscoreGroup (const TQString &groupname=TQString())
 
const TQString & highscoreGroup () const
 

Static Public Member Functions

static void init (const char *appname)
 

Protected Member Functions

TQString group () const
 
TDEConfig * config () const
 
void init (bool forceLocal)
 

Detailed Description

Class for managing highscore tables.

This is the KDE class for saving and reading highscore tables. It offers the possibility for system-wide highscore tables (configure with e.g. –enable-highscore-dir=/var/games) and a theoretically unlimited number of entries.

You can specify different "keys" for an entry - just like the TDEConfig 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 doesn't 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 TDEConfig 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:

TQString group = TQString("%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:

TQString firstName = highscore->readEntry(0, "name");

Easy, what?

Author
Andreas Beckermann b_man.nosp@m.n@gm.nosp@m.x.de

Definition at line 84 of file khighscore.h.

Constructor & Destructor Documentation

◆ KHighscore() [1/2]

KHighscore::KHighscore ( TQObject *  parent = 0)
Deprecated:
Constructor.

The highscore file is forced to be local to support games using the old behaviour.

Definition at line 59 of file khighscore.cpp.

◆ KHighscore() [2/2]

KHighscore::KHighscore ( bool  forceLocal,
TQObject *  parent 
)

Constructor.

Parameters
forceLocalif 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.
parentparent widget for this widget
Since
3.2

Definition at line 65 of file khighscore.cpp.

◆ ~KHighscore()

KHighscore::~KHighscore ( )

Destructor.

If necessary, write and unlock the highscore file.

Definition at line 157 of file khighscore.cpp.

Member Function Documentation

◆ config()

TDEConfig * KHighscore::config ( ) const
protected
Returns
A pointer to the TDEConfig object to be used. This is either kapp->config() (default) or a KSimpleConfig object for a system-wide highscore file.

Definition at line 163 of file khighscore.cpp.

◆ group()

TQString KHighscore::group ( ) const
protected
Returns
A groupname to be used in TDEConfig. Used internally to prefix the value from highscoreGroup() with "KHighscore_"

Definition at line 246 of file khighscore.cpp.

◆ hasEntry()

bool KHighscore::hasEntry ( int  entry,
const TQString &  key 
) const
Returns
True if the highscore table conatins the entry/key pair, otherwise false

Definition at line 213 of file khighscore.cpp.

◆ hasTable()

bool KHighscore::hasTable ( ) const
Returns
Whether a highscore table exists. You can use this function to indicate whether KHighscore created a highscore table before and - if not - read your old (non-KHighscore) table instead. This way you can safely read an old table and save it using KHighscore without losing any data

Definition at line 254 of file khighscore.cpp.

◆ highscoreGroup()

const TQString & KHighscore::highscoreGroup ( ) const
Returns
The currently used group. This doesn't contain the prefix ("KHighscore_") but the same as setHighscoreGroup uses. The default is TQString()

Definition at line 241 of file khighscore.cpp.

◆ init()

void KHighscore::init ( const char *  appname)
static
Since
3.2 This method open the system-wide highscore file 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 TDEApplication and doing anything else (TDEApplication checks that the program is not suid/sgid and will exit the program for security reason if it is the case).

Definition at line 95 of file khighscore.cpp.

◆ isLocked()

bool KHighscore::isLocked ( ) const
Returns
true if the highscore file is locked or if a local file is used.
Since
3.2

Definition at line 85 of file khighscore.cpp.

◆ lockForWriting()

bool KHighscore::lockForWriting ( TQWidget *  widget = 0)
Since
3.2 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.

Parameters
widgetused 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.

Definition at line 114 of file khighscore.cpp.

◆ readCurrentConfig()

void KHighscore::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).

Since
3.2

Definition at line 90 of file khighscore.cpp.

◆ readEntry()

TQString KHighscore::readEntry ( int  entry,
const TQString &  key,
const TQString &  pDefault = TQString() 
) const

Reads an entry from the highscore table.

Parameters
entryThe number of the entry / the placing to be read
keyThe key of the entry. E.g. "name" for the name of the player. Nearly the same as the usual keys in TDEConfig - but they are prefixed with the entry number
pDefaultThis will be used as default value if the key+pair entry can't be found.
Returns
The value of this entry+key pair or pDefault if the entry+key pair doesn't exist

Definition at line 199 of file khighscore.cpp.

◆ readList()

TQStringList KHighscore::readList ( const TQString &  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 on 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!
Parameters
keyThe key of the entry. E.g. "name" for the name of the player. Nearly the same as the usual keys in TDEConfig - but they are prefixed with the entry number
lastEntrythe last entry which will be includes into the list. 1 will include a list with maximal 1 entry - 20 a list with maximal 20 entries. If lastEntry is <= 0 then rading is only stopped when when an entry does not exist.

Definition at line 220 of file khighscore.cpp.

◆ readNumEntry()

int KHighscore::readNumEntry ( int  entry,
const TQString &  key,
int  pDefault = -1 
) const

Read a numeric value.

Parameters
entryThe number of the entry / the placing to be read
keyThe key of the entry. E.g. "name" for the name of the player. Nearly the same as the usual keys in TDEConfig - but they are prefixed with the entry number
pDefaultThis will be used as default value if the key+pair entry can't be found.
Returns
The value of this entry+key pair or pDefault if the entry+key pair doesn't exist

Definition at line 206 of file khighscore.cpp.

◆ readPropertyEntry()

TQVariant KHighscore::readPropertyEntry ( int  entry,
const TQString &  key,
const TQVariant &  pDefault 
) const

Read a TQVariant entry.

See TDEConfigBase documentation for allowed TQVariant::Type.

Returns
the value of this entry+key pair or pDefault if the entry+key pair doesn't exist or

Definition at line 192 of file khighscore.cpp.

◆ setHighscoreGroup()

void KHighscore::setHighscoreGroup ( const TQString &  groupname = TQString())

Set the new highscore group.

The group is being prefixed with "KHighscore_" in the table.

Parameters
groupnameThe new groupname. E.g. use "easy" for the easy level of your game. If you use TQString() (the default) the default group is used.

Definition at line 236 of file khighscore.cpp.

◆ sync()

void KHighscore::sync ( )
Deprecated:
This does the same as writeAndUnlock().

Definition at line 257 of file khighscore.cpp.

◆ writeAndUnlock()

void KHighscore::writeAndUnlock ( )

Effectively write and unlock the system-wide highscore file (.

See also
lockForWriting). If using a local highscore file, it will sync the config.
Since
3.2

Definition at line 143 of file khighscore.cpp.

◆ writeEntry() [1/3]

void KHighscore::writeEntry ( int  entry,
const TQString &  key,
const TQString &  value 
)
Parameters
entryThe number of the entry / the placing of the player
keyA key for this entry. E.g. "name" for the name of the player. Nearly the same as the usual keys in TDEConfig - but they are prefixed with the entry number
valueThe value of this entry

Definition at line 184 of file khighscore.cpp.

◆ writeEntry() [2/3]

void KHighscore::writeEntry ( int  entry,
const TQString &  key,
int  value 
)

This is an overloaded member function, provided for convenience.

It differs from the above function only in what argument(s) it accepts.

Definition at line 176 of file khighscore.cpp.

◆ writeEntry() [3/3]

void KHighscore::writeEntry ( int  entry,
const TQString &  key,
const TQVariant &  value 
)

This is an overloaded member function, provided for convenience.

It differs from the above function only in what argument(s) it accepts. See TDEConfigBase documentation for allowed TQVariant::Type.

Definition at line 168 of file khighscore.cpp.

◆ writeList()

void KHighscore::writeList ( const TQString &  key,
const TQStringList &  list 
)

Writes a list of entries 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()

Parameters
keyA key for the entry. E.g. "name" for the name of the player. Nearly the same as the usual keys in TDEConfig - but they are prefixed with the entry number
listThe list of values

Definition at line 229 of file khighscore.cpp.


The documentation for this class was generated from the following files:
  • khighscore.h
  • khighscore.cpp

libtdegames

Skip menu "libtdegames"
  • Main Page
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Class Members
  • Related Pages

libtdegames

Skip menu "libtdegames"
  • libtdegames
Generated for libtdegames by doxygen 1.8.13
This website is maintained by Timothy Pearson.