diff options
Diffstat (limited to 'libkdegames/highscore/kexthighscore.h')
| -rw-r--r-- | libkdegames/highscore/kexthighscore.h | 367 |
1 files changed, 0 insertions, 367 deletions
diff --git a/libkdegames/highscore/kexthighscore.h b/libkdegames/highscore/kexthighscore.h deleted file mode 100644 index 5809a896..00000000 --- a/libkdegames/highscore/kexthighscore.h +++ /dev/null @@ -1,367 +0,0 @@ -/* - This file is part of the KDE games library - Copyright (C) 2001-2004 Nicolas Hadacek ([email protected]) - - 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. -*/ - -#ifndef KEXTHIGHSCORE_H -#define KEXTHIGHSCORE_H - -#include "kexthighscore_item.h" - -#include <kurl.h> -#include <kdemacros.h> - -class TQTabWidget; - - -namespace KExtHighscore -{ - -class Score; -class Item; - -class ManagerPrivate; -extern ManagerPrivate *internal; - -/** - * Get the current game type. - */ -KDE_EXPORT uint gameType(); - -/** - * Set the current game type. - */ -KDE_EXPORT void setGameType(uint gameType); - -/** - * Configure the highscores. - * @return true if the configuration has been modified and saved - */ -KDE_EXPORT bool configure(TQWidget *parent); - -/** - * Show the highscores lists. - */ -KDE_EXPORT void show(TQWidget *parent); - -/** - * Submit a score. See @ref Manager for usage example. - * - * @param widget a widget used as parent for error message box. - */ -KDE_EXPORT void submitScore(const Score &score, TQWidget *widget); - -/** - * @return the last score in the local list of highscores. The worst possible - * score if there are less items than the maximum number. - */ -KDE_EXPORT Score lastScore(); - -/** - * @return the first score in the local list of highscores (the worst possible - * score if there is no entry). - */ -KDE_EXPORT Score firstScore(); - -/** - * This class manages highscores and players entries (several players can - * share the same highscores list if the libkdegame library is built to - * support a common highscores file; NOTE that to correctly implement such - * feature we probably need a locking mechanism in @ref KHighscore). - * - * You need one instance of this class during the application lifetime ; in - * main() just insert - * \code - * KExtHighscore::Manager highscoresManager; - * \endcode - * with the needed arguments. Use the derived class if you need to - * reimplement some of the default methods. - * - * This class has three functions : - * <ul> - * <li> Update the highscores list when new entries are submitted </li> - * <li> Display the highscores list and the players list </li> - * <li> Send query to an optionnal web server to support world-wide - * highscores </li> - * </ul> - * - * The highscores and the players lists contain several items described by - * the @ref Item class. - * - * The highscores list contains by default : - * <ul> - * <li> the player name (automatically set from the config value)</li> - * <li> the score value </li> - * <li> the time and date of the highscore (automatically set) </li> - * </ul> - * You can replace the score item (for e.g. displaying it differently) with - * setScoreItem or add an item with addScoreItem. - * - * The players list contains : - * <ul> - * <li> the player name (as defined by the user in the configuration - * dialog) </li> - * <li> the number of games played </li> - * <li> the mean score </li> - * <li> the best score </li> - * <li> the best score time and date </li> - * <li> the player comment (as defined by the user in the - * configuration dialog) </li> - * </ul> - * You can replace the best score and the mean score items - * by calling setPlayerItem. - * - * To submit a new score at game end, just construct a Score, set the - * score data and then call submitScore(). - * \code - * KExtHighscore::Score score(KExtHighscore::Won); - * score.setScore(myScore); - * KExtHighscore::submitScore(score, widget); - * \endcode - * You only need to set the score value with Score::setScore() - * and the value of the items that you have optionnally added - * with Score::setData() ; player name and date are set automatically. - */ -class KDE_EXPORT Manager -{ - public: - /** - * Constructor - * - * @param nbGameTypes the number of different game types (usually one). - * For example KMines has easy, normal and expert levels. - * @param maxNbEntries the maximum numbers of highscores entries (by game - * types) - */ - Manager(uint nbGameTypes = 1, uint maxNbEntries = 10); - virtual ~Manager(); - - /** - * Set the world-wide highscores. - * By default there is no world-wide highscores. - * - * Note: should be called at construction time. - * - * @param url the web server url - * @param version the game version which is sent to the web server (it can - * be useful for backward compatibility on the server side). - */ - void setWWHighscores(const KURL &url, const TQString &version); - - /** - * Set if the number of lost games should be track for the world-wide - * highscores statistics. By default, there is no tracking. - * False by default. - * - * Note: should be called at construction time. - */ - void setTrackLostGames(bool track); - - /** - * @since 3.3 - * Set if the number of "draw" games should be track for the world-wide - * highscores statistics. By default, there is no tracking. - * False by default. - * - * Note: should be called at construction time. - */ - void setTrackDrawGames(bool track); - - /** - * @since 3.3 - * Set if the statistics tab should be shown in the highscores dialog. - * You only want to show this tab if it makes sense to lose or to win the - * game (for e.g. it makes no sense for a tetris game but it does for a - * minesweeper game). - * False by default. - * - * Note: should be called at construction time. - */ - void setShowStatistics(bool show); - - /** @obsolete */ - // KDE4 remove this - void showStatistics(bool show) KDE_DEPRECATED; - - /** - * @since 3.3 - * Set if draw games statistics should be shown (enable this if - * draws are possible in your game). - * False by default. - */ - void setShowDrawGamesStatistic(bool show); - - enum ScoreTypeBound { ScoreNotBound, ScoreBound }; - /** - * Set the ranges for the score histogram. - * - * Note: should be called at construction time. - */ - void setScoreHistogram(const TQMemArray<uint> &scores, ScoreTypeBound type); - - /** - * Enumerate different conditions under which to show the - * high score dialog. - */ - enum ShowMode { AlwaysShow, ///< Always show the dialog - NeverShow, ///< Never show the dialog - ShowForHigherScore, ///< Show if score has improved - ShowForHighestScore ///< Only for the top spot - }; - /** - * Set how the highscores dialog is shown at game end. - * By default, the mode is ShowForHigherScore. - * - * Note: should be called at construction time. - */ - void setShowMode(ShowMode mode); - - /** - * Score type (@see setScoreType). - * @p Normal default score (unsigned integer without upper bound) - * @p MinuteTime score by time bound at 3599 seconds (for e.g. kmines) - */ - enum ScoreType { Normal, MinuteTime }; - /** - * Set score type. Helper method to quickly set the type of score. - * By default the type is Normal. - * - * Note: should be called at construction time. - */ - void setScoreType(ScoreType type); - - /** - * Some predefined item types. - * @p ScoreDefault default item for the score in the highscores list. - * @p MeanScoreDefault default item for the mean score (only show one decimal and - * 0 is shown as "--". - * @p BestScoreDefault default item for the best score (0 is shown as "--"). - * @p ElapsedTime optionnal item for elapsed time (maximum value is 3599 seconds). - */ - enum ItemType { ScoreDefault, MeanScoreDefault, BestScoreDefault, - ElapsedTime }; - /** - * Create a predefined item. - */ - static Item *createItem(ItemType type); - - /** - * Replace the default score item in the highscores list by the given one. - * @p worstScore is the worst possible score. By default it is 0. - * - * Note : This method should be called at construction time. - */ - void setScoreItem(uint worstScore, Item *item); - - /** - * Add an item in the highscores list (it will add a column to this list). - * - * Note : This method should be called at construction time. - */ - void addScoreItem(const TQString &name, Item *item); - - enum PlayerItemType { MeanScore, BestScore }; - /** - * Replace an item in the players list. - * - * Note : This method should be called at construction time. - */ - void setPlayerItem(PlayerItemType type, Item *item); - - /** - * @return true if the first score is strictly worse than the second one. - * By default return <pre>s1.score()<s2.score()</pre>. You can reimplement - * this method if additional items added to @ref Score can further - * differentiate the scores (for e.g. the time spent). - * - * Note that you do not need to use directly this method, simply write - * <pre>s1<s2</pre> since the operator calls this method. - */ - virtual bool isStrictlyLess(const Score &s1, const Score &s2) const; - - /** - * Possible type of label (@see gameTypeLabel). - * @p Standard label used in config file. - * @p I18N label used to display the game type. - * @p WW label used when contacting the world-wide highscores server. - * @p Icon label used to load the icon corresponding to the game type. - */ - enum LabelType { Standard, I18N, WW, Icon }; - - /** - * @return the label corresponding to the game type. The default - * implementation works only for one game type : you need to reimplement - * this method if the number of game types is more than one. - */ - virtual TQString gameTypeLabel(uint gameType, LabelType type) const; - - protected: - /** - * This method is called once for each player (ie for each user). You - * can reimplement it to convert old style highscores to the new mechanism - * (@see submitLegacyScore). By default this method does nothing. - * - * @param gameType the game type - */ - virtual void convertLegacy(uint gameType) { Q_UNUSED(gameType); } - - /** - * This method should be called from @ref convertLegacy. It is used - * to submit an old highscore (it will not be send over the network). - * For each score do something like: - * \code - * Score score(Won); - * score.setScore(oldScore); - * score.setData("name", name); - * submitLegacyScore(score); - * \endcode - * Note that here you can set the player "name" and the highscore "date" - * if they are known. - */ - void submitLegacyScore(const Score &score) const; - - /** - * This method is called before submitting a score to the world-wide - * highscores server. You can reimplement this method to add an entry - * with @ref addToQueryURL. By default this method does nothing. - * - * @param url the URL to query - * @param score the score to be submitted. - */ - virtual void additionalQueryItems(KURL &url, const Score &score) const - { Q_UNUSED(url); Q_UNUSED(score); } - - /** - * Add an entry to the url to be submitted (@see additionalQueryItems). - * - * @param url the URL to query - * @param item the item name - * @param content the item content - */ - static void addToQueryURL(KURL &url, const TQString &item, - const TQString &content); - - friend class ManagerPrivate; - - private: - Manager(const Manager &); - Manager &operator =(const Manager &); -}; - -} // namespace - -#endif |