libkdegames/highscore

KExtHighscore::Manager

KExtHighscore::Manager Class Reference

#include <kexthighscore.h>

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 optional 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 optionally added with Score::setData() player name and date are set automatically.

Definition at line 141 of file kexthighscore.h.


Public Types
enum	ScoreTypeBound { ScoreNotBound, ScoreBound }
enum	ShowMode { AlwaysShow, NeverShow, ShowForHigherScore, ShowForHighestScore }
enum	ScoreType { Normal, MinuteTime }
enum	ItemType { ScoreDefault, MeanScoreDefault, BestScoreDefault, ElapsedTime }
enum	PlayerItemType { MeanScore, BestScore }
enum	LabelType { Standard, I18N, WW, Icon }
Public Member Functions
	Manager (uint nbGameTypes=1, uint maxNbEntries=10)
virtual	~Manager ()
void	setWWHighscores (const KUrl &url, const QString &version)
void	setTrackLostGames (bool track)
void	setTrackDrawGames (bool track)
void	setShowStatistics (bool show)
void	setShowDrawGamesStatistic (bool show)
void	setScoreHistogram (const QVector< uint > &scores, ScoreTypeBound type)
void	setShowMode (ShowMode mode)
void	setScoreType (ScoreType type)
void	setScoreItem (uint worstScore, Item *item)
void	addScoreItem (const QString &name, Item *item)
void	setPlayerItem (PlayerItemType type, Item *item)
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)
Protected Member Functions
virtual void	convertLegacy (uint gameType)
void	submitLegacyScore (const Score &score) const
virtual void	additionalQueryItems (KUrl &url, const Score &score) const
Static Protected Member Functions
static void	addToQueryURL (KUrl &url, const QString &item, const QString &content)
Friends
class	ManagerPrivate

Member Enumeration Documentation

enum KExtHighscore::Manager::ScoreTypeBound

Enumerator:

ScoreNotBound
ScoreBound

Definition at line 203 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 215 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 233 of file kexthighscore.h.

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 optional item for elapsed time (maximum value is 3599 seconds).

Enumerator:

ScoreDefault
MeanScoreDefault
BestScoreDefault
ElapsedTime

Definition at line 250 of file kexthighscore.h.

enum KExtHighscore::Manager::PlayerItemType

Enumerator:

MeanScore
BestScore

Definition at line 272 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 298 of file kexthighscore.h.

Constructor & Destructor Documentation

KExtHighscore::Manager::Manager	(	uint	nbGameTypes = `1`,
		uint	maxNbEntries = `10`
	)			`[explicit]`

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 109 of file kexthighscore.cpp.

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

Definition at line 119 of file kexthighscore.cpp.

Member Function Documentation

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 145 of file kexthighscore.cpp.

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 125 of file kexthighscore.cpp.

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

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 130 of file kexthighscore.cpp.

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

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 135 of file kexthighscore.cpp.

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

Set if draw games statistics should be shown (enable this if draws are possible in your game).

False by default.

Definition at line 140 of file kexthighscore.cpp.

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

Set the ranges for the score histogram.

Note: should be called at construction time.

Definition at line 157 of file kexthighscore.cpp.

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 166 of file kexthighscore.cpp.

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 171 of file kexthighscore.cpp.

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

Create a predefined item.

Definition at line 203 of file kexthighscore.cpp.

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 228 of file kexthighscore.cpp.

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 238 of file kexthighscore.cpp.

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 243 of file kexthighscore.cpp.

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 198 of file kexthighscore.cpp.

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 261 of file kexthighscore.cpp.

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 315 of file kexthighscore.h.

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 sent 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 193 of file kexthighscore.cpp.

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 340 of file kexthighscore.h.

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 275 of file kexthighscore.cpp.

Friends And Related Function Documentation

friend class ManagerPrivate [friend]

Definition at line 353 of file kexthighscore.h.

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

libkdegames/highscore

KExtHighscore::Manager Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

libkdegames/highscore

API Reference