8 * @defgroup Eobj Eobj Generic Object System
10 * The Eobj generic object system. It was designed to be the base object
17 * @def EOBJ_TYPECHECK(type, x)
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.
23 #define EOBJ_TYPECHECK(type, x) \
33 * The basic Object type.
35 typedef struct _Eobj Eobj;
38 * The Eobj operation type id.
40 typedef unsigned int Eobj_Op;
44 * A special #Eobj_Op meaning "No operation".
46 #define EOBJ_NOOP ((Eobj_Op) 0)
49 * @typedef eobj_op_func_type
50 * The type of the Op functions. This is the type of the functions used by
53 typedef void (*eobj_op_func_type)(Eobj *, void *class_data, va_list *list);
56 * @addtogroup Eobj_Events Eobj's Event Handling
61 * @struct _Eobj_Event_Description
62 * This struct holds the description of a specific event.
64 struct _Eobj_Event_Description
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. */
72 * @typedef Eobj_Event_Description
73 * A convenience typedef for #_Eobj_Event_Description
75 typedef struct _Eobj_Event_Description Eobj_Event_Description;
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
85 #define EOBJ_EVENT_DESCRIPTION(name, type, doc) { name, type, doc }
92 * @addtogroup Eobj_Class Eobj Class
98 * The basic Object class type.
100 typedef struct _Eobj_Class Eobj_Class;
103 * An enum representing the possible types of an Eobj class.
105 enum _Eobj_Class_Type
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 */
114 * @typedef Eobj_Class_Type
115 * A convenience typedef for #_Eobj_Class_Type.
117 typedef enum _Eobj_Class_Type Eobj_Class_Type;
120 * @struct _Eobj_Op_Func_Description
121 * Used to associate an Op with a func.
122 * @see eobj_class_funcs_set
124 struct _Eobj_Op_Func_Description
126 Eobj_Op op; /**< The op */
127 eobj_op_func_type func; /**< The function to call for the op. */
131 * @typedef Eobj_Op_Func_Description
132 * A convenience typedef for #_Eobj_Op_Func_Description
134 typedef struct _Eobj_Op_Func_Description Eobj_Op_Func_Description;
137 * @def EOBJ_OP_FUNC(op, func)
138 * A convenience macro to be used when populating the #Eobj_Op_Func_Description
141 #define EOBJ_OP_FUNC(op, func) { op, func }
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.
147 #define EOBJ_OP_FUNC_SENTINEL { 0, NULL }
150 * @struct _Eobj_Op_Description
151 * This struct holds the description of a specific op.
153 struct _Eobj_Op_Description
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. */
162 * @typedef Eobj_Op_Description
163 * A convenience typedef for #_Eobj_Op_Description
165 typedef struct _Eobj_Op_Description Eobj_Op_Description;
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.
173 struct _Eobj_Class_Description
175 const char *name; /**< The name of the class. */
176 Eobj_Class_Type type; /**< The type of the class. */
179 const Eobj_Op_Description *descs;
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. */
191 * @typedef Eobj_Class_Description
192 * A convenience typedef for #_Eobj_Class_Description
194 typedef struct _Eobj_Class_Description Eobj_Class_Description;
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.
203 #define EOBJ_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count) { base_op_id, op_descs, count }
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
214 #define EOBJ_OP_DESCRIPTION(sub_id, type, doc) { sub_id, #sub_id, type, doc }
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
222 #define EOBJ_OP_DESCRIPTION_SENTINEL { 0, NULL, NULL, NULL }
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.
231 EAPI const Eobj_Class *eobj_class_new(const Eobj_Class_Description *desc, const Eobj_Class *parent, ...);
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
238 * Should be called from within the class constructor.
240 EAPI void eobj_class_funcs_set(Eobj_Class *klass, const Eobj_Op_Func_Description *func_descs);
243 * @brief Gets the name of the passed class.
244 * @param klass the class to work on.
245 * @return The class's name.
247 * @see eobj_class_get()
249 EAPI const char *eobj_class_name_get(const Eobj_Class *klass);
256 * @brief Init the eobj subsystem
257 * @return #EINA_TRUE on success.
259 * @see eobj_shutfown()
261 EAPI Eina_Bool eobj_init(void);
264 * @brief Shutdown the eobj subsystem
265 * @return #EINA_TRUE on success.
269 EAPI Eina_Bool eobj_shutdown(void);
273 * A convenience wrapper around eobj_do_internal()
274 * @see eobj_do_internal
276 #define eobj_do(object, ...) eobj_do_internal(object, __VA_ARGS__, (Eobj_Op) 0)
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.
284 * Use the helper macros, don't pass the parameters manually.
285 * Use #eobj_do instead of this function.
289 EAPI Eina_Bool eobj_do_internal(Eobj *obj, ...);
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.
298 * Use the helper macros, don't pass the parameters manually.
302 EAPI Eina_Bool eobj_do_super(Eobj *obj, Eobj_Op op, ...);
305 * @brief Gets the class of the object.
306 * @param obj The object to work on
307 * @return The object's class.
309 * @see eobj_class_name_get()
311 EAPI const Eobj_Class *eobj_class_get(const Eobj *obj);
314 * @brief Calls the super constructor of the object passed.
315 * @param obj the object to work on.
317 * @see eobj_destructor_super()
319 EAPI void eobj_constructor_super(Eobj *obj);
322 * @brief Calls the super destructor of the object passed.
323 * @param obj the object to work on.
325 * @see eobj_constructor_super()
327 EAPI void eobj_destructor_super(Eobj *obj);
330 * @brief Notify eobj that there was an error when constructing the object.
331 * @param obj the object to work on.
333 * (Should only be called from within a constructor/destructor).
335 * @see eobj_constructor_error_get()
337 EAPI void eobj_constructor_error_set(Eobj *obj);
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.
344 * (Should only be called from within a constructor/destructor).
346 * @see eobj_constructor_error_set()
348 EAPI Eina_Bool eobj_constructor_error_get(const Eobj *obj);
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.
356 EAPI Eobj *eobj_add(const Eobj_Class *klass, Eobj *parent);
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.
363 EAPI Eobj *eobj_parent_get(Eobj *obj);
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.
371 EAPI void *eobj_data_get(Eobj *obj, const Eobj_Class *klass);
374 * @brief Increment the object's reference count by 1.
375 * @param obj the object to work on.
376 * @return The object passed.
379 * @see eobj_ref_get()
381 EAPI Eobj *eobj_ref(Eobj *obj);
384 * @brief Decrement the object's reference count by 1 and free it if needed.
385 * @param obj the object to work on.
388 * @see eobj_ref_get()
390 EAPI void eobj_unref(Eobj *obj);
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.
400 EAPI int eobj_ref_get(const Eobj *obj);
403 * @def eobj_xref(obj, ref_obj)
404 * Convenience macro around eobj_xref()
407 #define eobj_xref(obj, ref_obj) eobj_xref_internal(obj, ref_obj, __FILE__, __LINE__)
410 * @brief Increment the object's reference count by 1 (and associate the ref with ref_obj)
411 * @param obj the object to work on.
412 * @param ref_obj the object that references obj.
413 * @param file the call's filename.
414 * @param line the call's line number.
415 * @return The object passed (obj)
417 * People should not use this function, use #eobj_xref instead.
421 EAPI Eobj *eobj_xref_internal(Eobj *obj, const Eobj *ref_obj, const char *file, int line);
424 * @brief Decrement the object's reference count by 1 and free it if needed. Will free the ref associated with ref_obj).
425 * @param obj the object to work on.
426 * @param ref_obj the object that references obj.
428 * This function only enforces the checks for object association. I.e don't rely
429 * on it. If such enforces are compiled out, this function behaves the same as
432 * @see eobj_xref_internal()
434 EAPI void eobj_xunref(Eobj *obj, const Eobj *ref_obj);
437 * @brief Delete the object passed (disregarding ref count).
438 * @param obj the object to work on.
442 EAPI void eobj_del(Eobj *obj);
445 * @addtogroup Eobj_Weak_Ref Weak reference for Eobj objects.
450 * @struct _Eobj_Weak_Ref
451 * This is exposed for performance, please use eobj_weak_ref_get() when you
452 * actually want to get the refed object.
454 struct _Eobj_Weak_Ref
456 Eobj *obj; /**< The object being referenced. */
460 * @typedef Eobj_Weak_Ref
461 * Weak reference type for Eobj.
463 typedef struct _Eobj_Weak_Ref Eobj_Weak_Ref;
466 * @brief Create a new weak reference to obj.
467 * @param obj The object being referenced.
468 * @return A new weak reference.
470 EAPI Eobj_Weak_Ref *eobj_weak_ref_new(const Eobj *obj);
473 * @brief Free the weak reference passed.
474 * @param wref the weak reference to free.
476 EAPI void eobj_weak_ref_free(Eobj_Weak_Ref *wref);
479 * @brief Get the referenced object from the weak reference.
480 * @param wref the weak reference to get the object from.
481 * @return The object referenced by wref.
484 eobj_weak_ref_get(const Eobj_Weak_Ref *wref)
495 * @addtogroup Eobj_Composite_Objects Composite Objects.
500 * @brief Make an object a composite object of another.
501 * @param obj the "parent" object.
502 * @param comp_obj the object that will be used to composite obj.
504 * @see eobj_composite_object_detach()
505 * @see eobj_composite_is()
507 EAPI void eobj_composite_object_attach(Eobj *obj, Eobj *comp_obj);
510 * @brief Detach a composite object from another object.
511 * @param obj the "parent" object.
512 * @param comp_obj the object attached to obj.
514 * @see eobj_composite_object_attach()
515 * @see eobj_composite_is()
517 EAPI void eobj_composite_object_detach(Eobj *obj, Eobj *comp_obj);
520 * @brief Check if an object is a composite object.
521 * @param comp_obj the object to be checked.
522 * @return #EINA_TRUE if it is, #EINA_FALSE otherwise.
524 * @see eobj_composite_object_attach()
525 * @see eobj_composite_object_detach()
527 EAPI Eina_Bool eobj_composite_is(Eobj *comp_obj);
534 * @addtogroup Eobj_Events Eobj's Event Handling
539 * @def EOBJ_CALLBACK_PRIORITY_BEFORE
540 * Slightly more prioritized than default.
542 #define EOBJ_CALLBACK_PRIORITY_BEFORE -100
544 * @def EOBJ_CALLBACK_PRIORITY_DEFAULT
545 * Default callback priority level
547 #define EOBJ_CALLBACK_PRIORITY_DEFAULT 0
549 * @def EOBJ_CALLBACK_PRIORITY_AFTER
550 * Slightly less prioritized than default.
552 #define EOBJ_CALLBACK_PRIORITY_AFTER 100
555 * @typedef Eobj_Callback_Priority
557 * Callback priority value. Range is -32k - 32k. The lower the number, the
558 * higher the priority.
560 * @see EOBJ_CALLBACK_PRIORITY_AFTER
561 * @see EOBJ_CALLBACK_PRIORITY_BEFORE
562 * @see EOBJ_CALLBACK_PRIORITY_DEFAULT
564 typedef short Eobj_Callback_Priority;
567 * @typedef Eobj_Event_Cb
569 * An event callback prototype.
571 * @param data The user data registered with the callback.
572 * @param obj The object which initiated the event.
573 * @param desc The event's description.
574 * @param event_info additional data passed with the event.
575 * @return #EINA_FALSE to stop calling additional callbacks for the event, #EINA_TRUE to continue.
577 typedef Eina_Bool (*Eobj_Event_Cb)(void *data, Eobj *obj, const Eobj_Event_Description *desc, void *event_info);
580 * @brief Add an event callback forwarder for an event and an object.
581 * @param obj The object to listen to events on.
582 * @param desc The description of the event to listen to.
583 * @param new_obj The object to emit events from.
584 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
586 * @see eobj_event_callback_forwarder_del()
588 EAPI Eina_Bool eobj_event_callback_forwarder_add(Eobj *obj, const Eobj_Event_Description *desc, Eobj *new_obj);
591 * @brief Remove an event callback forwarder for an event and an object.
592 * @param obj The object to listen to events on.
593 * @param desc The description of the event to listen to.
594 * @param new_obj The object to emit events from.
595 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
597 * @see eobj_event_callback_forwarder_add()
599 EAPI Eina_Bool eobj_event_callback_forwarder_del(Eobj *obj, const Eobj_Event_Description *desc, Eobj *new_obj);
602 * @def eobj_event_callback_add(obj, desc, cb, data)
603 * Add a callback for an event.
604 * @param obj The object to listen to events on.
605 * @param desc The description of the event to listen to.
606 * @param cb the callback to call.
607 * @param data additional data to pass to the callback.
608 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
610 * callbacks of the same priority are called in reverse order of creation.
612 * @see eobj_event_callback_priority_add()
614 #define eobj_event_callback_add(obj, desc, cb, data) \
615 eobj_event_callback_priority_add(obj, desc, \
616 EOBJ_CALLBACK_PRIORITY_DEFAULT, cb, data)
619 * @brief Add a callback for an event with a specific priority.
620 * @param obj The object to listen to events on.
621 * @param desc The description of the event to listen to.
622 * @param priority The priority of the callback.
623 * @param cb the callback to call.
624 * @param data additional data to pass to the callback.
625 * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
627 * callbacks of the same priority are called in reverse order of creation.
629 * @see #eobj_event_callback_add
631 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);
634 * @brief Del a callback for an event
635 * @param obj The object to listen to delete from.
636 * @param desc The description of the event to listen to.
637 * @param func the callback to delete.
638 * @return The additional data that was set to be passed to the callback.
640 * @see eobj_event_callback_del_full()
642 EAPI void *eobj_event_callback_del(Eobj *obj, const Eobj_Event_Description *desc, Eobj_Event_Cb func);
645 * @brief Del a callback with a specific data associated to it for an event.
646 * @param obj The object to listen to delete from.
647 * @param desc The description of the event to listen to.
648 * @param func the callback to delete.
649 * @param user_data The data to compare.
650 * @return The additional data that was set to be passed to the callback.
652 * @see eobj_event_callback_del()
654 EAPI void *eobj_event_callback_del_full(Eobj *obj, const Eobj_Event_Description *desc, Eobj_Event_Cb func, const void *user_data);
657 * @brief Call the callbacks for an event of an object.
658 * @param obj The object to work on.
659 * @param desc The description of the event to call.
660 * @param event_info Extra event info to pass to the callbacks.
661 * @return #EINA_FALSE if one of the callbacks aborted the callback calls or #EINA_TRUE otherwise.
663 EAPI Eina_Bool eobj_event_callback_call(Eobj *obj, const Eobj_Event_Description *desc, const void *event_info);
670 * @addtogroup Eobj_Class_Base Eobj's Base class.
675 * @def EOBJ_BASE_CLASS
676 * The class type for the Eobj base class.
678 #define EOBJ_BASE_CLASS eobj_base_class_get()
680 * @brief Use #EOBJ_BASE_CLASS
683 EAPI const Eobj_Class *eobj_base_class_get(void) EINA_CONST;
686 * @typedef eobj_base_data_free_func
687 * Data free func prototype.
689 typedef void (*eobj_base_data_free_func)(void *);
692 * @var EOBJ_BASE_BASE_ID
693 * #EOBJ_BASE_CLASS 's base id.
695 extern EAPI Eobj_Op EOBJ_BASE_BASE_ID;
698 EOBJ_BASE_SUB_ID_DATA_SET,
699 EOBJ_BASE_SUB_ID_DATA_GET,
700 EOBJ_BASE_SUB_ID_DATA_DEL,
701 EOBJ_BASE_SUB_ID_LAST
705 * @def EOBJ_BASE_ID(sub_id)
706 * Helper macro to get the full Op ID out of the sub_id for EOBJ_BASE.
707 * @param sub_id the sub id inside EOBJ_BASE.
709 #define EOBJ_BASE_ID(sub_id) (EOBJ_BASE_BASE_ID + sub_id)
712 * @def EOBJ_BASE_DATA_SET(key, data, free_func)
713 * Set generic data to object.
714 * @param key the key associated with the data
715 * @param data the data to set.
716 * @param free_func the func to free data with (NULL means "do nothing").
718 * @see #EOBJ_BASE_DATA_GET
719 * @see #EOBJ_BASE_DATA_DEL
721 #define EOBJ_BASE_DATA_SET(key, data, free_func) EOBJ_BASE_ID(EOBJ_BASE_SUB_ID_DATA_SET), EOBJ_TYPECHECK(const char *, key), EOBJ_TYPECHECK(const void *, data), EOBJ_TYPECHECK(eobj_base_data_free_func, free_func)
724 * @def EOBJ_BASE_DATA_GET(key, data)
725 * Get generic data from object.
726 * @param key the key associated with the data
727 * @param data the data for the key
729 * @see #EOBJ_BASE_DATA_SET
730 * @see #EOBJ_BASE_DATA_DEL
732 #define EOBJ_BASE_DATA_GET(key, data) EOBJ_BASE_ID(EOBJ_BASE_SUB_ID_DATA_GET), EOBJ_TYPECHECK(const char *, key), EOBJ_TYPECHECK(void **, data)
735 * @def EOBJ_BASE_DATA_DEL(key)
736 * Del generic data from object.
737 * @param key the key associated with the data
739 * @see #EOBJ_BASE_DATA_SET
740 * @see #EOBJ_BASE_DATA_GET
742 #define EOBJ_BASE_DATA_DEL(key) EOBJ_BASE_ID(EOBJ_BASE_SUB_ID_DATA_DEL), EOBJ_TYPECHECK(const char *, key)
745 * @var _EOBJ_EV_CALLBACK_ADD
746 * see EOBJ_EV_CALLBACK_ADD
748 EAPI extern const Eobj_Event_Description _EOBJ_EV_CALLBACK_ADD;
751 * @def EOBJ_EV_CALLBACK_ADD
752 * The event description (of type #Eobj_Event_Description) for
753 * The "Callback listener added" event.
755 #define EOBJ_EV_CALLBACK_ADD (&(_EOBJ_EV_CALLBACK_ADD))
758 * @var _EOBJ_EV_CALLBACK_DEL
759 * see EOBJ_EV_CALLBACK_DEL
761 EAPI extern const Eobj_Event_Description _EOBJ_EV_CALLBACK_DEL;
764 * @def EOBJ_EV_CALLBACK_DEL
765 * The event description (of type #Eobj_Event_Description) for
766 * The "Callback listener deleted" event.
768 #define EOBJ_EV_CALLBACK_DEL (&(_EOBJ_EV_CALLBACK_DEL))
774 EAPI extern const Eobj_Event_Description _EOBJ_EV_FREE;
778 * Object is being freed.
780 #define EOBJ_EV_FREE (&(_EOBJ_EV_FREE))
786 EAPI extern const Eobj_Event_Description _EOBJ_EV_DEL;
790 * Object is being deleted.
792 #define EOBJ_EV_DEL (&(_EOBJ_EV_DEL))