libkdegames/highscore

KScoreDialog Class Reference

#include <KScoreDialog>

Inheritance diagram for KScoreDialog:

Detailed Description

A simple high score implementation.

This class can be used both for displaying the current high scores and also for adding new highscores. It is the recommended way of implementing a simple highscore table.

To display the current highscores it is simply a case of creating a KScoreDialog object and calling exec(). This example code will display the Name and Score (the score is always added automatically unless hidden hideField since it is used for sorting) of the top 10 players:

 KScoreDialog ksdialog(this);
 ksdialog.exec();

To add a new highscore, e.g. at the end of a game you simply create an object with the Fields you want to write (i.e. KScoreDialog::Name | KScoreDialog::Score), call addScore and then (optionally) display the dialog. This code will allow you to add a highscore with a Name and Score field. If it's the first time a player has a score on the table, they will be prompted for their name but subsequent times they will have their name filled in automatically.

 KScoreDialog ksdialog(this);
 ksdialog.addScore(playersScore);
 ksdialog.exec();

Or if you want to fill the name in from the code you can pass a default name by doing

 KScoreDialog::FieldInfo scoreInfo;
 scoreInfo[KScoreDialog::Name] = "Matt";
 scoreInfo[KScoreDialog::Score].setNum(playersScore);
 ksdialog.addScore(scoreInfo);

If you want to add an extra field (e.g. the number of moves taken) then do

 KScoreDialog::FieldInfo scoreInfo;
 scoreInfo[KScoreDialog::Name] = "Matt";
 scoreInfo[KScoreDialog::Score].setNum(playersScore);
 
 ksdialog.addField(KScoreDialog::Custom1, "Num of Moves", "moves");
 scoreInfo[KScoreDialog::Custom1].setNum(42);
 
 ksdialog.addScore(scoreInfo);

You can define up to 5 Custom fields.

Author:: Matt Williams <matt@milliams.com>

Definition at line 95 of file kscoredialog.h.


Public Types
enum	AddScoreFlag { AskName = 0x1, LessIsMore = 0x2 }
typedef QMap< int, QString >	FieldInfo
enum	Fields { Name = 1 << 0, Level = 1 << 1, Date = 1 << 2, Time = 1 << 3, Score = 1 << 4, Custom1 = 1 << 10, Custom2 = 1 << 11, Custom3 = 1 << 12, Custom4 = 1 << 13, Custom5 = 1 << 14, Max = 1 << 30 }
Public Member Functions
void	addField (int field, const QString &header, const QString &key)
void	addLocalizedConfigGroupName (const QPair< QByteArray, QString > &group)
void	addLocalizedConfigGroupNames (const QMap< QByteArray, QString > &groups)
int	addScore (int newScore, const AddScoreFlags &flags=0)
int	addScore (const FieldInfo &newInfo=FieldInfo(), const AddScoreFlags &flags=0)
virtual void	exec ()
void	hideField (int field)
int	highScore ()
	KScoreDialog (int fields=Name, QWidget *parent=0)
void	setComment (const QString &comment)
void	setConfigGroup (const QPair< QByteArray, QString > &group)
void KDE_DEPRECATED	setConfigGroup (const QString &group=QString())
virtual void	show ()
	~KScoreDialog ()

Member Typedef Documentation

typedef QMap<int, QString> KScoreDialog::FieldInfo

Definition at line 125 of file kscoredialog.h.

Member Enumeration Documentation

enum KScoreDialog::AddScoreFlag

Flags for setting preferences for adding scores.

Enumerator:

AskName	Promt the player for their name.
LessIsMore	A lower numerical score means higher placing on the table.

Definition at line 118 of file kscoredialog.h.

enum KScoreDialog::Fields

Highscore fields.

Enumerator:

Name
Level
Date
Time
Score
Custom1	Field for custom information.
Custom2
Custom3
Custom4
Custom5
Max	Only for setting a maximum.

Definition at line 101 of file kscoredialog.h.

Constructor & Destructor Documentation

KScoreDialog::KScoreDialog	(	int	fields = `Name`,
		QWidget *	parent = `0`
	)			`[explicit]`

Parameters:

fields

Bitwise OR of the Fields that should be listed (Score is always present)

