KDEGames

kgamedifficulty.h
1 /*
2  SPDX-FileCopyrightText: 2007 Nicolas Roffet <[email protected]>
3  SPDX-FileCopyrightText: 2007 Pino Toscano <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #ifndef KGAMEDIFFICULTY_H
9 #define KGAMEDIFFICULTY_H
10 
11 // own
12 #include "libkdegamesprivate_export.h"
13 // Qt
14 #include <QMap>
15 #include <QPair>
16 
17 class QObject;
18 class KGameDifficultyPrivate;
19 class KXmlGuiWindow;
20 
21 
22 /**
23  * \class KGameDifficulty kgamedifficulty.h <KGameDifficulty>
24  *
25  * @brief KGameDifficuty manages the game difficulty levels in a standard way
26  *
27  * KGameDifficulty manages the difficulty levels of a game. The
28  * difficulty can be a type of game (like in KMines: small field / big
29  * field) or the AI skills (like in Bovo: how deep should the computer
30  * search to find the best move) or a combination of both of them. On
31  * the user point of view, it's not really different: either is the
32  * game easy or hard to play.
33  *
34  * KGameDifficulty provides standard actions on the main menu and a
35  * standard combo box in the status bar with the list of the
36  * difficulty levels. They both use the standard icon for
37  * "difficulty". Using KGameDifficulty instead of a custom
38  * implementation is better to provide a uniform user experience over
39  * all KDE games.
40  *
41  * It is possible to use standard difficulty levels (like "Easy",
42  * "Hard", ...) or define custom ones ("My level!"...). Using standard
43  * levels reduces the work of the translator teams and assures that
44  * the translation (for instance of "Medium") will not be different in
45  * different games (and it is better because it is uniform). In some
46  * games, it is no problem if the player changes the difficulty level
47  * during a running game. In others, it is: the current game should be
48  * given up and a new game should be started. In this case,
49  * KGameDifficulty provides a confirmation dialog so the game
50  * programmer does not have to manage this himself: he just has to
51  * tell KGameDifficulty when the game is running and when not.
52  *
53  * Code example: definition of the difficulty levels in the main window class.
54  * @code
55  * KGameDifficulty::init(this, this, SLOT(levelChanged(KGameDifficulty::standardLevel)));
56  * KGameDifficulty::addStandardLevel(KGameDifficulty::Easy);
57  * KGameDifficulty::addStandardLevel(KGameDifficulty::Medium);
58  * KGameDifficulty::addStandardLevel(KGameDifficulty::Hard);
59  * KGameDifficulty::setRestartOnChange(KGameDifficulty::NoRestartOnChange);
60  *
61  * // The default level (it should be read from the config file).
62  * KGameDifficulty::setLevel(KGameDifficulty::Medium);
63  *
64  * // And you also need to define the slot "levelChanged" to manage changes.
65  * // ...
66  * @endcode
67  *
68  * Note that this class is a singleton. So you can have only one current difficulty level per application.
69  *
70  * @author Nicolas Roffet, <[email protected]>
71  */
72 class KDEGAMESPRIVATE_EXPORT KGameDifficulty
73 {
74  public:
75  /**
76  * @brief Behavior on change
77  *
78  * 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.
79  */
80  enum onChange {
81  RestartOnChange, /**< The current game has to be canceled and a new game will be started on change. */
82  NoRestartOnChange /**< The current game can continue on change. */
83  };
84 
85  /**
86  * @brief Standard difficulty levels
87  *
88  * If they fit the needs of the game, the standard appellations of the difficulty levels should be used.
89  */
91  RidiculouslyEasy = 10, /**< Level "Ridiculously easy" */
92  VeryEasy = 20, /**< Level "Very easy" */
93  Easy = 30, /**< Level "Easy" */
94  Medium = 40, /**< Level "Medium" */
95  Hard = 50, /**< Level "Hard" */
96  VeryHard = 60, /**< Level "Very hard" */
97  ExtremelyHard = 70, /**< Level "Extremely hard" */
98  Impossible = 80, /**< Level "Impossible" */
99  Configurable = 90, /**< 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. */
100  Custom = 100, /**< Any custom appellations for levels */
101  NoLevel = 110 /**< No level */
102  };
103 
104 
105  /**
106  * @brief Destructor
107  */
108  virtual ~KGameDifficulty();
109 
110  /**
111  * @brief Initialize the difficulty class
112  *
113  * You must call this class before using the singleton.
114  *
115  * @param window The window where to add menu items.
116  * @param recvr Object that receives the signals and have the following slots.
117  * @param 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))
118  * @param 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))
119  */
120  static void init(KXmlGuiWindow* window, const QObject *recvr, const char* slotStandard, const char* slotCustom = nullptr);
121 
122  /**
123  * @brief Set if a new game has to be started by change
124  *
125  * Default is RestartOnChange.
126  * @param restart Behavior on change
127  */
128  static void setRestartOnChange(onChange restart);
129 
130  /**
131  * @brief Add a standard difficulty level
132  *
133  * You should add all the standard difficulty levels you need after the initialization of the class.
134  * Standard difficulty levels are displayed before custom levels (if available).
135  * @param level Standard difficulty level to add
136  */
137  static void addStandardLevel(standardLevel level);
138 
139  /**
140  * @brief Remove a standard difficulty level
141  *
142  * @param level Standard difficulty level to remove
143  */
144  static void removeStandardLevel(standardLevel level);
145 
146  /**
147  * @brief Add a custom difficulty level
148  *
149  * If you need custom appellations like "8x8", "Coward", "Courageous", "Tired of life" or whatever, you can define them with this method.
150  * Custom difficulty levels are displayed after standard levels (if available).
151  * @param 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.).
152  * @param appellation Custom level appellation.
153  */
154  static void addCustomLevel(int key, const QString& appellation);
155 
156  /**
157  * @brief Remove a custom difficulty level
158  *
159  * @param key Custom level identifier.
160  */
161  static void removeCustomLevel(int key);
162 
163  /**
164  * @brief Set if the difficulty level may be changed.
165  *
166  * If not, all the actions are disabled.
167  * Default is "true".
168  * @param enabled State.
169  */
170  static void setEnabled(bool enabled);
171 
172  /**
173  * @brief Set the new current difficulty level as a standard one
174  *
175  * @param level Standard level.
176  */
177  static void setLevel(standardLevel level);
178 
179  /**
180  * @brief Get the current standard difficulty level
181  *
182  * @return The current standard level, or customLevel if a custom level is selected, or noLevel if no difficulty level is selected.
183  */
184  static standardLevel level();
185  /**
186  * @return current standard level string name
187  */
188  static QString levelString();
189  /**
190  * @return current standard level name translated string
191  */
192  static QPair<QByteArray, QString> localizedLevelString();
193  /**
194  * @return list of translated standard level string names
195  */
196  static QMap<QByteArray, QString> localizedLevelStrings();
197  /**
198  * @return map with the weight order of untranslated standard level names matches value of standardLevel enum
199  * @since KDE 4.2
200  */
201  static QMap<int, QByteArray> levelWeights();
202  /**
203  * @brief Set the new current difficulty level as a custom one
204  *
205  * This sets also the value of the standard level to "custom".
206  * @param key Custom level identifier.
207  */
208  static void setLevelCustom(int key);
209 
210  /**
211  * @brief Get the current custom difficulty level
212  *
213  * It does only make sense to get the current custom difficulty level, if the value of the level is "custom".
214  * @return The current custom level identifier.
215  */
216  static int levelCustom();
217 
218  /**
219  * @brief Set the game state: Running or not
220  *
221  * The game state should be defined if the current onChange value is restartByChange.
222  * Default: false.
223  * @param running Running state.
224  */
225  static void setRunning(bool running);
226 
227 
228  private:
229  /**
230  * Private constructor: we are a singleton
231  */
232  KGameDifficulty();
233  /**
234  * @brief Access to the unique instance of the class
235  *
236  * Be aware to call init first.
237  * @see init
238  */
239  static KGameDifficulty* self();
240 
241  static KGameDifficulty* instance;
242  friend class KGameDifficultyPrivate;
243  KGameDifficultyPrivate* const d;
244 
245  Q_DISABLE_COPY(KGameDifficulty)
246 };
247 
248 #endif //KGAMEDIFFICULTY_H
KGameDifficuty manages the game difficulty levels in a standard way.
onChange
Behavior on change.
QCA_EXPORT void init()
standardLevel
Standard difficulty levels.
The current game has to be canceled and a new game will be started on change.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Dec 6 2021 22:33:52 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.