summaryrefslogtreecommitdiffstats
path: root/libkdegames/highscore/khighscore.h
diff options
context:
space:
mode:
Diffstat (limited to 'libkdegames/highscore/khighscore.h')
-rw-r--r--libkdegames/highscore/khighscore.h312
1 files changed, 0 insertions, 312 deletions
diff --git a/libkdegames/highscore/khighscore.h b/libkdegames/highscore/khighscore.h
deleted file mode 100644
index b7b6fb5e..00000000
--- a/libkdegames/highscore/khighscore.h
+++ /dev/null
@@ -1,312 +0,0 @@
-/*
- This file is part of the KDE games library
- Copyright (C) 2001 Andreas Beckermann (b_mann@gmx.de)
- Copyright (C) 2003 Nicolas Hadacek <hadacek@kde.org>
-
- This library 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 library 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 library; see the file COPYING.LIB. If not, write to
- the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
- Boston, MA 02110-1301, USA.
-*/
-/*
- $Id$
-*/
-#ifndef __KHIGHSCORE_H__
-#define __KHIGHSCORE_H__
-
-#include <tqstring.h>
-#include <tqobject.h>
-#include <kdemacros.h>
-class KConfig;
-class KFileLock;
-class KRawConfig;
-class KHighscorePrivate;
-
-/**
- * @short 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 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):
- * \code
- * highscore->writeEntry(1, "name", myPlayer->name());
- * \endcode
- * 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 KConfig
- * but are prefixed with "KHighscore_". The default group is just "KHighscore".
- * You might use this e.g. to create different highscore tables like
- * \code
- * 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);
- * \endcode
- * 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:
- * \code
- * TQString group = TQString("%1_%2").tqarg(player).tqarg(level);
- * table->setGroup(group);
- * writeHighscore(table, player, level);
- * \endcode
- *
- * 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:
- * \code
- * TQString firstName = highscore->readEntry(0, "name");
- * \endcode
- * Easy, what?
- * @author Andreas Beckermann <b_mann@gmx.de>
- **/
-class KDE_EXPORT KHighscore : public TQObject
-{
- Q_OBJECT
- TQ_OBJECT
-public:
- /** @obsolete
- * Constructor. The highscore file is forced to be local to support
- * games using the old behaviour.
- */
- KHighscore(TQObject* parent = 0);
-
- /**
- * Constructor.
- *
- * @param forceLocal if 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.
- * @param parent parent widget for this widget
- * @since 3.2
- */
- KHighscore(bool forceLocal, TQObject *parent);
-
- /**
- * 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
- */
- void readCurrentConfig();
-
- /** @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
- * 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).
- */
- static void init(const char *appname);
-
- /** @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.
- * @param widget used as the parent of the message box.
- *
- * @return false on error or if the config file is locked by another
- * process. In such case, the config stays read-only.
- */
- bool lockForWriting(TQWidget *widget = 0);
-
- /**
- * Effectively write and unlock the system-wide highscore file
- * (@see lockForWriting).
- * If using a local highscore file, it will sync the config.
- * @since 3.2
- */
- void writeAndUnlock();
-
- /**
- * @return true if the highscore file is locked or if a local
- * file is used.
- * @since 3.2
- */
- bool isLocked() const;
-
- /**
- * Destructor.
- * If necessary, write and unlock the highscore file.
- */
- ~KHighscore();
-
- /**
- * @param entry The number of the entry / the placing of the player
- * @param key A key for this entry. E.g. "name" for the name of the
- * player. Nearly the same as the usual keys in KConfig - but they
- * are prefixed with the entry number
- * @param value The value of this entry
- **/
- void writeEntry(int entry, const TQString& key, const TQString& value);
-
- /**
- * This is an overloaded member function, provided for convenience.
- * It differs from the above function only in what argument(s) it accepts.
- **/
- void 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.
- * See KConfigBase documentation for allowed TQVariant::Type.
- **/
- void writeEntry(int entry, const TQString& key, const TQVariant &value);
-
- /**
- * Reads an entry from the highscore table.
- * @param entry The number of the entry / the placing to be read
- * @param key The key of the entry. E.g. "name" for the name of the
- * player. Nearly the same as the usual keys in KConfig - but they
- * are prefixed with the entry number
- * @param pDefault This will be used as default value if the key+pair
- * entry can't be found.
- * @return The value of this entry+key pair or pDefault if the entry+key
- * pair doesn't exist
- **/
- TQString readEntry(int entry, const TQString& key, const TQString& pDefault = TQString()) const;
-
- /**
- * Read a numeric value.
- * @param entry The number of the entry / the placing to be read
- * @param key The key of the entry. E.g. "name" for the name of the
- * player. Nearly the same as the usual keys in KConfig - but they
- * are prefixed with the entry number
- * @param pDefault This will be used as default value if the key+pair
- * entry can't be found.
- * @return The value of this entry+key pair or pDefault if the entry+key
- * pair doesn't exist
- **/
- int readNumEntry(int entry, const TQString& key, int pDefault = -1) const;
-
- /**
- * Read a TQVariant entry.
- * See KConfigBase documentation for allowed TQVariant::Type.
- *
- * @return the value of this entry+key pair or pDefault if the entry+key
- * pair doesn't exist or
- */
- TQVariant readPropertyEntry(int entry, const TQString &key, const TQVariant &pDefault) const;
-
- /**
- * @return True if the highscore table conatins the entry/key pair,
- * otherwise false
- **/
- bool hasEntry(int entry, const TQString& key) 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.
- * @return 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!
- * @param key The key of the entry. E.g. "name" for the name of the
- * player. Nearly the same as the usual keys in KConfig - but they
- * are prefixed with the entry number
- * @param lastEntry the 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.
- **/
- TQStringList readList(const TQString& key, int lastEntry = 20) const;
-
- /**
- * 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()
- * @param key A key for the entry. E.g. "name" for the name of the
- * player. Nearly the same as the usual keys in KConfig - but they
- * are prefixed with the entry number
- * @param list The list of values
- **/
- void writeList(const TQString& key, const TQStringList& list);
-
- /**
- * @return 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
- **/
- bool hasTable() const;
-
- /** @obsolete
- * This does the same as writeAndUnlock().
- */
- void sync();
-
- /**
- * Set the new highscore group. The group is being prefixed with
- * "KHighscore_" in the table.
- * @param groupname The new groupname. E.g. use "easy" for the easy
- * level of your game. If you use TQString() (the default) the
- * default group is used.
- **/
- void setHighscoreGroup(const TQString& groupname = TQString());
-
- /**
- * @return The currently used group. This doesn't contain the prefix
- * ("KHighscore_") but the same as setHighscoreGroup uses. The
- * default is TQString()
- **/
- const TQString& highscoreGroup() const;
-
-protected:
- /**
- * @return A groupname to be used in KConfig. Used internally to
- * prefix the value from highscoreGroup() with "KHighscore_"
- **/
- TQString group() const;
-
- /**
- * @return A pointer to the KConfig object to be used. This is
- * either kapp->config() (default) or a KSimpleConfig object for
- * a system-wide highscore file.
- **/
- KConfig* config() const;
-
- void init(bool forceLocal);
-
-private:
- KHighscorePrivate* d;
-
- static KFileLock *_lock; // lock on system-wide highscore file
- static KRawConfig *_config; // config for system-wide highscore file
-};
-
-#endif