KDEGames

kgamedifficulty.h
1 /*
2  SPDX-FileCopyrightText: 2007 Nicolas Roffet <[email protected]>
3  SPDX-FileCopyrightText: 2007 Pino Toscano <[email protected]>
4  SPDX-FileCopyrightText: 2011-2012 Stefan Majewsky <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 
9 #ifndef KGAMEDIFFICULTY_H
10 #define KGAMEDIFFICULTY_H
11 
12 // own
13 #include "kdegames_export.h"
14 // Qt
15 #include <QMetaType>
16 #include <QObject>
17 // Std
18 #include <memory>
19 
20 /**
21  * @class KGameDifficultyLevel kgamedifficulty.h <KGameDifficultyLevel>
22  * @see KGameDifficulty
23  */
24 class KDEGAMES_EXPORT KGameDifficultyLevel : public QObject
25 {
26  Q_OBJECT
28  Q_PROPERTY(bool default READ isDefault)
29  Q_PROPERTY(int hardness READ hardness)
30  Q_PROPERTY(QByteArray key READ key)
31  Q_PROPERTY(QString title READ title)
32  Q_PROPERTY(StandardLevel standardLevel READ standardLevel)
33 
34 public:
36  Custom = -1, ///< standardLevel() returns this for custom levels.
37  RidiculouslyEasy = 10,
38  VeryEasy = 20,
39  Easy = 30,
40  Medium = 40,
41  Hard = 50,
42  VeryHard = 60,
43  ExtremelyHard = 70,
44  Impossible = 80
45  };
46  Q_ENUM(StandardLevel)
47 
48  /// Refer to the getters' documentation for details on the params.
49  KGameDifficultyLevel(int hardness, const QByteArray &key, const QString &title, bool isDefault = false);
50  explicit KGameDifficultyLevel(StandardLevel level, bool isDefault = false);
51  ~KGameDifficultyLevel() override;
52 
53  /// @return whether this level is the default level when no selection has
54  /// been stored (e.g. on first startup)
55  bool isDefault() const;
56  /// @return a numeric key which is used to sort the levels by difficulty
57  /// (smaller values mean easier levels)
58  /// @note For standard levels, this equals the numeric value of the level
59  /// in the StandardLevel enumeration.
60  int hardness() const;
61  /// @return a @b non-localized key for this level
62  QByteArray key() const;
63  /// @return a @b localized title for this level
64  QString title() const;
65  /// @return the standard level which was used to create this level, or
66  /// KGameDifficultyLevel::Custom for custom levels
67  StandardLevel standardLevel() const;
68 
69 private:
70  std::unique_ptr<class KGameDifficultyLevelPrivate> const d_ptr;
71  Q_DECLARE_PRIVATE(KGameDifficultyLevel)
72 };
73 
74 /**
75  * @class KGameDifficulty kgamedifficulty.h <KGameDifficulty>
76  * @brief KGameDifficulty manages difficulty levels of a game in a standard way.
77  *
78  * The difficulty can be a type of game (like in KMines: small or big field) or
79  * the AI skills (like in Bovo: how deep should the computer search to find the
80  * best move) or a combination of both of them. On the user point of view, it's
81  * not really different: either is the game easy or hard to play.
82  *
83  * KGameDifficulty contains a list of KGameDifficultyLevel instances. One of
84  * these levels is selected; this selection will be recorded when the
85  * application is closed. A set of standard difficulty levels is provided by
86  * KGameDifficultyLevel, but custom levels can be defined at the same time.
87  */
88 class KDEGAMES_EXPORT KGameDifficulty : public QObject
89 {
90  Q_OBJECT
92  // Use currentLevel in game logic and selectedLevel in level selection UI.
93  Q_PROPERTY(const KGameDifficultyLevel *currentLevel READ currentLevel WRITE select NOTIFY currentLevelChanged)
94  Q_PROPERTY(const KGameDifficultyLevel *selectedLevel READ currentLevel WRITE select NOTIFY selectedLevelChanged)
95  Q_PROPERTY(bool editable READ isEditable WRITE setEditable NOTIFY editableChanged)
96  Q_PROPERTY(bool gameRunning READ isGameRunning WRITE setGameRunning NOTIFY gameRunningChanged)
97 
98 public:
99  /// @return a singleton instance of KGameDifficulty
100  static KGameDifficulty *global();
101  /// A shortcut for KGameDifficulty::global()->currentLevel()->standardLevel().
102  static KGameDifficultyLevel::StandardLevel globalLevel();
103 
104 public:
105  explicit KGameDifficulty(QObject *parent = nullptr);
106  /// Destroys this instance and all DifficultyLevel instances in it.
107  ~KGameDifficulty() override;
108 
109  /// Adds a difficulty level to this instance. This will not affect the
110  /// currentLevel() if there is one.
111  void addLevel(KGameDifficultyLevel *level);
112  /// A shortcut for addLevel(new KGameDifficultyLevel(@a level)).
113  void addStandardLevel(KGameDifficultyLevel::StandardLevel level, bool isDefault = false);
114  /// This convenience method adds a range of standard levels to this
115  /// instance (including the boundaries). For example:
116  /// @code
117  /// difficulty.addStandardLevelRange(
118  /// KGameDifficultyLevel::Easy,
119  /// KGameDifficultyLevel::VeryHard
120  ///);
121  /// @endcode
122  /// This adds the levels "Easy", "Medium", "Hard" and "Very hard".
124  /// @overload
125  /// This overload allows to specify a @a defaultLevel.
126  void
128 
129  /// @return a list of all difficulty levels, sorted by hardness
131  /// @return the current difficulty level
132  ///
133  /// After the KGameDifficulty object has been created, the current
134  /// difficulty level will not be determined until this method is called
135  /// for the first time. This allows the application developer to set up
136  /// the difficulty levels before KGameDifficulty retrieves the last
137  /// selected level from the configuration file.
138  const KGameDifficultyLevel *currentLevel() const;
139 
140  /// @return whether the difficulty level selection may be edited
141  bool isEditable() const;
142  /// @return whether a running game has been marked @see setGameRunning
143  bool isGameRunning() const;
144  /// Set whether the difficulty level selection may be edited. The
145  /// default value is true.
146  void setEditable(bool editable);
147  /// KGameDifficulty has optional protection against changing the
148  /// difficulty level while a game is running. If setGameRunning(true) has
149  /// been called, and select() is called to select a new difficulty level,
150  /// the user will be asked for confirmation.
151  void setGameRunning(bool running);
152 Q_SIGNALS:
153  /// Emitted when the editability changes. @see setEditable
154  void editableChanged(bool editable);
155  /// Emitted when a running game has been marked or unmarked. @see setGameRunning
156  void gameRunningChanged(bool gameRunning);
157  /// Emitted when a new difficulty level has been selected.
158  void currentLevelChanged(const KGameDifficultyLevel *level);
159  /// Emitted after every call to select(), even when the user has rejected
160  /// the change. This is useful to reset a difficulty level selection UI
161  /// after a rejected change.
162  void selectedLevelChanged(const KGameDifficultyLevel *level);
163 public Q_SLOTS:
164  /// Select a new difficulty level. The given level must already have been
165  /// added to this instance.
166  /// @note This does nothing if isEditable() is false. If a game is
167  /// running (according to setGameRunning()), the user will be asked for
168  /// confirmation before the new difficulty level is selected.
169  void select(const KGameDifficultyLevel *level);
170 
171 private:
172  std::unique_ptr<class KGameDifficultyPrivate> const d_ptr;
173  Q_DECLARE_PRIVATE(KGameDifficulty)
174 };
175 
176 Q_DECLARE_METATYPE(const KGameDifficultyLevel *)
177 
178 class KXmlGuiWindow;
179 
180 /**
181  * @namespace KGameDifficultyGUI
182  *
183  * The namespace for methods to integrate KGameDifficulty into the UI.
184  *
185  * @see KGameDifficulty
186  */
187 // TODO KDE5: move this into a separate QtWidgets support library
188 namespace KGameDifficultyGUI
189 {
190 /// Install standard GUI components for the manipulation of the given
191 /// KGameDifficulty instance in the given @a window.
192 ///
193 /// Without a second parameter, the KGameDifficulty::global() singleton is used.
194 KDEGAMES_EXPORT void init(KXmlGuiWindow *window, KGameDifficulty *difficulty = nullptr);
195 }
196 
197 #endif // KGAMEDIFFICULTY_H
Q_PROPERTY(...)
Q_ENUM(...)
Q_SLOTSQ_SLOTS
KGameDifficulty manages difficulty levels of a game in a standard way.
Q_SIGNALSQ_SIGNALS
void init(KXmlGuiWindow *window, KGameDifficulty *difficulty=nullptr)
Install standard GUI components for the manipulation of the given KGameDifficulty instance in the giv...
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Nov 29 2023 04:08:40 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.