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
| Constant | Value | Description |
|---|---|---|
KGameHighScoreDialog::AskName | 0x1 | Prompt the player for their name. |
KGameHighScoreDialog::LessIsMore | 0x2 | A 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.
| Constant | Value | Description |
|---|---|---|
KGameHighScoreDialog::Name | 1 << 0 | The player's name. |
KGameHighScoreDialog::Level | 1 << 1 | The difficulty level. |
KGameHighScoreDialog::Date | 1 << 2 | The date of the score. |
KGameHighScoreDialog::Time | 1 << 3 | The player's time elapsed. |
KGameHighScoreDialog::Score | 1 << 4 | The player's score. |
KGameHighScoreDialog::Custom1 | 1 << 10 | Field for custom information. |
KGameHighScoreDialog::Custom2 | 1 << 11 | Field for custom information. |
KGameHighScoreDialog::Custom3 | 1 << 12 | Field for custom information. |
KGameHighScoreDialog::Custom4 | 1 << 13 | Field for custom information. |
KGameHighScoreDialog::Custom5 | 1 << 14 | Field for custom information. |
KGameHighScoreDialog::Max | 1 << 30 | The 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.