libkdegames

KGameDifficulty Class Reference

#include <KGameDifficulty>

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 not problem if the player changes the difficulty level during a running game. In other, 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 have to tell KGameDifficulty when the game is running and when not.

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

 KGameDifficulty::init(this, this, SLOT(levelChanged(KGameDifficulty::standardLevel)));
 KGameDifficulty::addStandardLevel(KGameDifficulty::Easy);
 KGameDifficulty::addStandardLevel(KGameDifficulty::Medium);
 KGameDifficulty::addStandardLevel(KGameDifficulty::Hard);
 KGameDifficulty::setRestartOnChange(KGameDifficulty::NoRestartOnChange);

 // The default level (it should be read from the config file).
 KGameDifficulty::setLevel(KGameDifficulty::Medium);

 // And you need also to define the slot "levelChanged" to manage changes.
 // ...

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

Author:: Nicolas Roffet, <nicolas-kde@roffet.com>

Definition at line 78 of file kgamedifficulty.h.


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=0)
static standardLevel	level ()
static int	levelCustom ()
static QString	levelString ()
static QPair< QByteArray, QString >	localizedLevelString ()
static QMap< QByteArray, QString >	localizedLevelStrings ()
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)

Member Enumeration Documentation

enum KGameDifficulty::onChange

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.

Enumerator:

RestartOnChange
NoRestartOnChange	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 86 of file kgamedifficulty.h.

enum KGameDifficulty::standardLevel

Standard difficulty levels.

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

Enumerator:

RidiculouslyEasy
VeryEasy	Level "Ridiculously easy".
Easy	Level "Very easy".
Medium	Level "Easy".
Hard	Level "Medium".
VeryHard	Level "Hard".
ExtremelyHard	Level "Very hard".
Impossible	Level "Extremely hard".
Configurable	Level "Impossible".
Custom	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.
NoLevel	Any custom appellations for levels.

Definition at line 96 of file kgamedifficulty.h.

Constructor & Destructor Documentation

KGameDifficulty::~KGameDifficulty ( ) [virtual]

Destructor.

Definition at line 286 of file kgamedifficulty.cpp.

Member Function Documentation

void KGameDifficulty::addCustomLevel	(	int	key,
		const QString &	appellation
	)			`[static]`

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).

Parameters:

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

Definition at line 331 of file kgamedifficulty.cpp.

void KGameDifficulty::addStandardLevel ( standardLevel level ) [static]

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).

Parameters:

level

Standard difficulty level to add

Definition at line 311 of file kgamedifficulty.cpp.

void KGameDifficulty::init	(	KXmlGuiWindow *	window,
		const QObject *	recvr,
		const char *	slotStandard,
		const char *	slotCustom = `0`
	)			`[static]`

Initialize the difficulty class.

You must call this class before using the singleton.

Parameters:

	window	The window where to add menu items.
	recvr	Object that receives the signals and have the following slots.
	slotStandard	Slot to call when the player changed the difficulty level to a standard one. Slot should have the signature like: SLOT(levelChanged(KGameDifficulty::standardLevel))
	slotCustom	Slot 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 292 of file kgamedifficulty.cpp.

KGameDifficulty::standardLevel KGameDifficulty::level ( ) [static]

Get the current standard difficulty level.

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

Definition at line 383 of file kgamedifficulty.cpp.

int KGameDifficulty::levelCustom ( ) [static]

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".

Returns:: The current custom level identifier.

Definition at line 375 of file kgamedifficulty.cpp.

QString KGameDifficulty::levelString ( ) [static]

Returns:: current standard level string name

Definition at line 391 of file kgamedifficulty.cpp.

QPair< QByteArray, QString > KGameDifficulty::localizedLevelString ( ) [static]

Returns:: current standard level name translated string

Definition at line 399 of file kgamedifficulty.cpp.

QMap< QByteArray, QString > KGameDifficulty::localizedLevelStrings ( ) [static]

Returns:: list of translated standard level string names

Definition at line 407 of file kgamedifficulty.cpp.

void KGameDifficulty::removeCustomLevel ( int key ) [static]

Remove a custom difficulty level.

Parameters:

key

Custom level identifier.

Definition at line 340 of file kgamedifficulty.cpp.

void KGameDifficulty::removeStandardLevel ( standardLevel level ) [static]

Remove a standard difficulty level.

Parameters:

level

Standard difficulty level to remove

Definition at line 322 of file kgamedifficulty.cpp.

void KGameDifficulty::setEnabled ( bool enabled ) [static]

Set if the difficulty level may be changed.

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

Parameters:

enabled

State.

Definition at line 349 of file kgamedifficulty.cpp.

void KGameDifficulty::setLevel ( standardLevel level ) [static]

Set the new current difficulty level as a standard one.

Parameters:

level

Standard level.

Definition at line 359 of file kgamedifficulty.cpp.

void KGameDifficulty::setLevelCustom ( int key ) [static]

Set the new current difficulty level as a custom one.

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

Parameters:

key

Custom level identifier.

Definition at line 367 of file kgamedifficulty.cpp.

void KGameDifficulty::setRestartOnChange ( onChange restart ) [static]

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

Default is RestartOnChange.

Parameters:

restart

Behavior on change

Definition at line 298 of file kgamedifficulty.cpp.

void KGameDifficulty::setRunning ( bool running ) [static]

Set the game state: Running or not.

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

Parameters:

running

Running state.

Definition at line 426 of file kgamedifficulty.cpp.

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

libkdegames

KGameDifficulty Class Reference

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

libkdegames

API Reference