KExtHighscore::Manager Class Reference

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 KHighscore). More...

#include <kexthighscore.h>

List of all members.

Public Types
enum	ScoreTypeBound { ScoreNotBound, ScoreBound }
enum	ShowMode { AlwaysShow, NeverShow, ShowForHigherScore, ShowForHighestScore }
	Enumerate different conditions under which to show the high score dialog. More...
enum	ScoreType { Normal, MinuteTime }
	Score type (. More...
enum	ItemType { ScoreDefault, MeanScoreDefault, BestScoreDefault, ElapsedTime }
	Some predefined item types. More...
enum	PlayerItemType { MeanScore, BestScore }
enum	LabelType { Standard, I18N, WW, Icon }
	Possible type of label (. More...
Public Member Functions
	Manager (uint nbGameTypes=1, uint maxNbEntries=10)
	Constructor.
virtual	~Manager ()
void	setWWHighscores (const KURL &url, const QString &version)
	Set the world-wide highscores.
void	setTrackLostGames (bool track)
	Set if the number of lost games should be track for the world-wide highscores statistics.
void	setTrackDrawGames (bool track)
void	setShowStatistics (bool show)
void	showStatistics (bool show) KDE_DEPRECATED
void	setShowDrawGamesStatistic (bool show)
void	setScoreHistogram (const QMemArray< uint > &scores, ScoreTypeBound type)
	Set the ranges for the score histogram.
void	setShowMode (ShowMode mode)
	Set how the highscores dialog is shown at game end.
void	setScoreType (ScoreType type)
	Set score type.
void	setScoreItem (uint worstScore, Item *item)
	Replace the default score item in the highscores list by the given one.
void	addScoreItem (const QString &name, Item *item)
	Add an item in the highscores list (it will add a column to this list).
void	setPlayerItem (PlayerItemType type, Item *item)
	Replace an item in the players list.
virtual bool	isStrictlyLess (const Score &s1, const Score &s2) const
virtual QString	gameTypeLabel (uint gameType, LabelType type) const
Static Public Member Functions
static Item *	createItem (ItemType type)
	Create a predefined item.
Protected Member Functions
virtual void	convertLegacy (uint gameType)
	This method is called once for each player (ie for each user).
void	submitLegacyScore (const Score &score) const
	This method should be called from convertLegacy.
virtual void	additionalQueryItems (KURL &url, const Score &score) const
	This method is called before submitting a score to the world-wide highscores server.
Static Protected Member Functions
static void	addToQueryURL (KURL &url, const QString &item, const QString &content)
	Add an entry to the url to be submitted (.
Friends
class	ManagerPrivate

---

Detailed Description

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

You need one instance of this class during the application lifetime ; in main() just insert

   KExtHighscore::Manager highscoresManager;

with the needed arguments. Use the derived class if you need to reimplement some of the default methods.

This class has three functions :

• Update the highscores list when new entries are submitted
• Display the highscores list and the players list
• Send query to an optionnal web server to support world-wide highscores

The highscores and the players lists contain several items described by the Item class.

The highscores list contains by default :

• the player name (automatically set from the config value)
• the score value
• the time and date of the highscore (automatically set)

You can replace the score item (for e.g. displaying it differently) with setScoreItem or add an item with addScoreItem.

The players list contains :

• the player name (as defined by the user in the configuration dialog)
• the number of games played
• the mean score
• the best score
• the best score time and date
• the player comment (as defined by the user in the configuration dialog)

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().

     KExtHighscore::Score score(KExtHighscore::Won);
     score.setScore(myScore);
     KExtHighscore::submitScore(score, widget);

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.

Definition at line 139 of file kexthighscore.h.

---

Member Enumeration Documentation

enum KExtHighscore::Manager::ItemType

Some predefined item types. ScoreDefault default item for the score in the highscores list. MeanScoreDefault default item for the mean score (only show one decimal and 0 is shown as "--". BestScoreDefault default item for the best score (0 is shown as "--"). ElapsedTime optionnal item for elapsed time (maximum value is 3599 seconds). Enumerator: ScoreDefault  MeanScoreDefault  BestScoreDefault  ElapsedTime  Definition at line 255 of file kexthighscore.h.

enum KExtHighscore::Manager::LabelType

Possible type of label (. See also: gameTypeLabel). Standard label used in config file. I18N label used to display the game type. WW label used when contacting the world-wide highscores server. Icon label used to load the icon corresponding to the game type. Enumerator: Standard  I18N  WW  Icon  Definition at line 303 of file kexthighscore.h.

enum KExtHighscore::Manager::PlayerItemType

Enumerator: MeanScore  BestScore  Definition at line 277 of file kexthighscore.h.

enum KExtHighscore::Manager::ScoreType

Score type (. See also: setScoreType). Normal default score (unsigned integer without upper bound) MinuteTime score by time bound at 3599 seconds (for e.g. kmines) Enumerator: Normal  MinuteTime  Definition at line 238 of file kexthighscore.h.

enum KExtHighscore::Manager::ScoreTypeBound

Enumerator: ScoreNotBound  ScoreBound  Definition at line 208 of file kexthighscore.h.

enum KExtHighscore::Manager::ShowMode

Enumerate different conditions under which to show the high score dialog. Enumerator: AlwaysShow  Always show the dialog. NeverShow  Never show the dialog. ShowForHigherScore  Show if score has improved. ShowForHighestScore  Only for the top spot. Definition at line 220 of file kexthighscore.h.

---

Constructor & Destructor Documentation

KExtHighscore::Manager::Manager (  uint  nbGameTypes = 1, uint  maxNbEntries = 10 )

Constructor. Parameters: nbGameTypes  the number of different game types (usually one). For example KMines has easy, normal and expert levels. maxNbEntries  the maximum numbers of highscores entries (by game types) Definition at line 107 of file kexthighscore.cpp. References KExtHighscore::ManagerPrivate::init(), KExtHighscore::internal, and ManagerPrivate. Here is the call graph for this function:

KExtHighscore::Manager::~Manager (   )  [virtual]

Definition at line 117 of file kexthighscore.cpp. References KExtHighscore::internal.

---

Member Function Documentation

virtual void KExtHighscore::Manager::additionalQueryItems (  KURL &  url, const Score &  score )  const [inline, protected, virtual]

This method is called before submitting a score to the world-wide highscores server. You can reimplement this method to add an entry with addToQueryURL. By default this method does nothing. Parameters: url  the URL to query score  the score to be submitted. Definition at line 345 of file kexthighscore.h.

void KExtHighscore::Manager::addScoreItem (  const QString &  name, 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. Definition at line 241 of file kexthighscore.cpp. References KExtHighscore::ItemArray::addItem(), KExtHighscore::internal, and KExtHighscore::ManagerPrivate::scoreInfos(). Here is the call graph for this function:

void KExtHighscore::Manager::addToQueryURL (  KURL &  url, const QString &  item, const QString &  content )  [static, protected]

Add an entry to the url to be submitted (. See also: additionalQueryItems). Parameters: url  the URL to query item  the item name content  the item content Definition at line 278 of file kexthighscore.cpp. Referenced by KExtHighscore::ManagerPrivate::modifySettings(), and KExtHighscore::ManagerPrivate::queryURL().

virtual void KExtHighscore::Manager::convertLegacy (  uint  gameType  )  [inline, protected, virtual]

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 also: submitLegacyScore). By default this method does nothing. Parameters: gameType  the game type Definition at line 320 of file kexthighscore.h. Referenced by KExtHighscore::ManagerPrivate::setGameType().

Item * KExtHighscore::Manager::createItem (  ItemType  type  )  [static]

Create a predefined item. Definition at line 206 of file kexthighscore.cpp. References BestScoreDefault, KExtHighscore::Item::DefaultNotDefined, ElapsedTime, MeanScoreDefault, KExtHighscore::Item::MinuteTime, KExtHighscore::Item::OneDecimal, ScoreDefault, KExtHighscore::Item::setPrettyFormat(), KExtHighscore::Item::setPrettySpecial(), and KExtHighscore::Item::ZeroNotDefined. Referenced by KExtHighscore::PlayerInfos::PlayerInfos(), KExtHighscore::ScoreInfos::ScoreInfos(), and setScoreType(). Here is the call graph for this function:

QString KExtHighscore::Manager::gameTypeLabel (  uint  gameType, LabelType  type )  const [virtual]

Returns: 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. Definition at line 264 of file kexthighscore.cpp. References I18N, Icon, Standard, and WW. Referenced by KExtHighscore::ManagerPrivate::exportHighscores(), KExtHighscore::HighscoresDialog::HighscoresDialog(), and KExtHighscore::ManagerPrivate::queryURL().

bool KExtHighscore::Manager::isStrictlyLess (  const Score &  s1, const Score &  s2 )  const [virtual]

Returns: true if the first score is strictly worse than the second one. By default return s1.score()<s2.score() . You can reimplement this method if additional items added to 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 s1<s2 since the operator calls this method. Definition at line 201 of file kexthighscore.cpp. References KExtHighscore::Score::score(). Referenced by KExtHighscore::Score::operator<(). Here is the call graph for this function:

void KExtHighscore::Manager::setPlayerItem (  PlayerItemType  type, Item *  item )

Replace an item in the players list. Note : This method should be called at construction time. Definition at line 246 of file kexthighscore.cpp. References BestScore, KExtHighscore::Item::defaultValue(), KExtHighscore::internal, KExtHighscore::ItemContainer::item(), KExtHighscore::ItemArray::item(), MeanScore, KExtHighscore::ManagerPrivate::playerInfos(), KExtHighscore::ManagerPrivate::scoreInfos(), KExtHighscore::Item::setDefaultValue(), and KExtHighscore::ItemArray::setItem(). Referenced by setScoreType(). Here is the call graph for this function:

void KExtHighscore::Manager::setScoreHistogram (  const QMemArray< uint > &  scores, ScoreTypeBound  type )

Set the ranges for the score histogram. Note: should be called at construction time. Definition at line 160 of file kexthighscore.cpp. References KExtHighscore::PlayerInfos::createHistoItems(), KExtHighscore::internal, KExtHighscore::ManagerPrivate::playerInfos(), and ScoreBound. Here is the call graph for this function:

void KExtHighscore::Manager::setScoreItem (  uint  worstScore, Item *  item )

Replace the default score item in the highscores list by the given one. worstScore is the worst possible score. By default it is 0. Note : This method should be called at construction time. Definition at line 231 of file kexthighscore.cpp. References KExtHighscore::internal, KExtHighscore::ItemContainer::item(), KExtHighscore::ItemArray::item(), KExtHighscore::ManagerPrivate::playerInfos(), KExtHighscore::ManagerPrivate::scoreInfos(), KExtHighscore::Item::setDefaultValue(), and KExtHighscore::ItemArray::setItem(). Referenced by setScoreType(). Here is the call graph for this function:

void KExtHighscore::Manager::setScoreType (  ScoreType  type  )

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. Definition at line 174 of file kexthighscore.cpp. References BestScore, BestScoreDefault, createItem(), MeanScore, MeanScoreDefault, KExtHighscore::Item::MinuteTime, MinuteTime, Normal, ScoreDefault, setPlayerItem(), KExtHighscore::Item::setPrettyFormat(), and setScoreItem(). Here is the call graph for this function:

void KExtHighscore::Manager::setShowDrawGamesStatistic (  bool  show  )

Since: 3.3 Set if draw games statistics should be shown (enable this if draws are possible in your game). False by default. Definition at line 143 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::showDrawGames.

void KExtHighscore::Manager::setShowMode (  ShowMode  mode  )

Set how the highscores dialog is shown at game end. By default, the mode is ShowForHigherScore. Note: should be called at construction time. Definition at line 169 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::showMode.

void KExtHighscore::Manager::setShowStatistics (  bool  show  )

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. Definition at line 133 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::showStatistics.

void KExtHighscore::Manager::setTrackDrawGames (  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. Definition at line 128 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::trackDrawGames.

void KExtHighscore::Manager::setTrackLostGames (  bool  track  )

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. Definition at line 123 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::trackLostGames.

void KExtHighscore::Manager::setWWHighscores (  const KURL &  url, const QString &  version )

Set the world-wide highscores. By default there is no world-wide highscores. Note: should be called at construction time. Parameters: url  the web server url version  the game version which is sent to the web server (it can be useful for backward compatibility on the server side). Definition at line 148 of file kexthighscore.cpp. References KExtHighscore::internal, KExtHighscore::ManagerPrivate::serverURL, and KExtHighscore::ManagerPrivate::version.

void KExtHighscore::Manager::showStatistics (  bool  show  )

Definition at line 138 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::showStatistics.

void KExtHighscore::Manager::submitLegacyScore (  const Score &  score  )  const [protected]

This method should be called from convertLegacy. It is used to submit an old highscore (it will not be send over the network). For each score do something like: Score score(Won); score.setScore(oldScore); score.setData("name", name); submitLegacyScore(score); Note that here you can set the player "name" and the highscore "date" if they are known. Definition at line 196 of file kexthighscore.cpp. References KExtHighscore::internal, and KExtHighscore::ManagerPrivate::submitLocal(). Here is the call graph for this function:

---

Friends And Related Function Documentation

friend class ManagerPrivate [friend]

Definition at line 358 of file kexthighscore.h. Referenced by Manager().

---

The documentation for this class was generated from the following files:

• kexthighscore.h
• kexthighscore.cpp

---