summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBruno Dilly <bdilly@profusion.mobi>2012-12-14 04:01:41 +0000
committerBruno Dilly <bdilly@profusion.mobi>2012-12-14 04:01:41 +0000
commit0c067ecfcfafdf25a33bcb86bd0a91f804da6969 (patch)
tree18c2bd9b485117271eddaddc263c2c933909f187
parent2835c9799f5ee065a9c1373e32b5d87ca3c9b9ba (diff)
etrophy: split functions in documented groups
SVN revision: 80911
-rw-r--r--src/lib/Etrophy.h409
1 files changed, 327 insertions, 82 deletions
diff --git a/src/lib/Etrophy.h b/src/lib/Etrophy.h
index 918ae7f..9ce0025 100644
--- a/src/lib/Etrophy.h
+++ b/src/lib/Etrophy.h
@@ -1,6 +1,41 @@
1#ifndef __ETROPHY_H__ 1#ifndef __ETROPHY_H__
2#define __ETROPHY_H__ 2#define __ETROPHY_H__
3 3
4/**
5 * @mainpage Etrophy Library Documentation
6 *
7 * @version 0.5.0
8 * @date 2012
9 *
10 * @section intro What is Etrophy ?
11 *
12 * Etrophy is a library that manages scores, trophies and unlockables. It will
13 * store them and provide views to display them. Could be used by games based
14 * on EFL.
15 *
16 * For a better reference, check the following groups:
17 * @li @ref Init
18 * @li @ref Gamescore
19 * @li @ref Score
20 * @li @ref Trophy
21 * @li @ref Lock
22 * @li @ref View
23 *
24 * Please see the @ref authors page for contact details.
25 */
26
27/**
28 *
29 * @page authors Authors
30 *
31 * @author Bruno Dilly <bdilly@@profusion.mobi>
32 * @author Mike Blumenkrantz <michael.blumenkrantz@@gmail.com>
33 *
34 * Please contact <enlightenment-devel@lists.sourceforge.net> to get in
35 * contact with the developers and maintainers.
36 *
37 */
38
4#include <Eina.h> 39#include <Eina.h>
5#include <Eet.h> 40#include <Eet.h>
6#include <Evas.h> 41#include <Evas.h>
@@ -35,6 +70,185 @@
35extern "C" { 70extern "C" {
36#endif 71#endif
37 72
73/**
74 * @file
75 * @brief These routines are used for Etrophy library interaction.
76 */
77
78/**
79 * @brief Init / shutdown functions.
80 * @defgroup Init Init / Shutdown
81 *
82 * @{
83 *
84 * Functions of obligatory usage, handling proper initialization
85 * and shutdown routines.
86 *
87 * Before the usage of any other function, Etrophy should be properly
88 * initialized with @ref etrophy_init() and the last call to Etrophy's
89 * functions should be @ref etrophy_shutdown(), so everything will
90 * be correctly freed.
91 *
92 * Etrophy logs everything with Eina Log, using the "etrophy" log domain.
93 *
94 */
95
96EAPI int etrophy_init(void);
97EAPI int etrophy_shutdown(void);
98
99/**
100 * @}
101 */
102
103/**
104 * @brief Gamescore API available to add a gamescore for your application.
105 * @defgroup Gamescore Gamescore
106 *
107 * @{
108 *
109 * Gamescore is the object that will integrate all the components required
110 * for the application, like trophies, scores and locks. It's mandatory
111 * to have one created gamescore before adding anything else, so generally
112 * an application should start by handling it.
113 *
114 * Example:
115 * @code
116 * Etrophy_Gamescore *gamescore;
117 * gamescore = etrophy_gamescore_load("gamename");
118 * if (!gamescore)
119 * {
120 * gamescore = etrophy_gamescore_new("gamename");
121 * // Functions populating the generated gamescore like a bunch of
122 * // @ref etrophy_lock_new(), @ref etrophy_gamescore_lock_add()
123 * }
124 * @endcode
125 *
126 * Gamescore can be created with @ref etrophy_gamescore_new(), or loaded
127 * with @ref etrophy_gamescore_load(), @ref etrophy_gamescore_path_load().
128 * @ref etrophy_gamescore_edd_get() can be used to get the Eet data descriptor.
129 *
130 * The gamescore must to be saved with @ref etrophy_gamescore_save() or changes
131 * will be lost. It can be cleared with @ref etrophy_gamescore_clear().
132 *
133 * After usage it should be freed with @ref etrophy_gamescore_free().
134 *
135 */
136
137typedef struct _Etrophy_Gamescore Etrophy_Gamescore;
138
139EAPI void etrophy_gamescore_clear(Etrophy_Gamescore *gamescore);
140EAPI Etrophy_Gamescore *etrophy_gamescore_new(const char *gamename);
141EAPI void etrophy_gamescore_free(Etrophy_Gamescore *gamescore);
142EAPI Eet_Data_Descriptor *etrophy_gamescore_edd_get(void);
143EAPI Etrophy_Gamescore *etrophy_gamescore_path_load(const char *filename);
144EAPI Etrophy_Gamescore *etrophy_gamescore_load(const char *gamename);
145EAPI Eina_Bool etrophy_gamescore_save(Etrophy_Gamescore *gamescore, const char *filename);
146
147/**
148 * @}
149 */
150
151/**
152 * @brief Functions to manipulate player's scores.
153 * @defgroup Score Score
154 *
155 * @{
156 *
157 * Scores consists of the player name, amount of points earned, and date
158 * and time. It should be added to the specific level. So basically,
159 * a gamescore has many levels, and each level many scores saved.
160 * So a level just have a name and a list of scores.
161 *
162 * These two objects are handled by @ref Etrophy_Score and @ref Etrophy_Level.
163 *
164 * Levels can be created by two ways:
165 * @li Creating a level inside a gamescore with
166 * @ref etrophy_gamescore_level_add().
167 * @li Creating a level with @ref etrophy_level_new() and adding it to
168 * gamescore with @ref etrophy_gamescore_level_add();
169 *
170 * The list of levels in the gamescore can be get with
171 * @ref etrophy_gamescore_levels_list_get() and can be cleared with
172 * @ref etrophy_gamescore_levels_list_clear(). A specific level can be get
173 * with @ref etrophy_gamescore_level_get().
174 *
175 * Scores can be created using @ref etrophy_score_new() and added to a
176 * level with @ref etrophy_gamescore_level_score_add() or directly with
177 * @ref etrophy_level_score_add(). A list of scores can be get
178 * with @ref etrophy_level_scores_list_get(). But a couple of functions
179 * can be very useful:
180 * @li @ref etrophy_gamescore_level_hi_score_get() to get the highest score
181 * in a specific level and
182 * @li @ref etrophy_gamescore_level_hi_score_get() to get the lowest one
183 * (useful for games based on time).
184 *
185 * Score properties can be accessed with:
186 * @li @ref etrophy_score_player_name_get()
187 * @li @ref etrophy_score_score_get()
188 * @li @ref etrophy_score_date_get()
189 *
190 */
191
192typedef struct _Etrophy_Level Etrophy_Level;
193typedef struct _Etrophy_Score Etrophy_Score;
194
195EAPI Etrophy_Level *etrophy_level_new(const char *name);
196EAPI void etrophy_level_free(Etrophy_Level *level);
197EAPI const char *etrophy_level_name_get(const Etrophy_Level *level);
198EAPI const Eina_List *etrophy_level_scores_list_get(const Etrophy_Level *level);
199EAPI void etrophy_level_scores_list_clear(Etrophy_Level *level);
200EAPI void etrophy_gamescore_level_add(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
201EAPI void etrophy_gamescore_level_del(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
202EAPI Etrophy_Level *etrophy_gamescore_level_get(Etrophy_Gamescore *gamescore, const char *name);
203EAPI const Eina_List *etrophy_gamescore_levels_list_get(const Etrophy_Gamescore *gamescore);
204EAPI void etrophy_gamescore_levels_list_clear(Etrophy_Gamescore *gamescore);
205EAPI void etrophy_level_score_add(Etrophy_Level *level, Etrophy_Score *escore);
206EAPI void etrophy_level_score_del(Etrophy_Level *level, Etrophy_Score *escore);
207EAPI Etrophy_Score *etrophy_gamescore_level_score_add(Etrophy_Gamescore *gamescore, const char *level_name, const char *player_name, int score);
208EAPI Etrophy_Score *etrophy_score_new(const char *player_name, int score);
209EAPI void etrophy_score_free(Etrophy_Score *escore);
210EAPI const char *etrophy_score_player_name_get(const Etrophy_Score *escore);
211EAPI int etrophy_score_score_get(const Etrophy_Score *escore);
212EAPI unsigned int etrophy_score_date_get(const Etrophy_Score *escore);
213EAPI int etrophy_gamescore_level_hi_score_get(const Etrophy_Gamescore *gamescore, const char *level_name);
214EAPI int etrophy_gamescore_level_low_score_get(const Etrophy_Gamescore *gamescore, const char *level_name);
215
216/**
217 * @}
218 */
219
220/**
221 * @brief Functions to manipulate player's trophies.
222 * @defgroup Trophy Trophy
223 *
224 * @{
225 *
226 * A trophy represents a task a user achieved. It can be visible or hidden,
227 * and starts locked and only unlocked after the player reaches
228 * its goal. For that, a trophy consists of a name, description, visibility
229 * the goal, and current points on this task.
230 *
231 * A new trophy can be created with @ref etrophy_trophy_new() and should
232 * be added to the gamescore with @ref etrophy_gamescore_trophy_add().
233 * It is handled by @ref Etrophy_Trophy.
234 *
235 * It's counter can be directly set with @ref etrophy_trophy_counter_set()
236 * or incremented using @ref etrophy_trophy_counter_increment(). Current
237 * points and goal can be get using @ref etrophy_trophy_goal_get().
238 * @ref etrophy_trophy_earned_get() returns if the trophy was achieved
239 * or not.
240 *
241 * Other attributes can be read with:
242 * @li @ref etrophy_trophy_name_get()
243 * @li @ref etrophy_trophy_description_get()
244 * @li @ref etrophy_trophy_visibility_get()
245 * @li @ref etrophy_trophy_date_get()
246 *
247 * The trophies list can be get with
248 * @ref etrophy_gamescore_trophies_list_get() and cleared using
249 * @ref etrophy_gamescore_trophies_list_clear().
250 */
251
38typedef struct _Etrophy_Trophy Etrophy_Trophy; 252typedef struct _Etrophy_Trophy Etrophy_Trophy;
39typedef enum 253typedef enum
40{ 254{
@@ -43,6 +257,81 @@ typedef enum
43 ETROPHY_TROPHY_STATE_LAST_VALUE 257 ETROPHY_TROPHY_STATE_LAST_VALUE
44} Etrophy_Trophy_Visibility; 258} Etrophy_Trophy_Visibility;
45 259
260EAPI Etrophy_Trophy *etrophy_trophy_new(const char *name, const char *description, Etrophy_Trophy_Visibility visibility, unsigned int goal);
261EAPI void etrophy_trophy_free(Etrophy_Trophy *trophy);
262EAPI const char *etrophy_trophy_name_get(const Etrophy_Trophy *trophy);
263EAPI const char *etrophy_trophy_description_get(const Etrophy_Trophy *trophy);
264EAPI Etrophy_Trophy_Visibility etrophy_trophy_visibility_get(const Etrophy_Trophy *trophy);
265EAPI void etrophy_trophy_goal_get(const Etrophy_Trophy *trophy, unsigned int *goal, unsigned int *counter);
266EAPI void etrophy_trophy_counter_set(Etrophy_Trophy *trophy, unsigned int value);
267EAPI void etrophy_trophy_counter_increment(Etrophy_Trophy *trophy, unsigned int value);
268EAPI Eina_Bool etrophy_trophy_earned_get(const Etrophy_Trophy *trophy);
269EAPI unsigned int etrophy_trophy_date_get(const Etrophy_Trophy *trophy);
270
271EAPI void etrophy_gamescore_trophy_add(Etrophy_Gamescore *gamescore, Etrophy_Trophy *trophy);
272EAPI void etrophy_gamescore_trophy_del(Etrophy_Gamescore *gamescore, Etrophy_Trophy *trophy);
273EAPI Etrophy_Trophy *etrophy_gamescore_trophy_get(Etrophy_Gamescore *gamescore, const char *name);
274EAPI const Eina_List *etrophy_gamescore_trophies_list_get(const Etrophy_Gamescore *gamescore);
275EAPI void etrophy_gamescore_trophies_list_clear(Etrophy_Gamescore *gamescore);
276
277/**
278 * @}
279 */
280
281/**
282 * @brief Functions to handle locks.
283 * @defgroup Lock Lock
284 *
285 * @{
286 *
287 * A lock is a very simple and generic concept, generally used for games
288 * regarding stuff that should be accesible only after the user does a
289 * specific action. For example: a gun is locked until the player kills the
290 * first boss; or the "hard" level is unlocked only when the "easy" one is
291 * concluded with a high score.
292 *
293 * It consists of a name, date of update, and its state: locked or unlocked.
294 *
295 * It is handled by @ref Etrophy_Lock and should be created with
296 * @ref etrophy_lock_new() and added to the gamescore using
297 * @ref etrophy_gamescore_lock_add().
298 *
299 * A list of locks can be get with @ref etrophy_gamescore_locks_list_get()
300 * and cleared with @ref etrophy_gamescore_locks_list_clear().
301 *
302 * The state should be changed using @ref etrophy_lock_state_set().
303 *
304 * Example of usage of locks:
305 * @code
306 * Etrophy_Gamescore *load_function(Eina_List *locks_names)
307 * {
308 * Etrophy_Gamescore *gamescore;
309 * gamescore = etrophy_gamescore_load("gamename");
310 * if (!gamescore)
311 * {
312 * const char *name;
313 * Eina_List *l;
314 * gamescore = etrophy_gamescore_new("gamename");
315 * EINA_LIST_FOREACH(locks_names, l, name)
316 * {
317 * Etrophy_Lock *etrophy_lock;
318 * etrophy_lock = etrophy_lock_new(name,
319 * ETROPHY_LOCK_STATE_LOCKED);
320 * etrophy_gamescore_lock_add(gamescore, etrophy_lock);
321 * }
322 * }
323 * return gamescore;
324 * }
325 * void unlock_function(Etrophy_Gamescore *gamescore, const char *name)
326 * {
327 * Etrophy_Lock *lock;
328 * lock = etrophy_gamescore_lock_get(gamescore, name);
329 * etrophy_lock_state_set(lock, ETROPHY_LOCK_STATE_UNLOCKED);
330 * }
331 * @endcode
332 *
333 */
334
46typedef struct _Etrophy_Lock Etrophy_Lock; 335typedef struct _Etrophy_Lock Etrophy_Lock;
47typedef enum 336typedef enum
48{ 337{
@@ -51,90 +340,46 @@ typedef enum
51 ETROPHY_LOCK_STATE_LAST_VALUE 340 ETROPHY_LOCK_STATE_LAST_VALUE
52} Etrophy_Lock_State; 341} Etrophy_Lock_State;
53 342
54typedef struct _Etrophy_Score Etrophy_Score; 343EAPI Etrophy_Lock *etrophy_lock_new(const char *name, Etrophy_Lock_State state);
55typedef struct _Etrophy_Level Etrophy_Level; 344EAPI void etrophy_lock_free(Etrophy_Lock *lock);
56typedef struct _Etrophy_Gamescore Etrophy_Gamescore; 345EAPI const char *etrophy_lock_name_get(const Etrophy_Lock *lock);
346EAPI void etrophy_lock_state_set(Etrophy_Lock *lock, Etrophy_Lock_State state);
347EAPI Etrophy_Lock_State etrophy_lock_state_get(const Etrophy_Lock *lock);
348EAPI unsigned int etrophy_lock_date_get(const Etrophy_Lock *lock);
349EAPI void etrophy_gamescore_lock_add(Etrophy_Gamescore *gamescore, Etrophy_Lock *lock);
350EAPI void etrophy_gamescore_lock_del(Etrophy_Gamescore *gamescore, Etrophy_Lock *lock);
351EAPI Etrophy_Lock *etrophy_gamescore_lock_get(Etrophy_Gamescore *gamescore, const char *name);
352EAPI const Eina_List *etrophy_gamescore_locks_list_get(const Etrophy_Gamescore *gamescore);
353EAPI void etrophy_gamescore_locks_list_clear(Etrophy_Gamescore *gamescore);
57 354
58/* Etrophy_Trophy */ 355/**
59EAPI Etrophy_Trophy *etrophy_trophy_new(const char *name, const char *description, Etrophy_Trophy_Visibility visibility, unsigned int goal); 356 * @}
60EAPI void etrophy_trophy_free(Etrophy_Trophy *trophy); 357 */
61 358
62EAPI const char *etrophy_trophy_name_get(const Etrophy_Trophy *trophy); 359/**
63EAPI const char *etrophy_trophy_description_get(const Etrophy_Trophy *trophy); 360 * @brief Functions that return objects to display gamescore data visually.
64EAPI Etrophy_Trophy_Visibility etrophy_trophy_visibility_get(const Etrophy_Trophy *trophy); 361 * @defgroup View View
65EAPI void etrophy_trophy_goal_get(const Etrophy_Trophy *trophy, unsigned int *goal, unsigned int *counter); 362 *
66EAPI void etrophy_trophy_counter_set(Etrophy_Trophy *trophy, unsigned int value); 363 * @{
67EAPI void etrophy_trophy_counter_increment(Etrophy_Trophy *trophy, unsigned int value); 364 *
68EAPI Eina_Bool etrophy_trophy_earned_get(const Etrophy_Trophy *trophy); 365 * Beyond data management, Etrophy provides some views, built with Elementary.
69EAPI unsigned int etrophy_trophy_date_get(const Etrophy_Trophy *trophy); 366 * They consist of Elm Layouts with widgets used to display gamescore data
70 367 * to the application user.
71/* Etrophy_Lock */ 368 *
72EAPI Etrophy_Lock *etrophy_lock_new(const char *name, Etrophy_Lock_State state); 369 * It provides views for:
73EAPI void etrophy_lock_free(Etrophy_Lock *lock); 370 * @li scores with @ref etrophy_score_layout_add()
74 371 * @li trophies with @ref etrophy_trophies_layout_add()
75EAPI const char *etrophy_lock_name_get(const Etrophy_Lock *lock); 372 * @li locks with @ref etrophy_locks_layout_add()
76EAPI void etrophy_lock_state_set(Etrophy_Lock *lock, Etrophy_Lock_State state); 373 *
77EAPI Etrophy_Lock_State etrophy_lock_state_get(const Etrophy_Lock *lock); 374 */
78EAPI unsigned int etrophy_lock_date_get(const Etrophy_Lock *lock); 375
79 376EAPI Evas_Object *etrophy_score_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
80/* Etrophy_Score */ 377EAPI Evas_Object *etrophy_trophies_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
81EAPI Etrophy_Score *etrophy_score_new(const char *player_name, int score); 378EAPI Evas_Object *etrophy_locks_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
82EAPI void etrophy_score_free(Etrophy_Score *escore); 379
83 380/**
84EAPI const char *etrophy_score_player_name_get(const Etrophy_Score *escore); 381 * @}
85EAPI int etrophy_score_score_get(const Etrophy_Score *escore); 382 */
86EAPI unsigned int etrophy_score_date_get(const Etrophy_Score *escore);
87
88/* Etrophy_Level */
89EAPI Etrophy_Level *etrophy_level_new(const char *name);
90EAPI void etrophy_level_free(Etrophy_Level *level);
91
92EAPI const char *etrophy_level_name_get(const Etrophy_Level *level);
93EAPI void etrophy_level_score_add(Etrophy_Level *level, Etrophy_Score *escore);
94EAPI void etrophy_level_score_del(Etrophy_Level *level, Etrophy_Score *escore);
95EAPI const Eina_List *etrophy_level_scores_list_get(const Etrophy_Level *level);
96EAPI void etrophy_level_scores_list_clear(Etrophy_Level *level);
97
98/* Etrophy_Gamescore */
99EAPI Etrophy_Gamescore *etrophy_gamescore_new(const char *gamename);
100EAPI void etrophy_gamescore_free(Etrophy_Gamescore *gamescore);
101EAPI Eet_Data_Descriptor *etrophy_gamescore_edd_get(void);
102EAPI Etrophy_Gamescore *etrophy_gamescore_path_load(const char *filename);
103EAPI Etrophy_Gamescore *etrophy_gamescore_load(const char *gamename);
104EAPI Eina_Bool etrophy_gamescore_save(Etrophy_Gamescore *gamescore, const char *filename);
105
106EAPI void etrophy_gamescore_level_add(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
107EAPI void etrophy_gamescore_level_del(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
108EAPI Etrophy_Level *etrophy_gamescore_level_get(Etrophy_Gamescore *gamescore, const char *name);
109EAPI const Eina_List *etrophy_gamescore_levels_list_get(const Etrophy_Gamescore *gamescore);
110EAPI void etrophy_gamescore_levels_list_clear(Etrophy_Gamescore *gamescore);
111
112EAPI void etrophy_gamescore_trophy_add(Etrophy_Gamescore *gamescore, Etrophy_Trophy *trophy);
113EAPI void etrophy_gamescore_trophy_del(Etrophy_Gamescore *gamescore, Etrophy_Trophy *trophy);
114EAPI Etrophy_Trophy *etrophy_gamescore_trophy_get(Etrophy_Gamescore *gamescore, const char *name);
115EAPI const Eina_List *etrophy_gamescore_trophies_list_get(const Etrophy_Gamescore *gamescore);
116EAPI void etrophy_gamescore_trophies_list_clear(Etrophy_Gamescore *gamescore);
117
118EAPI void etrophy_gamescore_lock_add(Etrophy_Gamescore *gamescore, Etrophy_Lock *lock);
119EAPI void etrophy_gamescore_lock_del(Etrophy_Gamescore *gamescore, Etrophy_Lock *lock);
120EAPI Etrophy_Lock *etrophy_gamescore_lock_get(Etrophy_Gamescore *gamescore, const char *name);
121EAPI const Eina_List *etrophy_gamescore_locks_list_get(const Etrophy_Gamescore *gamescore);
122EAPI void etrophy_gamescore_locks_list_clear(Etrophy_Gamescore *gamescore);
123
124EAPI void etrophy_gamescore_clear(Etrophy_Gamescore *gamescore);
125
126EAPI int etrophy_gamescore_level_hi_score_get(const Etrophy_Gamescore *gamescore, const char *level_name);
127EAPI int etrophy_gamescore_level_low_score_get(const Etrophy_Gamescore *gamescore, const char *level_name);
128EAPI Etrophy_Score *etrophy_gamescore_level_score_add(Etrophy_Gamescore *gamescore, const char *level_name, const char *player_name, int score);
129
130/* Layouts */
131EAPI Evas_Object *etrophy_score_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
132EAPI Evas_Object *etrophy_trophies_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
133EAPI Evas_Object *etrophy_locks_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
134
135/* Global initializer / shutdown functions */
136EAPI int etrophy_init(void);
137EAPI int etrophy_shutdown(void);
138 383
139#ifdef __cplusplus 384#ifdef __cplusplus
140} 385}