libkdegames/kgamedifficulty.h

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