summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBruno Dilly <bdilly@profusion.mobi>2012-12-14 07:08:03 +0000
committerBruno Dilly <bdilly@profusion.mobi>2012-12-14 07:08:03 +0000
commit8d1f285a5ad7243dfa6511c7b1796ad1c68e494b (patch)
tree176aef35a843bd685b61cf650d0ef34d848e8956
parentab0bc090456d3760fbeea68515f5683ff2749d16 (diff)
etrophy: document general functions and types
Document things enough to somebody interested get started: * all types and enumerations. * all functions of groups Init, Gamescore and View SVN revision: 80916
-rw-r--r--TODO1
-rw-r--r--src/lib/Etrophy.h308
2 files changed, 297 insertions, 12 deletions
diff --git a/TODO b/TODO
index cda9810..88ed3bd 100644
--- a/TODO
+++ b/TODO
@@ -3,3 +3,4 @@
3* add test for GUI elements 3* add test for GUI elements
4* add version to gamescore 4* add version to gamescore
5* add remote backend 5* add remote backend
6* document trophy, lock and score functions
diff --git a/src/lib/Etrophy.h b/src/lib/Etrophy.h
index 9ce0025..1c0762a 100644
--- a/src/lib/Etrophy.h
+++ b/src/lib/Etrophy.h
@@ -93,7 +93,32 @@ extern "C" {
93 * 93 *
94 */ 94 */
95 95
96/**
97 * Initialize Etrophy.
98 *
99 * Initializes Etrophy, its dependencies and modules. Should be the first
100 * function of Etrophy to be called.
101 *
102 * @return The init counter value.
103 *
104 * @see etrophy_shutdown().
105 *
106 * @ingroup Init
107 */
96EAPI int etrophy_init(void); 108EAPI int etrophy_init(void);
109
110/**
111 * Shutdown Etrophy
112 *
113 * Shutdown Etrophy. If init count reaches 0, all the internal structures will
114 * be freed. Any Etrophy library call after this point will leads to an error.
115 *
116 * @return Etrophy's init counter value.
117 *
118 * @see etrophy_init().
119 *
120 * @ingroup Init
121 */
97EAPI int etrophy_shutdown(void); 122EAPI int etrophy_shutdown(void);
98 123
99/** 124/**
@@ -134,17 +159,134 @@ EAPI int etrophy_shutdown(void);
134 * 159 *
135 */ 160 */
136 161
162/**
163 * @typedef Etrophy_Gamescore
164 *
165 * Gamescore handle, mandatory for Etrophy's usage. Each application
166 * need to have one.
167 *
168 * Created with @ref etrophy_gamescore_new() and deleted with
169 * @ref etrophy_gamescore_free().
170 *
171 * @ingroup Gamescore
172 */
137typedef struct _Etrophy_Gamescore Etrophy_Gamescore; 173typedef struct _Etrophy_Gamescore Etrophy_Gamescore;
138 174
139EAPI void etrophy_gamescore_clear(Etrophy_Gamescore *gamescore); 175/**
176 * @brief
177 * Create a new gamescore.
178 *
179 * A gamescore should be used by application. It will be used to manage
180 * trophies, locks and players' scores.
181 *
182 * It must to be saved after edited, using @ref etrophy_gamescore_save().
183 *
184 * @param gamename Name of the gamescore to be used to load in later
185 * uses.
186 * @return The gamescore created or @c NULL on error.
187 *
188 * @see etrophy_gamescore_free()
189 * @see etrophy_gamescore_load()
190 *
191 * @ingroup Gamescore
192 */
140EAPI Etrophy_Gamescore *etrophy_gamescore_new(const char *gamename); 193EAPI Etrophy_Gamescore *etrophy_gamescore_new(const char *gamename);
194
195/**
196 * @brief
197 * Free a previouly created gamescore.
198 *
199 * @param gamescore Gamescore handle.
200 *
201 * @see etrophy_gamescore_new()
202 * @see etrophy_gamescore_load()
203 *
204 * @ingroup Gamescore
205 */
141EAPI void etrophy_gamescore_free(Etrophy_Gamescore *gamescore); 206EAPI void etrophy_gamescore_free(Etrophy_Gamescore *gamescore);
142EAPI Eet_Data_Descriptor *etrophy_gamescore_edd_get(void); 207
143EAPI Etrophy_Gamescore *etrophy_gamescore_path_load(const char *filename); 208/**
209 * @brief
210 * Load a gamescore given a name.
211 *
212 * An alternative way of loading it is using
213 * @ref etrophy_gamescore_path_load(). It will be necessary if the gamescore
214 * was previoulsy saved in a non standard Etrophy directory.
215 *
216 * @param gamename Name used when gamescore was created.
217 * @return The gamescore or @c NULL on error.
218 *
219 * @see etrophy_gamescore_new()
220 * @see etrophy_gamescore_save()
221 *
222 * @ingroup Gamescore
223 */
144EAPI Etrophy_Gamescore *etrophy_gamescore_load(const char *gamename); 224EAPI Etrophy_Gamescore *etrophy_gamescore_load(const char *gamename);
225
226/**
227 * @brief
228 * Load a gamescore from a give path.
229 *
230 * An alternative way of loading it is using @ref etrophy_gamescore_load(),
231 * and the provided gamescore name will be searched on default Etrophy
232 * directories.
233 *
234 * @param filename Full path to the file.
235 * @return The gamescore or @c NULL on error.
236 *
237 * @ingroup Gamescore
238 */
239EAPI Etrophy_Gamescore *etrophy_gamescore_path_load(const char *filename);
240
241/**
242 * @brief
243 * Save a gamescore.
244 *
245 * There are two ways of loading / saving gamescores. Just using gamescore's
246 * name, and the directory will be defined by Etrophy, or passing
247 * the full path to the file to be written.
248 *
249 * The default directory can be set with environment variable @c ETROPHY_PATH
250 * or it will try to find user's home. Then the file will be stored inside
251 * .etrophy sub directory, with the name of gamescore and extension ".eet".
252 *
253 * @param filename Full path to the file. If @c NULL, it will be saved on
254 * default Etrophy directories.
255 * @param gamescore Gamescore handle.
256 * @return @c EINA_TRUE if the gamescore was properly saved @c EINA_FALSE
257 * on error.
258 *
259 * @ingroup Gamescore
260 */
145EAPI Eina_Bool etrophy_gamescore_save(Etrophy_Gamescore *gamescore, const char *filename); 261EAPI Eina_Bool etrophy_gamescore_save(Etrophy_Gamescore *gamescore, const char *filename);
146 262
147/** 263/**
264 * @brief
265 * Return gamescore Eet data descriptor.
266 *
267 * Useful when you already have an eet file for your application and wants
268 * to merge gamescore on it.
269 *
270 * @return Eet data descriptor.
271 *
272 * @ingroup Gamescore
273 */
274EAPI Eet_Data_Descriptor *etrophy_gamescore_edd_get(void);
275
276/**
277 * @brief
278 * Clear all the data of the gamescore.
279 *
280 * It will clear trophies, locks, players' scores.
281 * Everything will be deleted.
282 *
283 * @param gamescore Gamescore handle.
284 *
285 * @ingroup Gamescore
286 */
287EAPI void etrophy_gamescore_clear(Etrophy_Gamescore *gamescore);
288
289/**
148 * @} 290 * @}
149 */ 291 */
150 292
@@ -189,27 +331,55 @@ EAPI Eina_Bool etrophy_gamescore_save(Etrophy_Gamescore *gamescore, const char *
189 * 331 *
190 */ 332 */
191 333
334/**
335 * @typedef Etrophy_Level
336 *
337 * Level handle, used to store all the players' scores in the level.
338 *
339 * Created with @ref etrophy_level_new(), added to gamescore using
340 * @ref etrophy_gamescore_level_add() and freed with
341 * @ref etrophy_level_free().
342 *
343 * @ingroup Score
344 */
192typedef struct _Etrophy_Level Etrophy_Level; 345typedef struct _Etrophy_Level Etrophy_Level;
346
347/**
348 * @typedef Etrophy_Score
349 *
350 * Score handle, save the player's scores, name, and date.
351 *
352 * Created with @ref etrophy_score_new(), added to the level using
353 * @ref etrophy_level_score_add() and freed with
354 * @ref etrophy_score_free().
355 *
356 * @ingroup Score
357 */
193typedef struct _Etrophy_Score Etrophy_Score; 358typedef struct _Etrophy_Score Etrophy_Score;
194 359
195EAPI Etrophy_Level *etrophy_level_new(const char *name); 360EAPI Etrophy_Level *etrophy_level_new(const char *name);
196EAPI void etrophy_level_free(Etrophy_Level *level); 361EAPI void etrophy_level_free(Etrophy_Level *level);
197EAPI const char *etrophy_level_name_get(const Etrophy_Level *level); 362EAPI const char *etrophy_level_name_get(const Etrophy_Level *level);
363
198EAPI const Eina_List *etrophy_level_scores_list_get(const Etrophy_Level *level); 364EAPI const Eina_List *etrophy_level_scores_list_get(const Etrophy_Level *level);
199EAPI void etrophy_level_scores_list_clear(Etrophy_Level *level); 365EAPI void etrophy_level_scores_list_clear(Etrophy_Level *level);
366
200EAPI void etrophy_gamescore_level_add(Etrophy_Gamescore *gamescore, Etrophy_Level *level); 367EAPI void etrophy_gamescore_level_add(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
201EAPI void etrophy_gamescore_level_del(Etrophy_Gamescore *gamescore, Etrophy_Level *level); 368EAPI void etrophy_gamescore_level_del(Etrophy_Gamescore *gamescore, Etrophy_Level *level);
202EAPI Etrophy_Level *etrophy_gamescore_level_get(Etrophy_Gamescore *gamescore, const char *name); 369EAPI 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); 370EAPI const Eina_List *etrophy_gamescore_levels_list_get(const Etrophy_Gamescore *gamescore);
204EAPI void etrophy_gamescore_levels_list_clear(Etrophy_Gamescore *gamescore); 371EAPI void etrophy_gamescore_levels_list_clear(Etrophy_Gamescore *gamescore);
372
205EAPI void etrophy_level_score_add(Etrophy_Level *level, Etrophy_Score *escore); 373EAPI void etrophy_level_score_add(Etrophy_Level *level, Etrophy_Score *escore);
206EAPI void etrophy_level_score_del(Etrophy_Level *level, Etrophy_Score *escore); 374EAPI 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); 375
208EAPI Etrophy_Score *etrophy_score_new(const char *player_name, int score); 376EAPI Etrophy_Score *etrophy_score_new(const char *player_name, int score);
209EAPI void etrophy_score_free(Etrophy_Score *escore); 377EAPI void etrophy_score_free(Etrophy_Score *escore);
210EAPI const char *etrophy_score_player_name_get(const Etrophy_Score *escore); 378EAPI const char *etrophy_score_player_name_get(const Etrophy_Score *escore);
211EAPI int etrophy_score_score_get(const Etrophy_Score *escore); 379EAPI int etrophy_score_score_get(const Etrophy_Score *escore);
212EAPI unsigned int etrophy_score_date_get(const Etrophy_Score *escore); 380EAPI unsigned int etrophy_score_date_get(const Etrophy_Score *escore);
381
382EAPI Etrophy_Score *etrophy_gamescore_level_score_add(Etrophy_Gamescore *gamescore, const char *level_name, const char *player_name, int score);
213EAPI int etrophy_gamescore_level_hi_score_get(const Etrophy_Gamescore *gamescore, const char *level_name); 383EAPI 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); 384EAPI int etrophy_gamescore_level_low_score_get(const Etrophy_Gamescore *gamescore, const char *level_name);
215 385
@@ -249,12 +419,37 @@ EAPI int etrophy_gamescore_level_low_score_get(const Etrophy_Gamescore *gamescor
249 * @ref etrophy_gamescore_trophies_list_clear(). 419 * @ref etrophy_gamescore_trophies_list_clear().
250 */ 420 */
251 421
422/**
423 * @typedef Etrophy_Trophy
424 *
425 * Trophy handle, keeps score per tasks and goals. It has name, description
426 * and visibility.
427 *
428 * Created with @ref etrophy_trophy_new(), added to gamescore using
429 * @ref ephysics_gamescore_trophy_add() and freed with
430 * @ref etrophy_level_free().
431 *
432 * @ingroup Trophy
433 */
252typedef struct _Etrophy_Trophy Etrophy_Trophy; 434typedef struct _Etrophy_Trophy Etrophy_Trophy;
253typedef enum 435
436/**
437 * @enum _Etrophy_Trophy_Visibility
438 * @typedef Etrophy_Trophy_Visibility
439 *
440 * State of a lock: locked or unlocked. Usually locks starts locked and
441 * after the player achieves a task it is unlocked.
442 *
443 * @see etrophy_trophy_new()
444 * @see etrophy_trophy_visibility_get()
445 *
446 * @ingroup Trophy
447 */
448typedef enum _Etrophy_Trophy_Visibility
254{ 449{
255 ETROPHY_TROPHY_STATE_HIDDEN = 0, 450 ETROPHY_TROPHY_STATE_HIDDEN = 0, /**< Player shouldn't know about its existence */
256 ETROPHY_TROPHY_STATE_VISIBLE, 451 ETROPHY_TROPHY_STATE_VISIBLE, /**< Player can know about its existence */
257 ETROPHY_TROPHY_STATE_LAST_VALUE 452 ETROPHY_TROPHY_STATE_LAST_VALUE /**< kept as sentinel */
258} Etrophy_Trophy_Visibility; 453} Etrophy_Trophy_Visibility;
259 454
260EAPI Etrophy_Trophy *etrophy_trophy_new(const char *name, const char *description, Etrophy_Trophy_Visibility visibility, unsigned int goal); 455EAPI Etrophy_Trophy *etrophy_trophy_new(const char *name, const char *description, Etrophy_Trophy_Visibility visibility, unsigned int goal);
@@ -332,12 +527,37 @@ EAPI void etrophy_gamescore_trophies_list_clear(Etrophy_Gamescore *gamescore);
332 * 527 *
333 */ 528 */
334 529
530/**
531 * @typedef Etrophy_Lock
532 *
533 * Lock handle, has name, lock state and date of update.
534 *
535 * Created with @ref etrophy_lock_new(), added to gamescore using
536 * @ref ephysics_gamescore_lock_add() and freed with
537 * @ref etrophy_lock_free().
538 *
539 * @ingroup Lock
540 */
335typedef struct _Etrophy_Lock Etrophy_Lock; 541typedef struct _Etrophy_Lock Etrophy_Lock;
336typedef enum 542
543/**
544 * @enum _Etrophy_Lock_State
545 * @typedef Etrophy_Lock_State
546 *
547 * State of a lock: locked or unlocked. Usually locks starts locked and
548 * after the player achieves a task it is unlocked.
549 *
550 * @see etrophy_lock_new()
551 * @see etrophy_lock_state_set()
552 * @see etrophy_lock_state_get()
553 *
554 * @ingroup Lock
555 */
556typedef enum _Etrophy_Lock_State
337{ 557{
338 ETROPHY_LOCK_STATE_LOCKED = 0, 558 ETROPHY_LOCK_STATE_LOCKED = 0, /**< Player doesn't have access to it yet */
339 ETROPHY_LOCK_STATE_UNLOCKED, 559 ETROPHY_LOCK_STATE_UNLOCKED, /**< Player already has access to it */
340 ETROPHY_LOCK_STATE_LAST_VALUE 560 ETROPHY_LOCK_STATE_LAST_VALUE /**< kept as sentinel, not really a state */
341} Etrophy_Lock_State; 561} Etrophy_Lock_State;
342 562
343EAPI Etrophy_Lock *etrophy_lock_new(const char *name, Etrophy_Lock_State state); 563EAPI Etrophy_Lock *etrophy_lock_new(const char *name, Etrophy_Lock_State state);
@@ -373,8 +593,72 @@ EAPI void etrophy_gamescore_locks_list_clear(Etrophy_Gamescore *gamescore);
373 * 593 *
374 */ 594 */
375 595
596/**
597 * @brief
598 * Create a view and populate it with scores data.
599 *
600 * Create a Elm Layout with a spinner to select the level and a genlist
601 * displaying each score. The returned object can be placed anywhere in
602 * the application view (layout, boxes, etc).
603 *
604 * Example:
605 * @code
606 * static void
607 * _scores_show_cb(void *data, Evas_Object *obj __UNUSED__,
608 * void *event_info __UNUSED__)
609 * {
610 * Evas_Object *popup, *bt, *leaderboard;
611 * Game *game = data;
612 *
613 * popup = elm_popup_add(game->win);
614 * elm_object_part_text_set(popup, "title,text", "Leaderboard");
615 *
616 * bt = elm_button_add(popup);
617 * elm_object_text_set(bt, "OK");
618 * elm_object_part_content_set(popup, "button1", bt);
619 *
620 * leaderboard = etrophy_score_layout_add(popup, game->gamescore);
621 * elm_object_content_set(popup, leaderboard);
622 * evas_object_smart_callback_add(bt, "clicked", _scores_hide_cb, popup);
623 *
624 * evas_object_show(popup);
625 * }
626 * @endcode
627 *
628 * @param parent Evas object to be used as parent.
629 * @param gamescore Gamescore handle.
630 * @return The view or @c NULL on error.
631 *
632 * @ingroup View
633 */
376EAPI Evas_Object *etrophy_score_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore); 634EAPI Evas_Object *etrophy_score_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
635
636/**
637 * @brief
638 * Create a view and populate it with trophies data.
639 *
640 * NOT IMPLEMENTED.
641 *
642 * @param parent Evas object to be used as parent.
643 * @param gamescore Gamescore handle.
644 * @return The view or @c NULL on error.
645 *
646 * @ingroup View
647 */
377EAPI Evas_Object *etrophy_trophies_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore); 648EAPI Evas_Object *etrophy_trophies_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
649
650/**
651 * @brief
652 * Create a view and populate it with locks data.
653 *
654 * NOT IMPLEMENTED.
655 *
656 * @param parent Evas object to be used as parent.
657 * @param gamescore Gamescore handle.
658 * @return The view or @c NULL on error.
659 *
660 * @ingroup View
661 */
378EAPI Evas_Object *etrophy_locks_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore); 662EAPI Evas_Object *etrophy_locks_layout_add(Evas_Object *parent, Etrophy_Gamescore *gamescore);
379 663
380/** 664/**