Parameters:

parent

passed to parent QWidget constructor.

Definition at line 97 of file kscoredialog.cpp.

KScoreDialog::~KScoreDialog ( )

Definition at line 141 of file kscoredialog.cpp.

Member Function Documentation

void KScoreDialog::addField	(	int	field,
		const QString &	header,
		const QString &	key
	)

Define an extra FieldInfo entry.

Parameters:

	field	id of this field Fields e.g. KScoreDialog::Custom1
	header	text shown in the header in the dialog for this field. e.g. "Number of Moves"
	key	unique key used to store this field. e.g. "moves"

Definition at line 205 of file kscoredialog.cpp.

void KScoreDialog::addLocalizedConfigGroupName ( const QPair< QByteArray, QString > & group )

You must add the translations of all group names to the dialog.

This is best done by passing the name through ki18n(). The group set through setConfigGroup(const KLocalizedString& group) will be added automatically

Parameters:

group

the translated group name

Definition at line 161 of file kscoredialog.cpp.

void KScoreDialog::addLocalizedConfigGroupNames ( const QMap< QByteArray, QString > & groups )

You must add the translations of all group names to the dialog.

This is best done by passing the name through ki18n(). The group set through setConfigGroup(const KLocalizedString& group) will be added automatically.

This function can be used directly with KGameDifficulty::localizedLevelStrings().

Parameters:

group

the list of translated group names

Definition at line 179 of file kscoredialog.cpp.

int KScoreDialog::addScore	(	int	newScore,
		const AddScoreFlags &	flags = `0`
	)

Convenience function for ease of use.

Parameters:

	newScore	the score of the player.
	flags	set whether the user should be prompted for their name and how the scores should be sorted

Returns:: The highscore position if the score was good enough to make it into the list (1 being topscore) or 0 otherwise.

Definition at line 555 of file kscoredialog.cpp.

int KScoreDialog::addScore	(	const FieldInfo &	newInfo = `FieldInfo()`,
		const AddScoreFlags &	flags = `0`
	)

Adds a new score to the list.

Parameters:

	newInfo	info about the score.
	flags	set whether the user should be prompted for their name and how the scores should be sorted

Returns:: The highscore position if the score was good enough to make it into the list (1 being topscore) or 0 otherwise.

Definition at line 480 of file kscoredialog.cpp.

void KScoreDialog::exec ( ) [virtual]

Display the dialog as modal.

Definition at line 568 of file kscoredialog.cpp.

void KScoreDialog::hideField ( int field )

Hide a field so that it is not shown on the table (but is still stored in the configuration file).

Parameters:

field

id of this field Fields e.g. KScoreDialog::Score

Definition at line 212 of file kscoredialog.cpp.

int KScoreDialog::highScore ( )

Returns:: the current best score in the group

Definition at line 600 of file kscoredialog.cpp.

void KScoreDialog::setComment ( const QString & comment )

Parameters:

comment

to add when showing high-scores.

The comment is only used once.

Definition at line 200 of file kscoredialog.cpp.

void KScoreDialog::setConfigGroup ( const QPair< QByteArray, QString > & group )

The group name must be passed though ki18n() in order for the group name to be translated.

i.e.

 ksdialog.setConfigGroup(ki18n("Easy"));

If you set a group, it will be prefixed in the config file by 'KHighscore_' otherwise the group will simply be 'KHighscore'.

Parameters:

group

to use for reading/writing highscores from/to.

Definition at line 154 of file kscoredialog.cpp.

void KScoreDialog::setConfigGroup ( const QString & group = QString() )

The group name must be passed though I18N_NOOP() in order for the group name to be translated.

i.e.

 ksdialog.setConfigGroup(I18N_NOOP("Easy"));

If you set a group, it will be prefixed in the config file by 'KHighscore_' otherwise the group will simply be 'KHighscore'.

Parameters:

group

to use for reading/writing highscores from/to.

Deprecated:: since 4.1

Definition at line 148 of file kscoredialog.cpp.

void KScoreDialog::show ( ) [virtual]

Display the dialog as non-modal.

Definition at line 562 of file kscoredialog.cpp.

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

libkdegames/highscore

KScoreDialog Class Reference

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

libkdegames/highscore

API Reference