#include <KGameDifficulty>

Public Types

enum  onChange { RestartOnChange, NoRestartOnChange }
enum  standardLevel {
  RidiculouslyEasy = 10, VeryEasy = 20, Easy = 30, Medium = 40,
  Hard = 50, VeryHard = 60, ExtremelyHard = 70, Impossible = 80,
  Configurable = 90, Custom = 100, NoLevel = 110

Public Member Functions

virtual ~KGameDifficulty ()

Static Public Member Functions

static void addCustomLevel (int key, const QString &appellation)
static void addStandardLevel (standardLevel level)
static void init (KXmlGuiWindow *window, const QObject *recvr, const char *slotStandard, const char *slotCustom=nullptr)
static standardLevel level ()
static int levelCustom ()
static QString levelString ()
static QMap< int, QByteArraylevelWeights ()
static QPair< QByteArray, QStringlocalizedLevelString ()
static QMap< QByteArray, QStringlocalizedLevelStrings ()
static void removeCustomLevel (int key)
static void removeStandardLevel (standardLevel level)
static void setEnabled (bool enabled)
static void setLevel (standardLevel level)
static void setLevelCustom (int key)
static void setRestartOnChange (onChange restart)
static void setRunning (bool running)

Detailed Description

KGameDifficuty manages the game difficulty levels in a standard way.

KGameDifficulty manages the difficulty levels of a game. The difficulty can be a type of game (like in KMines: small field / big field) or the AI skills (like in Bovo: how deep should the computer search to find the best move) or a combination of both of them. On the user point of view, it's not really different: either is the game easy or hard to play.

KGameDifficulty provides standard actions on the main menu and a standard combo box in the status bar with the list of the difficulty levels. They both use the standard icon for "difficulty". Using KGameDifficulty instead of a custom implementation is better to provide a uniform user experience over all KDE games.

It is possible to use standard difficulty levels (like "Easy", "Hard", ...) or define custom ones ("My level!"...). Using standard levels reduces the work of the translator teams and assures that the translation (for instance of "Medium") will not be different in different games (and it is better because it is uniform). In some games, it is no problem if the player changes the difficulty level during a running game. In others, it is: the current game should be given up and a new game should be started. In this case, KGameDifficulty provides a confirmation dialog so the game programmer does not have to manage this himself: he just has to tell KGameDifficulty when the game is running and when not.

Code example: definition of the difficulty levels in the main window class.

Note that this class is a singleton. So you can have only one current difficulty level per application.

Nicolas Roffet, nicol[email protected]as-k[email protected][email protected][email protected]ffet[email protected].com

Definition at line 72 of file kgamedifficulty.h.

Member Enumeration Documentation

Behavior on change.

Does the game have to be restarted, when the player changes the difficulty level? In this case and if the game is running, a confirmation dialog is displayed and the player can cancel the change.


The current game has to be canceled and a new game will be started on change.


The current game can continue on change.

Definition at line 80 of file kgamedifficulty.h.

Standard difficulty levels.

If they fit the needs of the game, the standard appellations of the difficulty levels should be used.


Level "Ridiculously easy".


Level "Very easy".


Level "Easy".


Level "Medium".


Level "Hard".


Level "Very hard".


Level "Extremely hard".


Level "Impossible".


Level "Custom".

This is a special item to let the player configure the difficulty level. The configuration of the user level has to be implemented in each game using it with an adapted dialog. Example: In a minesweeper game like KMines, the player wants to define the number of rows, columns and mines.


Any custom appellations for levels.


No level.

Definition at line 90 of file kgamedifficulty.h.

Constructor & Destructor Documentation

KGameDifficulty::~KGameDifficulty ( )


Definition at line 285 of file kgamedifficulty.cpp.

Member Function Documentation

void KGameDifficulty::addCustomLevel ( int  key,
const QString appellation 

Add a custom difficulty level.

If you need custom appellations like "8x8", "Coward", "Courageous", "Tired of life" or whatever, you can define them with this method. Custom difficulty levels are displayed after standard levels (if available).

keyCustom level identifier. (It must be distinct for every different level. Trying to add a new level with an allocated key replace the previous level.).
appellationCustom level appellation.

Definition at line 330 of file kgamedifficulty.cpp.

void KGameDifficulty::addStandardLevel ( standardLevel  level)

Add a standard difficulty level.

You should add all the standard difficulty levels you need after the initialization of the class. Standard difficulty levels are displayed before custom levels (if available).

levelStandard difficulty level to add

Definition at line 310 of file kgamedifficulty.cpp.

void KGameDifficulty::init ( KXmlGuiWindow window,
const QObject recvr,
const char *  slotStandard,
const char *  slotCustom = nullptr 

Initialize the difficulty class.

You must call this class before using the singleton.

windowThe window where to add menu items.
recvrObject that receives the signals and have the following slots.
slotStandardSlot to call when the player changed the difficulty level to a standard one. Slot should have the signature like: SLOT(levelChanged(KGameDifficulty::standardLevel))
slotCustomSlot to call when the player changed the difficulty level to a custom one. (Optional). Slot should have the signature like: SLOT(customLevelChanged(int))

Definition at line 291 of file kgamedifficulty.cpp.

KGameDifficulty::standardLevel KGameDifficulty::level ( )

Get the current standard difficulty level.

The current standard level, or customLevel if a custom level is selected, or noLevel if no difficulty level is selected.

Definition at line 382 of file kgamedifficulty.cpp.

int KGameDifficulty::levelCustom ( )

Get the current custom difficulty level.

It does only make sense to get the current custom difficulty level, if the value of the level is "custom".

The current custom level identifier.

Definition at line 374 of file kgamedifficulty.cpp.

QString KGameDifficulty::levelString ( )
current standard level string name

Definition at line 390 of file kgamedifficulty.cpp.

QMap< int, QByteArray > KGameDifficulty::levelWeights ( )
map with the weight order of untranslated standard level names matches value of standardLevel enum
KDE 4.2

Definition at line 424 of file kgamedifficulty.cpp.

QPair< QByteArray, QString > KGameDifficulty::localizedLevelString ( )
current standard level name translated string

Definition at line 398 of file kgamedifficulty.cpp.

QMap< QByteArray, QString > KGameDifficulty::localizedLevelStrings ( )
list of translated standard level string names

Definition at line 406 of file kgamedifficulty.cpp.

void KGameDifficulty::removeCustomLevel ( int  key)

Remove a custom difficulty level.

keyCustom level identifier.

Definition at line 339 of file kgamedifficulty.cpp.

void KGameDifficulty::removeStandardLevel ( standardLevel  level)

Remove a standard difficulty level.

levelStandard difficulty level to remove

Definition at line 321 of file kgamedifficulty.cpp.

void KGameDifficulty::setEnabled ( bool  enabled)

Set if the difficulty level may be changed.

If not, all the actions are disabled. Default is "true".


Definition at line 348 of file kgamedifficulty.cpp.

void KGameDifficulty::setLevel ( standardLevel  level)

Set the new current difficulty level as a standard one.

levelStandard level.

Definition at line 358 of file kgamedifficulty.cpp.

void KGameDifficulty::setLevelCustom ( int  key)

Set the new current difficulty level as a custom one.

This sets also the value of the standard level to "custom".

keyCustom level identifier.

Definition at line 366 of file kgamedifficulty.cpp.

void KGameDifficulty::setRestartOnChange ( onChange  restart)

Set if a new game has to be started by change.

Default is RestartOnChange.

restartBehavior on change

Definition at line 297 of file kgamedifficulty.cpp.

void KGameDifficulty::setRunning ( bool  running)

Set the game state: Running or not.

The game state should be defined if the current onChange value is restartByChange. Default: false.

runningRunning state.

Definition at line 441 of file kgamedifficulty.cpp.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Wed Jan 27 2021 22:37:06 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.