Eobj: Added event callbacks for Object free/del.
[profile/ivi/eobj.git] / lib / Eobj.h
1 #ifndef EOBJ_H
2 #define EOBJ_H
3
4 #include <stdarg.h>
5 #include <Eina.h>
6
7 /**
8  * @defgroup Eobj Eobj Generic Object System
9  *
10  * The Eobj generic object system. It was designed to be the base object
11  * system for the EFL.
12  *
13  * @{
14  */
15
16 /**
17  * @def EOBJ_TYPECHECK(type, x)
18  *
19  * Checks x is castable to type "type" and casts it to it.
20  * @param type The C type to check against.
21  * @param x the variable to test and cast.
22  */
23 #define EOBJ_TYPECHECK(type, x) \
24    ({ \
25     type __x; \
26     __x = x; \
27     (void) __x; \
28     (type) x; \
29     })
30
31 /**
32  * @typedef Eobj
33  * The basic Object type.
34  */
35 typedef struct _Eobj Eobj;
36 /**
37  * @typedef Eobj_Op
38  * The Eobj operation type id.
39  */
40 typedef unsigned int Eobj_Op;
41
42 /**
43  * @def EOBJ_NOOP
44  * A special Eobj_Op meaning "No operation".
45  */
46 #define EOBJ_NOOP ((Eobj_Op) 0)
47
48 /**
49  * @typedef eobj_op_func_type
50  * The type of the Op functions. This is the type of the functions used by
51  * Eobj.
52  */
53 typedef void (*eobj_op_func_type)(Eobj *, void *class_data, va_list *list);
54
55 /**
56  * @addtogroup Eobj_Events Eobj's Event Handling
57  * @{
58  */
59
60 /**
61  * @struct _Eobj_Event_Description
62  * This struct holds the description of a specific event.
63  */
64 struct _Eobj_Event_Description
65 {
66    const char *name; /**< name of the event. */
67    const char *type; /**< describes the data passed in event_info */
68    const char *doc; /**< Explanation about the event. */
69 };
70
71 /**
72  * @typedef Eobj_Event_Description
73  * A convenience typedef for #_Eobj_Event_Description
74  */
75 typedef struct _Eobj_Event_Description Eobj_Event_Description;
76
77 /**
78  * @def EOBJ_EVENT_DESCRIPTION(name, type, doc)
79  * An helper macro to help populating #Eobj_Event_Description
80  * @param name The name of the event.
81  * @param type The type string of the event.
82  * @param doc Additional doc for the event.
83  * @see Eobj_Event_Description
84  */
85 #define EOBJ_EVENT_DESCRIPTION(name, type, doc) { name, type, doc }
86
87 /**
88  * @}
89  */
90
91 /**
92  * @addtogroup Eobj_Class Eobj Class
93  * @{
94  */
95
96 /**
97  * @typedef Eobj_Class
98  * The basic Object class type.
99  */
100 typedef struct _Eobj_Class Eobj_Class;
101
102 /**
103  * An enum representing the possible types of an Eobj class.
104  */
105 enum _Eobj_Class_Type
106 {
107    EOBJ_CLASS_TYPE_REGULAR = 0, /**< Regular class. */
108    EOBJ_CLASS_TYPE_REGULAR_NO_INSTANT, /**< Regular non instant-able class. */
109    EOBJ_CLASS_TYPE_INTERFACE, /**< Interface */
110    EOBJ_CLASS_TYPE_MIXIN /**< Mixin */
111 };
112
113 /**
114  * @typedef Eobj_Class_Type
115  * A convenience typedef for #_Eobj_Class_Type.
116  */
117 typedef enum _Eobj_Class_Type Eobj_Class_Type;
118
119 /**
120  * @struct _Eobj_Op_Func_Description
121  * Used to associate an Op with a func.
122  * @see eobj_class_funcs_set
123  */
124 struct _Eobj_Op_Func_Description
125 {
126    Eobj_Op op; /**< The op */
127    eobj_op_func_type func; /**< The function to call for the op. */
128 };
129
130 /**
131  * @typedef Eobj_Op_Func_Description
132  * A convenience typedef for #_Eobj_Op_Func_Description
133  */
134 typedef struct _Eobj_Op_Func_Description Eobj_Op_Func_Description;
135
136 /**
137  * @def EOBJ_OP_FUNC(op, func)
138  * A convenience macro to be used when populating the #Eobj_Op_Func_Description
139  * array.
140  */
141 #define EOBJ_OP_FUNC(op, func) { op, func }
142 /**
143  * @def EOBJ_OP_FUNC_SENTINEL
144  * A convenience macro to be used when populating the #Eobj_Op_Func_Description
145  * array. It must appear at the end of the ARRAY.
146  */
147 #define EOBJ_OP_FUNC_SENTINEL { 0, NULL }
148
149 /**
150  * @struct _Eobj_Op_Description
151  * This struct holds the description of a specific op.
152  */
153 struct _Eobj_Op_Description
154 {
155    Eobj_Op sub_op; /**< The sub_id of the op in it's class. */
156    const char *name; /**< The name of the op. */
157    const char *type; /**< descripbes the Op's function signature. */
158    const char *doc; /**< Explanation about the Op. */
159 };
160
161 /**
162  * @typedef Eobj_Op_Description
163  * A convenience typedef for #_Eobj_Op_Description
164  */
165 typedef struct _Eobj_Op_Description Eobj_Op_Description;
166
167 /**
168  * @struct _Eobj_Class_Description
169  * This struct holds the description of a class.
170  * This description should be passed to eobj_class_new.
171  * Please use the #EOBJ_CLASS_DESCRIPTION_OPS macro when populating it.
172  */
173 struct _Eobj_Class_Description
174 {
175    const char *name; /**< The name of the class. */
176    Eobj_Class_Type type; /**< The type of the class. */
177    struct {
178         Eobj_Op *base_op_id;
179         const Eobj_Op_Description *descs;
180         size_t count;
181    } ops; /**< The ops description, should be filled using #EOBJ_CLASS_DESCRIPTION_OPS */
182    const Eobj_Event_Description **events; /**< The event descriptions for this class. */
183    size_t data_size; /**< The size of data (private + protected + public) this class needs per object. */
184    void (*constructor)(Eobj *obj, void *class_data); /**< The constructor of the object. */
185    void (*destructor)(Eobj *obj, void *class_data); /**< The destructor of the object. */
186    void (*class_constructor)(Eobj_Class *klass); /**< The constructor of the class. */
187    void (*class_destructor)(Eobj_Class *klass); /**< The destructor of the class. */
188 };
189
190 /**
191  * @typedef Eobj_Class_Description
192  * A convenience typedef for #_Eobj_Class_Description
193  */
194 typedef struct _Eobj_Class_Description Eobj_Class_Description;
195
196 /**
197  * @def EOBJ_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count)
198  * An helper macro to help populating #Eobj_Class_Description.
199  * @param base_op_id A pointer to the base op id of the class.
200  * @param op_descs the op descriptions array.
201  * @param count the number of ops in the op descriptions array.
202  */
203 #define EOBJ_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count) { base_op_id, op_descs, count }
204
205 /**
206  * @def EOBJ_OP_DESCRIPTION(op, type, doc)
207  * An helper macro to help populating #Eobj_Op_Description
208  * @param sub_id The sub id of the op being described.
209  * @param type The type string for the op.
210  * @param doc Additional doc for the op.
211  * @see Eobj_Op_Description
212  * @see EOBJ_OP_DESCRIPTION_SENTINEL
213  */
214 #define EOBJ_OP_DESCRIPTION(sub_id, type, doc) { sub_id, #sub_id, type, doc }
215 /**
216  * @def EOBJ_OP_DESCRIPTION_SENTINEL
217  * An helper macro to help populating #Eobj_Op_Description
218  * Should be placed at the end of the array.
219  * @see Eobj_Op_Description
220  * @see EOBJ_OP_DESCRIPTION
221  */
222 #define EOBJ_OP_DESCRIPTION_SENTINEL { 0, NULL, NULL, NULL }
223
224 /**
225  * @brief Create a new class.
226  * @param desc the class description to create the class with.
227  * @param parent the class to inherit from.
228  * @param ... A NULL terminated list of extensions (interfaces, mixins and the classes of any composite objects).
229  * @return The new class's handle on success, or NULL otherwise.
230  */
231 EAPI Eobj_Class *eobj_class_new(const Eobj_Class_Description *desc, const Eobj_Class *parent, ...);
232
233 /**
234  * @brief Sets the OP functions for a class.
235  * @param klass the class to set the functions to.
236  * @param func_descs a NULL terminated array of #Eobj_Op_Func_Description
237  *
238  * Should be called from within the class constructor.
239  */
240 EAPI void eobj_class_funcs_set(Eobj_Class *klass, const Eobj_Op_Func_Description *func_descs);
241
242 /**
243  * @brief Gets the name of the passed class.
244  * @param klass the class to work on.
245  * @return The class's name.
246  *
247  * @see eobj_class_get()
248  */
249 EAPI const char *eobj_class_name_get(const Eobj_Class *klass);
250
251 /**
252  * @}
253  */
254
255 /**
256  * @brief Init the eobj subsystem
257  * @return #EINA_TRUE on success.
258  *
259  * @see eobj_shutfown()
260  */
261 EAPI Eina_Bool eobj_init(void);
262
263 /**
264  * @brief Shutdown the eobj subsystem
265  * @return #EINA_TRUE on success.
266  *
267  * @see eobj_init()
268  */
269 EAPI Eina_Bool eobj_shutdown(void);
270
271 /**
272  * @def eobj_do
273  * A convenience wrapper around eobj_do_internal()
274  * @see eobj_do_internal
275  */
276 #define eobj_do(object, ...) eobj_do_internal(object, __VA_ARGS__, (Eobj_Op) 0)
277
278 /**
279  * @brief Issues ops on an object.
280  * @param obj The object to work on
281  * @param ... NULL terminated list of OPs and parameters.
282  * @return #EINA_TRUE on success.
283  *
284  * Use the helper macros, don't pass the parameters manually.
285  * Use #eobj_do instead of this function.
286  *
287  * @see #eobj_do
288  */
289 EAPI Eina_Bool eobj_do_internal(Eobj *obj, ...);
290
291 /**
292  * @brief Calls the super function for the specific op.
293  * @param obj The object to work on
294  * @param op The wanted op.
295  * @param ... list of parameters.
296  * @return #EINA_TRUE on success.
297  *
298  * Use the helper macros, don't pass the parameters manually.
299  *
300  * @see #eobj_do
301  */
302 EAPI Eina_Bool eobj_super_do(Eobj *obj, Eobj_Op op, ...);
303
304 /**
305  * @brief Gets the class of the object.
306  * @param obj The object to work on
307  * @return The object's class.
308  *
309  * @see eobj_class_name_get()
310  */
311 EAPI const Eobj_Class *eobj_class_get(const Eobj *obj);
312
313 /**
314  * @brief Calls the super constructor of the object passed.
315  * @param obj the object to work on.
316  *
317  * @see eobj_destructor_super()
318  */
319 EAPI void eobj_constructor_super(Eobj *obj);
320
321 /**
322  * @brief Calls the super destructor of the object passed.
323  * @param obj the object to work on.
324  *
325  * @see eobj_constructor_super()
326  */
327 EAPI void eobj_destructor_super(Eobj *obj);
328
329 /**
330  * @brief Notify eobj that there was an error when constructing the object.
331  * @param obj the object to work on.
332  *
333  * (Should only be called from within a constructor/destructor).
334  *
335  * @see eobj_constructor_error_get()
336  */
337 EAPI void eobj_constructor_error_set(Eobj *obj);
338
339 /**
340  * @brief Check if there was an error constructing obj
341  * @param obj the object to work on.
342  * @return #EINA_TRUE if there was an error.
343  *
344  * (Should only be called from within a constructor/destructor).
345  *
346  * @see eobj_constructor_error_set()
347  */
348 EAPI Eina_Bool eobj_constructor_error_get(const Eobj *obj);
349
350 /**
351  * @brief Create a new object.
352  * @param klass the class of the object to create.
353  * @param parent the parent to set to the object.
354  * @return An handle to the new object on success, NULL otherwise.
355  */
356 EAPI Eobj *eobj_add(const Eobj_Class *klass, Eobj *parent);
357
358 /**
359  * @brief Get the parent of an object
360  * @param obj the object to get the parent of.
361  * @return a pointer to the parent object.
362  */
363 EAPI Eobj *eobj_parent_get(Eobj *obj);
364
365 /**
366  * @brief Get a pointer to the data of an object for a specific class.
367  * @param obj the object to work on.
368  * @param klass the klass associated with the data.
369  * @return a pointer to the data.
370  */
371 EAPI void *eobj_data_get(Eobj *obj, const Eobj_Class *klass);
372
373 /**
374  * @brief Increment the object's reference count by 1.
375  * @param obj the object to work on.
376  * @return The object passed.
377  *
378  * @see eobj_unref()
379  * @see eobj_ref_get()
380  */
381 EAPI Eobj *eobj_ref(Eobj *obj);
382
383 /**
384  * @brief Decrement the object's reference count by 1 and free it if needed.
385  * @param obj the object to work on.
386  *
387  * @see eobj_ref()
388  * @see eobj_ref_get()
389  */
390 EAPI void eobj_unref(Eobj *obj);
391
392 /**
393  * @brief Return the ref count of the object passed.
394  * @param obj the object to work on.
395  * @return the ref count of the object.
396  *
397  * @see eobj_ref()
398  * @see eobj_unref()
399  */
400 EAPI int eobj_ref_get(const Eobj *obj);
401
402 /**
403  * @brief Delete the object passed (disregarding ref count).
404  * @param obj the object to work on.
405  *
406  * @see eobj_unref()
407  */
408 EAPI void eobj_del(Eobj *obj);
409
410 /**
411  * @brief Set generic data to object.
412  * @param obj the object to work on.
413  * @param key the key associated with the data
414  * @param data the data to set.
415  * @return the previous data associated with the key.
416  *
417  * @see eobj_generic_data_get()
418  * @see eobj_generic_data_del()
419  */
420 EAPI void *eobj_generic_data_set(Eobj *obj, const char *key, const void *data);
421
422 /**
423  * @brief Get generic data from object.
424  * @param obj the object to work on.
425  * @param key the key associated with the data
426  * @return the data associated with the key.
427  *
428  * @see eobj_generic_data_set()
429  * @see eobj_generic_data_del()
430  */
431 EAPI void *eobj_generic_data_get(const Eobj *obj, const char *key);
432
433 /**
434  * @brief Del generic data from object.
435  * @param obj the object to work on.
436  * @param key the key associated with the data
437  * @return the data previously associated with the key.
438  *
439  * @see eobj_generic_data_set()
440  * @see eobj_generic_data_get()
441  */
442 EAPI void *eobj_generic_data_del(Eobj *obj, const char *key);
443
444 /**
445  * @var _EOBJ_EV_FREE
446  * see #EOBJ_EV_FREE
447  */
448 EAPI extern const Eobj_Event_Description _EOBJ_EV_FREE;
449
450 /**
451  * @def EOBJ_EV_FREE
452  * Object is being freed.
453  */
454 #define EOBJ_EV_FREE (&(_EOBJ_EV_FREE))
455
456 /**
457  * @var _EOBJ_EV_DEL
458  * see #EOBJ_EV_DEL
459  */
460 EAPI extern const Eobj_Event_Description _EOBJ_EV_DEL;
461
462 /**
463  * @def EOBJ_EV_DEL
464  * Object is being deleted.
465  */
466 #define EOBJ_EV_DEL (&(_EOBJ_EV_DEL))
467
468 /**
469  * @addtogroup Eobj_Composite_Objects Composite Objects.
470  * @{
471  */
472
473 /**
474  * @brief Make an object a composite object of another.
475  * @param obj the "parent" object.
476  * @param comp_obj the object that will be used to composite obj.
477  *
478  * @see eobj_composite_object_detach()
479  * @see eobj_composite_is()
480  */
481 EAPI void eobj_composite_object_attach(Eobj *obj, Eobj *comp_obj);
482
483 /**
484  * @brief Detach a composite object from another object.
485  * @param obj the "parent" object.
486  * @param comp_obj the object attached to obj.
487  *
488  * @see eobj_composite_object_attach()
489  * @see eobj_composite_is()
490  */
491 EAPI void eobj_composite_object_detach(Eobj *obj, Eobj *comp_obj);
492
493 /**
494  * @brief Check if an object is a composite object.
495  * @param comp_obj the object to be checked.
496  * @return #EINA_TRUE if it is, #EINA_FALSE otherwise.
497  *
498  * @see eobj_composite_object_attach()
499  * @see eobj_composite_object_detach()
500  */
501 EAPI Eina_Bool eobj_composite_is(Eobj *comp_obj);
502
503 /**
504  * @}
505  */
506
507 /**
508  * @addtogroup Eobj_Events Eobj's Event Handling
509  * @{
510  */
511
512 /**
513  * @def EOBJ_CALLBACK_PRIORITY_BEFORE
514  * Slightly more prioritized than default.
515  */
516 #define EOBJ_CALLBACK_PRIORITY_BEFORE -100
517 /**
518  * @def EOBJ_CALLBACK_PRIORITY_DEFAULT
519  * Default callback priority level
520  */
521 #define EOBJ_CALLBACK_PRIORITY_DEFAULT 0
522 /**
523  * @def EOBJ_CALLBACK_PRIORITY_AFTER
524  * Slightly less prioritized than default.
525  */
526 #define EOBJ_CALLBACK_PRIORITY_AFTER 100
527
528 /**
529  * @typedef Eobj_Callback_Priority
530  *
531  * Callback priority value. Range is -32k - 32k. The lower the number, the
532  * bigger the priority.
533  *
534  * @see EOBJ_CALLBACK_PRIORITY_AFTER
535  * @see EOBJ_CALLBACK_PRIORITY_BEFORE
536  * @see EOBJ_CALLBACK_PRIORITY_DEFAULT
537  */
538 typedef short Eobj_Callback_Priority;
539
540 /**
541  * @typedef Eobj_Event_Cb
542  *
543  * An event callback prototype.
544  *
545  * @param data The user data registered with the callback.
546  * @param obj The object which initiated the event.
547  * @param desc The event's description.
548  * @param event_info additional data passed with the event.
549  * @return #EINA_FALSE to stop calling additional callbacks for the event, #EINA_TRUE to continue.
550  */
551 typedef Eina_Bool (*Eobj_Event_Cb)(void *data, Eobj *obj, const Eobj_Event_Description *desc, void *event_info);
552
553 /**
554  * @brief Add an event callback forwarder for an event and an object.
555  * @param obj The object to listen to events on.
556  * @param desc The description of the event to listen to.
557  * @param new_obj The object to emit events from.
558  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
559  *
560  * @see eobj_event_callback_forwarder_del()
561  */
562 EAPI Eina_Bool eobj_event_callback_forwarder_add(Eobj *obj, const Eobj_Event_Description *desc, Eobj *new_obj);
563
564 /**
565  * @brief Remove an event callback forwarder for an event and an object.
566  * @param obj The object to listen to events on.
567  * @param desc The description of the event to listen to.
568  * @param new_obj The object to emit events from.
569  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
570  *
571  * @see eobj_event_callback_forwarder_add()
572  */
573 EAPI Eina_Bool eobj_event_callback_forwarder_del(Eobj *obj, const Eobj_Event_Description *desc, Eobj *new_obj);
574
575 /**
576  * @def eobj_event_callback_add(obj, desc, cb, data)
577  * Add a callback for an event.
578  * @param obj The object to listen to events on.
579  * @param desc The description of the event to listen to.
580  * @param cb the callback to call.
581  * @param data additional data to pass to the callback.
582  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
583  *
584  * callbacks of the same priority are called in reverse order of creation.
585  *
586  * @see eobj_event_callback_priority_add()
587  */
588 #define eobj_event_callback_add(obj, desc, cb, data) \
589    eobj_event_callback_priority_add(obj, desc, \
590          EOBJ_CALLBACK_PRIORITY_DEFAULT, cb, data)
591
592 /**
593  * @brief Add a callback for an event with a specific priority.
594  * @param obj The object to listen to events on.
595  * @param desc The description of the event to listen to.
596  * @param priority The priority of the callback.
597  * @param cb the callback to call.
598  * @param data additional data to pass to the callback.
599  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
600  *
601  * callbacks of the same priority are called in reverse order of creation.
602  *
603  * @see #eobj_event_callback_add
604  */
605 EAPI Eina_Bool eobj_event_callback_priority_add(Eobj *obj, const Eobj_Event_Description *desc, Eobj_Callback_Priority priority, Eobj_Event_Cb cb, const void *data);
606
607 /**
608  * @brief Del a callback for an event
609  * @param obj The object to listen to delete from.
610  * @param desc The description of the event to listen to.
611  * @param func the callback to delete.
612  * @return The additional data that was set to be passed to the callback.
613  *
614  * @see eobj_event_callback_del_full()
615  */
616 EAPI void *eobj_event_callback_del(Eobj *obj, const Eobj_Event_Description *desc, Eobj_Event_Cb func);
617
618 /**
619  * @brief Del a callback with a specific data associated to it for an event.
620  * @param obj The object to listen to delete from.
621  * @param desc The description of the event to listen to.
622  * @param func the callback to delete.
623  * @param user_data The data to compare.
624  * @return The additional data that was set to be passed to the callback.
625  *
626  * @see eobj_event_callback_del()
627  */
628 EAPI void *eobj_event_callback_del_full(Eobj *obj, const Eobj_Event_Description *desc, Eobj_Event_Cb func, const void *user_data);
629
630 /**
631  * @brief Call the callbacks for an event of an object.
632  * @param obj The object to work on.
633  * @param desc The description of the event to call.
634  * @param event_info Extra event info to pass to the callbacks.
635  * @return #EINA_FALSE if one of the callbacks aborted the callback calls or #EINA_TRUE otherwise.
636  */
637 EAPI Eina_Bool eobj_event_callback_call(Eobj *obj, const Eobj_Event_Description *desc, const void *event_info);
638
639 /**
640  * @var _EOBJ_EV_CALLBACK_ADD
641  * see EOBJ_EV_CALLBACK_ADD
642  */
643 EAPI extern const Eobj_Event_Description _EOBJ_EV_CALLBACK_ADD;
644
645 /**
646  * @def EOBJ_EV_CALLBACK_ADD
647  * The event description (of type #Eobj_Event_Description) for
648  * The "Callback listener added" event.
649  */
650 #define EOBJ_EV_CALLBACK_ADD (&(_EOBJ_EV_CALLBACK_ADD))
651
652 /**
653  * @var _EOBJ_EV_CALLBACK_DEL
654  * see EOBJ_EV_CALLBACK_DEL
655  */
656 EAPI extern const Eobj_Event_Description _EOBJ_EV_CALLBACK_DEL;
657
658 /**
659  * @def EOBJ_EV_CALLBACK_DEL
660  * The event description (of type #Eobj_Event_Description) for
661  * The "Callback listener deleted" event.
662  */
663 #define EOBJ_EV_CALLBACK_DEL (&(_EOBJ_EV_CALLBACK_DEL))
664
665 /**
666  * @}
667  */
668
669 /**
670  * @addtogroup Eobj_Class_Base Eobj's Base class.
671  * @{
672  */
673
674 /**
675  * @def EOBJ_CLASS_BASE
676  * The class type for the Eobj base class.
677  */
678 #define EOBJ_CLASS_BASE eobj_base_class_get()
679 /**
680  * @brief Use #EOBJ_CLASS_BASE
681  * @internal
682  * */
683 EAPI const Eobj_Class *eobj_base_class_get(void) EINA_CONST;
684
685 /**
686  * @}
687  */
688
689 /**
690  * @}
691  */
692
693 #endif