KGameHighScoreDialog Class

A simple high score implementation. More...

Header: #include <KGameHighScoreDialog>
Inherits: QDialog

Public Types

enum AddScoreFlag { AskName, LessIsMore }
flags AddScoreFlags
FieldInfo
enum Fields { Name, Level, Date, Time, Score, …, Max }

Public Functions

KGameHighScoreDialog(int fields = Name, QWidget *parent = nullptr)
void addField(int field, const QString &header, const QString &key)
void addLocalizedConfigGroupName(const std::pair<QByteArray, QString> &group)
void addLocalizedConfigGroupNames(const QMap<QByteArray, QString> &groups)
int addScore(const KGameHighScoreDialog::FieldInfo &newInfo = FieldInfo(), KGameHighScoreDialog::AddScoreFlags flags = {})
int addScore(int newScore, KGameHighScoreDialog::AddScoreFlags flags = {})
void hideField(int field)
int highScore()
void initFromDifficulty(const KGameDifficulty *difficulty, bool setConfigGroup = true)
void setComment(const QString &comment)
void setConfigGroup(const std::pair<QByteArray, QString> &group)
(since KDE 4.2) void setConfigGroupWeights(const QMap<int, QByteArray> &weights)
(since KDE 4.6) void setHiddenConfigGroups(const QList<QByteArray> &hiddenGroups)
virtual void show()

Reimplemented Public Functions

virtual int exec() override

Private Slots

void slotForgetScore()
void slotGotName()
void slotGotReturn()

Detailed Description

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 KGameHighScoreDialog 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:

KGameHighScoreDialog ksdialog(this);
ksdialog.exec();

To add a new highscore, for example at the end of a game you simply create an object with the Fields you want to write (such as KGameHighScoreDialog::Name | KGameHighScoreDialog::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.

KGameHighScoreDialog 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

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

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

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

ksdialog.addField(KGameHighScoreDialog::Custom1, "Num of Moves", "moves");
scoreInfo[KGameHighScoreDialog::Custom1].setNum(42);

ksdialog.addScore(scoreInfo);

You can define up to 5 Custom fields.

Member Type Documentation

enum KGameHighScoreDialog::AddScoreFlag
flags KGameHighScoreDialog::AddScoreFlags

Flags for setting preferences for adding scores

ConstantValueDescription
KGameHighScoreDialog::AskName0x1Prompt the player for their name.
KGameHighScoreDialog::LessIsMore0x2A lower numerical score means higher placing on the table.

The AddScoreFlags type is a typedef for QFlags<AddScoreFlag>. It stores an OR combination of AddScoreFlag values.

KGameHighScoreDialog::FieldInfo

Stores a combination of AddScoreFlag values.

enum KGameHighScoreDialog::Fields

Highscore fields.

ConstantValueDescription
KGameHighScoreDialog::Name1 << 0The player's name.
KGameHighScoreDialog::Level1 << 1The difficulty level.
KGameHighScoreDialog::Date1 << 2The date of the score.
KGameHighScoreDialog::Time1 << 3The player's time elapsed.
KGameHighScoreDialog::Score1 << 4The player's score.
KGameHighScoreDialog::Custom11 << 10Field for custom information.
KGameHighScoreDialog::Custom21 << 11Field for custom information.
KGameHighScoreDialog::Custom31 << 12Field for custom information.
KGameHighScoreDialog::Custom41 << 13Field for custom information.
KGameHighScoreDialog::Custom51 << 14Field for custom information.
KGameHighScoreDialog::Max1 << 30The maximum number of fields.

Member Function Documentation

[explicit] KGameHighScoreDialog::KGameHighScoreDialog(int fields = Name, QWidget *parent = nullptr)

fields Bitwise OR of the Fields that should be listed (Score is always present) parent passed to parent QWidget constructor.

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

Define an extra FieldInfo entry. field id of this field Fields for example KGameHighScoreDialog::Custom1 header text shown in the header in the dialog for this field, for example "Number of Moves" key unique key used to store this field, for example "moves"

void KGameHighScoreDialog::addLocalizedConfigGroupName(const std::pair<QByteArray, QString> &group)

You must add the translations of all group names to the dialog. This is best done by passing the name through i18n(). The group set through setConfigGroup(const std::pair<QByteArray, QString>& group) will be added automatically.

group is the translated group name.

void KGameHighScoreDialog::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 i18n(). The group set through setConfigGroup(const std::pair<QByteArray, QString>& group) will be added automatically.

groups is the list of translated group names.

int KGameHighScoreDialog::addScore(const KGameHighScoreDialog::FieldInfo &newInfo = FieldInfo(), KGameHighScoreDialog::AddScoreFlags flags = {})

Adds a new score info newInfo to the list. 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.

int KGameHighScoreDialog::addScore(int newScore, KGameHighScoreDialog::AddScoreFlags flags = {})

Adds a new score newScore to the list. 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.

[override virtual] int KGameHighScoreDialog::exec()

Reimplements: QDialog::exec().

Displays the dialog as modal.

void KGameHighScoreDialog::hideField(int field)

Hides a field so that it is not shown on the table (but is still stored in the configuration file). field id of this field Fields for example KGameHighScoreDialog::Score

int KGameHighScoreDialog::highScore()

Returns the current best score in the group.

void KGameHighScoreDialog::initFromDifficulty(const KGameDifficulty *difficulty, bool setConfigGroup = true)

Assumes that config groups (including current selection) are equal to difficulty levels, and initializes them. If setConfigGroup is true, sets the config group to difficulty->currentLevel().

void KGameHighScoreDialog::setComment(const QString &comment)

Sets the comment to add when showing high-scores. The comment is only used once.

void KGameHighScoreDialog::setConfigGroup(const std::pair<QByteArray, QString> &group)

The group name must be passed though i18n() in order for the group name to be translated, for example,

ksdialog.setConfigGroup(std::make_pair(QByteArrayLiteral("Easy"), i18n("Easy")));

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

group to use for reading/writing highscores from/to.

[since KDE 4.2] void KGameHighScoreDialog::setConfigGroupWeights(const QMap<int, QByteArray> &weights)

It is a good idea to give config group weights, otherwise tabs get ordered by their tab name which is probably not what you want.

weights is the list of untranslated group weights.

This function was introduced in KDE 4.2.

[since KDE 4.6] void KGameHighScoreDialog::setHiddenConfigGroups(const QList<QByteArray> &hiddenGroups)

Hides some config groups so that they are not shown on the dialog (but are still stored in the configuration file).

ksdialog.setHiddenConfigGroups(QList<QByteArray>{QByteArrayLiteral("Very Easy"), QByteArrayLiteral("Easy")});

hiddenGroups is the list of group names you want to hide.

This function was introduced in KDE 4.6.

[virtual] void KGameHighScoreDialog::show()

Displays the dialog as non-modal.

[private slot] void KGameHighScoreDialog::slotForgetScore()

[private slot] void KGameHighScoreDialog::slotGotName()

[private slot] void KGameHighScoreDialog::slotGotReturn()