KDEGames

kgdifficulty.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 KGDIFFICULTY_H
10 #define KGDIFFICULTY_H
11 
12 // own
13 #include <libkdegames_export.h>
14 // Qt
15 #include <QMetaType>
16 #include <QObject>
17 // Std
18 #include <memory>
19 
20 /**
21  * @class KgDifficultyLevel kgdifficulty.h <KgDifficultyLevel>
22  * @see KgDifficulty
23  */
24 class KDEGAMES_EXPORT KgDifficultyLevel : 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  public:
35  {
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  };
47 
48  ///Refer to the getters' documentation for details on the params.
49  KgDifficultyLevel(int hardness, const QByteArray& key, const QString& title, bool isDefault = false);
50  explicit KgDifficultyLevel(StandardLevel level, bool isDefault = false);
51  ~KgDifficultyLevel() 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  /// KgDifficultyLevel::Custom for custom levels
67  StandardLevel standardLevel() const;
68  private:
69  std::unique_ptr<class KgDifficultyLevelPrivate> const d;
70 };
71 
72 /**
73  * @class KgDifficulty kgdifficulty.h <KgDifficulty>
74  * @brief KgDifficulty manages difficulty levels of a game in a standard way.
75  *
76  * The difficulty can be a type of game (like in KMines: small or big field) or
77  * the AI skills (like in Bovo: how deep should the computer search to find the
78  * best move) or a combination of both of them. On the user point of view, it's
79  * not really different: either is the game easy or hard to play.
80  *
81  * KgDifficulty contains a list of KgDifficultyLevel instances. One of
82  * these levels is selected; this selection will be recorded when the
83  * application is closed. A set of standard difficulty levels is provided by
84  * KgDifficultyLevel, but custom levels can be defined at the same time.
85  */
86 class KDEGAMES_EXPORT KgDifficulty : public QObject
87 {
88  Q_OBJECT
90  //Use currentLevel in game logic and selectedLevel in level selection UI.
91  Q_PROPERTY(const KgDifficultyLevel* currentLevel READ currentLevel WRITE select NOTIFY currentLevelChanged)
92  Q_PROPERTY(const KgDifficultyLevel* selectedLevel READ currentLevel WRITE select NOTIFY selectedLevelChanged)
93  Q_PROPERTY(bool editable READ isEditable WRITE setEditable NOTIFY editableChanged)
94  Q_PROPERTY(bool gameRunning READ isGameRunning WRITE setGameRunning NOTIFY gameRunningChanged)
95  public:
96  explicit KgDifficulty(QObject* parent = nullptr);
97  ///Destroys this instance and all DifficultyLevel instances in it.
98  ~KgDifficulty() override;
99 
100  ///Adds a difficulty level to this instance. This will not affect the
101  ///currentLevel() if there is one.
102  void addLevel(KgDifficultyLevel* level);
103  ///A shortcut for addLevel(new KgDifficultyLevel(@a level)).
104  void addStandardLevel(KgDifficultyLevel::StandardLevel level, bool isDefault = false);
105  ///This convenience method adds a range of standard levels to this
106  ///instance (including the boundaries). For example:
107  ///@code
108  ///difficulty.addStandardLevelRange(
109  /// KgDifficultyLevel::Easy,
110  /// KgDifficultyLevel::VeryHard
111  ///);
112  ///@endcode
113  ///This adds the levels "Easy", "Medium", "Hard" and "Very hard".
114  void addStandardLevelRange(KgDifficultyLevel::StandardLevel from, KgDifficultyLevel::StandardLevel to);
115  ///@overload
116  ///This overload allows to specify a @a defaultLevel.
118 
119  ///@return a list of all difficulty levels, sorted by hardness
120  QList<const KgDifficultyLevel*> levels() const;
121  ///@return the current difficulty level
122  ///
123  ///After the KgDifficulty object has been created, the current
124  ///difficulty level will not be determined until this method is called
125  ///for the first time. This allows the application developer to set up
126  ///the difficulty levels before KgDifficulty retrieves the last
127  ///selected level from the configuration file.
128  const KgDifficultyLevel* currentLevel() const;
129 
130  ///@return whether the difficulty level selection may be edited
131  bool isEditable() const;
132  ///@return whether a running game has been marked @see setGameRunning
133  bool isGameRunning() const;
134  ///Set whether the difficulty level selection may be edited. The
135  ///default value is true.
136  void setEditable(bool editable);
137  ///KgDifficulty has optional protection against changing the
138  ///difficulty level while a game is running. If setGameRunning(true) has
139  ///been called, and select() is called to select a new difficulty level,
140  ///the user will be asked for confirmation.
141  void setGameRunning(bool running);
142  Q_SIGNALS:
143  ///Emitted when the editability changes. @see setEditable
144  void editableChanged(bool editable);
145  ///Emitted when a running game has been marked or unmarked. @see setGameRunning
146  void gameRunningChanged(bool gameRunning);
147  ///Emitted when a new difficulty level has been selected.
148  void currentLevelChanged(const KgDifficultyLevel* level);
149  ///Emitted after every call to select(), even when the user has rejected
150  ///the change. This is useful to reset a difficulty level selection UI
151  ///after a rejected change.
152  void selectedLevelChanged(const KgDifficultyLevel* level);
153  public Q_SLOTS:
154  ///Select a new difficulty level. The given level must already have been
155  ///added to this instance.
156  ///@note This does nothing if isEditable() is false. If a game is
157  ///running (according to setGameRunning()), the user will be asked for
158  ///confirmation before the new difficulty level is selected.
159  void select(const KgDifficultyLevel* level);
160  private:
161  std::unique_ptr<class KgDifficultyPrivate> const d;
162 };
163 
164 Q_DECLARE_METATYPE(const KgDifficultyLevel*)
165 
166 //TODO: Where to put documentation for this namespace?
167 namespace Kg
168 {
169  ///@return a singleton instance of KgDifficulty
170  KDEGAMES_EXPORT KgDifficulty* difficulty();
171  ///A shortcut for Kg::difficulty()->currentLevel()->standardLevel().
172  KDEGAMES_EXPORT KgDifficultyLevel::StandardLevel difficultyLevel();
173 }
174 
175 class KXmlGuiWindow;
176 
177 //TODO KDE5: move this into a separate QtWidgets support library
178 namespace KgDifficultyGUI
179 {
180  ///Install standard GUI components for the manipulation of the given
181  ///KgDifficulty instance in the given @a window.
182  ///
183  ///Without a second parameter, the Kg::difficulty() singleton is used.
184  KDEGAMES_EXPORT void init(KXmlGuiWindow* window, KgDifficulty* difficulty = nullptr);
185 }
186 
187 #endif // KGDIFFICULTY_H
Q_ENUM(...)
Q_PROPERTY(...)
QCA_EXPORT void init()
Q_DISABLE_COPY(Class)
KgDifficulty manages difficulty levels of a game in a standard way.
Definition: kgdifficulty.h:86
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Dec 7 2021 22:34:15 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.