lib/Eo.h

   1 #ifndef EO_H
   2 #define EO_H
   3
   4 #include <stdarg.h>
   5 #include <Eina.h>
   6
   7 #ifdef EAPI
   8 # undef EAPI
   9 #endif
  10
  11 #ifdef _WIN32
  12 # ifdef EFL_EO_BUILD
  13 #  ifdef DLL_EXPORT
  14 #   define EAPI __declspec(dllexport)
  15 #  else
  16 #   define EAPI
  17 #  endif /* ! DLL_EXPORT */
  18 # else
  19 #  define EAPI __declspec(dllimport)
  20 # endif /* ! EFL_EO_BUILD */
  21 #else
  22 # ifdef __GNUC__
  23 #  if __GNUC__ >= 4
  24 #   define EAPI __attribute__ ((visibility("default")))
  25 #  else
  26 #   define EAPI
  27 #  endif
  28 # else
  29 #  define EAPI
  30 # endif
  31 #endif /* ! _WIN32 */
  32
  33 /**
  34  * @var _eo_class_creation_lock
  35  * This variable is used for locking purposes in the class_get function
  36  * defined in #EO_DEFINE_CLASS.
  37  * This is just to work around the fact that we need to init locks before
  38  * using them.
  39  * Don't touch it if you don't know what you are doing.
  40  * @internal
  41  */
  42 EAPI extern Eina_Lock _eo_class_creation_lock;
  43
  44 /**
  45  * @defgroup Eo Eo Generic Object System
  46  *
  47  * The Eo generic object system. It was designed to be the base object
  48  * system for the EFL.
  49  *
  50  * @{
  51  */
  52
  53 /**
  54  * @def EO_TYPECHECK(type, x)
  55  *
  56  * Checks x is castable to type "type" and casts it to it.
  57  * @param type The C type to check against.
  58  * @param x the variable to test and cast.
  59  */
  60 #define EO_TYPECHECK(type, x) \
  61    ({ \
  62     type __x; \
  63     __x = x; \
  64     (type) __x; \
  65     })
  66
  67 /**
  68  * @typedef Eo
  69  * The basic Object type.
  70  */
  71 typedef struct _Eo Eo;
  72 /**
  73  * @typedef Eo_Op
  74  * The Eo operation type id.
  75  */
  76 typedef unsigned int Eo_Op;
  77
  78 /**
  79  * @def EO_NOOP
  80  * A special #Eo_Op meaning "No operation".
  81  */
  82 #define EO_NOOP ((Eo_Op) 0)
  83
  84 /**
  85  * @typedef eo_op_func_type
  86  * The type of the Op functions. This is the type of the functions used by
  87  * Eo.
  88  *
  89  * @see eo_op_func_type_const
  90  */
  91 typedef void (*eo_op_func_type)(Eo *, void *class_data, va_list *list);
  92
  93 /**
  94  * @typedef eo_op_func_type_const
  95  * The type of the const Op functions. This is the type of the functions used
  96  * by Eo. This is the same as #eo_op_func_type, except that this should
  97  * be used with functions that don't modify the data.
  98  *
  99  * @see eo_op_func_type
 100  */
 101 typedef void (*eo_op_func_type_const)(const Eo *, const void *class_data, va_list *list);
 102
 103 /**
 104  * @addtogroup Eo_Events Eo's Event Handling
 105  * @{
 106  */
 107
 108 /**
 109  * @struct _Eo_Event_Description
 110  * This struct holds the description of a specific event.
 111  */
 112 struct _Eo_Event_Description
 113 {
 114    const char *name; /**< name of the event. */
 115    const char *type; /**< describes the data passed in event_info */
 116    const char *doc; /**< Explanation about the event. */
 117 };
 118
 119 /**
 120  * @typedef Eo_Event_Description
 121  * A convenience typedef for #_Eo_Event_Description
 122  */
 123 typedef struct _Eo_Event_Description Eo_Event_Description;
 124
 125 /**
 126  * @def EO_EVENT_DESCRIPTION(name, type, doc)
 127  * An helper macro to help populating #Eo_Event_Description
 128  * @param name The name of the event.
 129  * @param type The type string of the event.
 130  * @param doc Additional doc for the event.
 131  * @see Eo_Event_Description
 132  */
 133 #define EO_EVENT_DESCRIPTION(name, type, doc) { name, type, doc }
 134
 135 /**
 136  * @}
 137  */
 138
 139 /**
 140  * @addtogroup Eo_Class Eo Class
 141  * @{
 142  */
 143
 144 /**
 145  * @typedef Eo_Class
 146  * The basic Object class type.
 147  */
 148 typedef struct _Eo_Class Eo_Class;
 149
 150 /**
 151  * @def EO_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...)
 152  * A convenience macro to be used for creating the class_get function. This
 153  * macro is fairly simple but should still be used as it'll let us improve
 154  * things easily.
 155  * @param class_get_func_name the name of the wanted class_get function name.
 156  * @param class_desc the class description.
 157  * @param parent_class The parent class for the function. Look at eo_class_new() for more information.
 158  * @param ... List of etxensions. Look at eo_class_new() for more information.
 159  *
 160  * You must use this macro if you want thread safety in class creation.
 161  */
 162 #define EO_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...) \
 163 EAPI const Eo_Class * \
 164 class_get_func_name(void) \
 165 { \
 166    static volatile char lk_init = 0; \
 167    static Eina_Lock _my_lock; \
 168    static const Eo_Class * volatile _my_class = NULL; \
 169    if (EINA_LIKELY(!!_my_class)) return _my_class; \
 170    \
 171    eina_lock_take(&_eo_class_creation_lock); \
 172    if (!lk_init) \
 173       eina_lock_new(&_my_lock); \
 174    if (lk_init < 2) eina_lock_take(&_my_lock); \
 175    if (!lk_init) \
 176       lk_init = 1; \
 177    else \
 178      { \
 179         if (lk_init < 2) eina_lock_release(&_my_lock); \
 180         eina_lock_release(&_eo_class_creation_lock); \
 181         return _my_class; \
 182      } \
 183    eina_lock_release(&_eo_class_creation_lock); \
 184    _my_class = eo_class_new(class_desc, parent_class, __VA_ARGS__); \
 185    eina_lock_release(&_my_lock); \
 186    \
 187    eina_lock_take(&_eo_class_creation_lock); \
 188    eina_lock_free(&_my_lock); \
 189    lk_init = 2; \
 190    eina_lock_release(&_eo_class_creation_lock); \
 191    return _my_class; \
 192 }
 193
 194
 195 /**
 196  * An enum representing the possible types of an Eo class.
 197  */
 198 enum _Eo_Class_Type
 199 {
 200    EO_CLASS_TYPE_REGULAR = 0, /**< Regular class. */
 201    EO_CLASS_TYPE_REGULAR_NO_INSTANT, /**< Regular non instant-able class. */
 202    EO_CLASS_TYPE_INTERFACE, /**< Interface */
 203    EO_CLASS_TYPE_MIXIN /**< Mixin */
 204 };
 205
 206 /**
 207  * @typedef Eo_Class_Type
 208  * A convenience typedef for #_Eo_Class_Type.
 209  */
 210 typedef enum _Eo_Class_Type Eo_Class_Type;
 211
 212 /**
 213  * @struct _Eo_Op_Func_Description
 214  * Used to associate an Op with a func.
 215  * @see eo_class_funcs_set
 216  */
 217 struct _Eo_Op_Func_Description
 218 {
 219    Eo_Op op; /**< The op */
 220    eo_op_func_type func; /**< The function to call for the op. */
 221    Eina_Bool constant; /**< @c EINA_TRUE if this function is a const. */
 222 };
 223
 224 /**
 225  * @typedef Eo_Op_Func_Description
 226  * A convenience typedef for #_Eo_Op_Func_Description
 227  */
 228 typedef struct _Eo_Op_Func_Description Eo_Op_Func_Description;
 229
 230 /**
 231  * @def EO_OP_FUNC(op, func)
 232  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 233  * array.
 234  *
 235  * @see EO_OP_FUNC_CONST
 236  */
 237 #define EO_OP_FUNC(op, func) { op, EO_TYPECHECK(eo_op_func_type, func), EINA_FALSE }
 238
 239 /**
 240  * @def EO_OP_FUNC_CONST(op, func)
 241  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 242  * array.
 243  * The same as #EO_OP_FUNC but for const functions.
 244  *
 245  * @see EO_OP_FUNC
 246  */
 247 #define EO_OP_FUNC_CONST(op, func) { op, (eo_op_func_type) EO_TYPECHECK(eo_op_func_type_const, func), EINA_TRUE }
 248
 249 /**
 250  * @def EO_OP_FUNC_SENTINEL
 251  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 252  * array. It must appear at the end of the ARRAY.
 253  */
 254 #define EO_OP_FUNC_SENTINEL { 0, NULL, EINA_FALSE }
 255
 256 /**
 257  * @struct _Eo_Op_Description
 258  * This struct holds the description of a specific op.
 259  */
 260 struct _Eo_Op_Description
 261 {
 262    Eo_Op sub_op; /**< The sub_id of the op in it's class. */
 263    const char *name; /**< The name of the op. */
 264    const char *type; /**< descripbes the Op's function signature. */
 265    const char *doc; /**< Explanation about the Op. */
 266    Eina_Bool constant; /**< @c EINA_TRUE if this op's implementation should not change the obj. */
 267 };
 268
 269 /**
 270  * @typedef Eo_Op_Description
 271  * A convenience typedef for #_Eo_Op_Description
 272  */
 273 typedef struct _Eo_Op_Description Eo_Op_Description;
 274
 275 /**
 276  * @struct _Eo_Class_Description
 277  * This struct holds the description of a class.
 278  * This description should be passed to eo_class_new.
 279  * Please use the #EO_CLASS_DESCRIPTION_OPS macro when populating it.
 280  */
 281 struct _Eo_Class_Description
 282 {
 283    const char *name; /**< The name of the class. */
 284    Eo_Class_Type type; /**< The type of the class. */
 285    struct {
 286         Eo_Op *base_op_id;
 287         const Eo_Op_Description *descs;
 288         size_t count;
 289    } ops; /**< The ops description, should be filled using #EO_CLASS_DESCRIPTION_OPS */
 290    const Eo_Event_Description **events; /**< The event descriptions for this class. */
 291    size_t data_size; /**< The size of data (private + protected + public) this class needs per object. */
 292    void (*constructor)(Eo *obj, void *class_data); /**< The constructor of the object. */
 293    void (*destructor)(Eo *obj, void *class_data); /**< The destructor of the object. */
 294    void (*class_constructor)(Eo_Class *klass); /**< The constructor of the class. */
 295    void (*class_destructor)(Eo_Class *klass); /**< The destructor of the class. */
 296 };
 297
 298 /**
 299  * @typedef Eo_Class_Description
 300  * A convenience typedef for #_Eo_Class_Description
 301  */
 302 typedef struct _Eo_Class_Description Eo_Class_Description;
 303
 304 /**
 305  * @def EO_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count)
 306  * An helper macro to help populating #Eo_Class_Description.
 307  * @param base_op_id A pointer to the base op id of the class.
 308  * @param op_descs the op descriptions array.
 309  * @param count the number of ops in the op descriptions array.
 310  */
 311 #define EO_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count) { base_op_id, op_descs, count }
 312
 313 /**
 314  * @def EO_OP_DESCRIPTION(op, type, doc)
 315  * An helper macro to help populating #Eo_Op_Description
 316  * @param sub_id The sub id of the op being described.
 317  * @param type The type string for the op.
 318  * @param doc Additional doc for the op.
 319  * @see Eo_Op_Description
 320  * @see EO_OP_DESCRIPTION_CONST
 321  * @see EO_OP_DESCRIPTION_SENTINEL
 322  */
 323 #define EO_OP_DESCRIPTION(sub_id, type, doc) { sub_id, #sub_id, type, doc, EINA_FALSE }
 324
 325 /**
 326  * @def EO_OP_DESCRIPTION_CONST(op, type, doc)
 327  * An helper macro to help populating #Eo_Op_Description
 328  * This macro is the same as EO_OP_DESCRIPTION but indicates that the op's
 329  * implementation should not change the object.
 330  * @param sub_id The sub id of the op being described.
 331  * @param type The type string for the op.
 332  * @param doc Additional doc for the op.
 333  * @see Eo_Op_Description
 334  * @see EO_OP_DESCRIPTION
 335  * @see EO_OP_DESCRIPTION_SENTINEL
 336  */
 337 #define EO_OP_DESCRIPTION_CONST(sub_id, type, doc) { sub_id, #sub_id, type, doc, EINA_TRUE }
 338
 339 /**
 340  * @def EO_OP_DESCRIPTION_SENTINEL
 341  * An helper macro to help populating #Eo_Op_Description
 342  * Should be placed at the end of the array.
 343  * @see Eo_Op_Description
 344  * @see EO_OP_DESCRIPTION
 345  */
 346 #define EO_OP_DESCRIPTION_SENTINEL { 0, NULL, NULL, NULL, EINA_FALSE }
 347
 348 /**
 349  * @brief Create a new class.
 350  * @param desc the class description to create the class with.
 351  * @param parent the class to inherit from.
 352  * @param ... A NULL terminated list of extensions (interfaces, mixins and the classes of any composite objects).
 353  * @return The new class's handle on success, or NULL otherwise.
 354  *
 355  * You should use #EO_DEFINE_CLASS. It'll provide thread safety and other
 356  * features easily.
 357  *
 358  * @see #EO_DEFINE_CLASS
 359  */
 360 EAPI const Eo_Class *eo_class_new(const Eo_Class_Description *desc, const Eo_Class *parent, ...);
 361
 362 /**
 363  * @brief Sets the OP functions for a class.
 364  * @param klass the class to set the functions to.
 365  * @param func_descs a NULL terminated array of #Eo_Op_Func_Description
 366  *
 367  * Should be called from within the class constructor.
 368  */
 369 EAPI void eo_class_funcs_set(Eo_Class *klass, const Eo_Op_Func_Description *func_descs);
 370
 371 /**
 372  * @brief Gets the name of the passed class.
 373  * @param klass the class to work on.
 374  * @return The class's name.
 375  *
 376  * @see eo_class_get()
 377  */
 378 EAPI const char *eo_class_name_get(const Eo_Class *klass);
 379
 380 /**
 381  * @}
 382  */
 383
 384 /**
 385  * @brief Init the eo subsystem
 386  * @return @c EINA_TRUE on success.
 387  *
 388  * @see eo_shutfown()
 389  */
 390 EAPI Eina_Bool eo_init(void);
 391
 392 /**
 393  * @brief Shutdown the eo subsystem
 394  * @return @c EINA_TRUE on success.
 395  *
 396  * @see eo_init()
 397  */
 398 EAPI Eina_Bool eo_shutdown(void);
 399
 400 /**
 401  * @def eo_do
 402  * A convenience wrapper around eo_do_internal()
 403  * @see eo_do_internal
 404  */
 405 #define eo_do(obj, ...) eo_do_internal(obj, EINA_FALSE, __VA_ARGS__, EO_NOOP)
 406
 407 /**
 408  * @def eo_query
 409  * Same as #eo_do but only for const ops.
 410  * @see eo_do
 411  */
 412 #define eo_query(obj, ...) eo_do_internal((Eo *) EO_TYPECHECK(const Eo *, obj), EINA_TRUE, __VA_ARGS__, EO_NOOP)
 413
 414 /**
 415  * @brief Issues ops on an object.
 416  * @param obj The object to work on
 417  * @param constant @c EINA_TRUE if this call is on a constant object.
 418  * @param ... NULL terminated list of OPs and parameters.
 419  * @return @c EINA_TRUE on success.
 420  *
 421  * Use the helper macros, don't pass the parameters manually.
 422  * Use #eo_do instead of this function.
 423  *
 424  * @see #eo_do
 425  */
 426 EAPI Eina_Bool eo_do_internal(Eo *obj, Eina_Bool constant, ...);
 427
 428 /**
 429  * @brief Calls the super function for the specific op.
 430  * @param obj The object to work on
 431  * @param ... list of parameters.
 432  * @return @c EINA_TRUE on success.
 433  *
 434  * Unlike eo_do() and eo_query(), this function only accepts one op.
 435  *
 436  * Use the helper macros, don't pass the parameters manually.
 437  *
 438  * Same as eo_do_super() just for const objects.
 439  *
 440  * @see #eo_query
 441  * @see eo_do_super()
 442  */
 443 #define eo_query_super(obj, ...) eo_do_super_internal((Eo *) EO_TYPECHECK(const Eo *, obj), EINA_TRUE, __VA_ARGS__)
 444
 445 /**
 446  * @brief Calls the super function for the specific op.
 447  * @param obj The object to work on
 448  * @param ... list of parameters.
 449  * @return @c EINA_TRUE on success.
 450  *
 451  * Unlike eo_do() and eo_query(), this function only accepts one op.
 452  *
 453  * @see #eo_do
 454  * @see eo_query_super()
 455  */
 456 #define eo_do_super(obj, ...) eo_do_super_internal(obj, EINA_FALSE, __VA_ARGS__)
 457
 458 /**
 459  * @brief Calls the super function for the specific op.
 460  * @param obj The object to work on
 461  * @param constant @c EINA_TRUE if this call is on a constant object.
 462  * @param op The wanted op.
 463  * @param ... list of parameters.
 464  * @return @c EINA_TRUE on success.
 465  *
 466  * Don't use this function, use the wrapping macros instead.
 467  *
 468  * @see #eo_do
 469  * @see #eo_do_super
 470  * @see #eo_query_super
 471  */
 472 EAPI Eina_Bool eo_do_super_internal(Eo *obj, Eina_Bool constant, Eo_Op op, ...);
 473
 474 /**
 475  * @brief Gets the class of the object.
 476  * @param obj The object to work on
 477  * @return The object's class.
 478  *
 479  * @see eo_class_name_get()
 480  */
 481 EAPI const Eo_Class *eo_class_get(const Eo *obj);
 482
 483 /**
 484  * @brief Calls the super constructor of the object passed.
 485  * @param obj the object to work on.
 486  *
 487  * @see eo_destructor_super()
 488  */
 489 EAPI void eo_constructor_super(Eo *obj);
 490
 491 /**
 492  * @brief Calls the super destructor of the object passed.
 493  * @param obj the object to work on.
 494  *
 495  * @see eo_constructor_super()
 496  */
 497 EAPI void eo_destructor_super(Eo *obj);
 498
 499 /**
 500  * @brief Notify eo that there was an error when constructing the object.
 501  * @param obj the object to work on.
 502  *
 503  * (Should only be called from within a constructor/destructor).
 504  *
 505  * @see eo_constructor_error_get()
 506  */
 507 EAPI void eo_constructor_error_set(Eo *obj);
 508
 509 /**
 510  * @brief Check if there was an error constructing obj
 511  * @param obj the object to work on.
 512  * @return @c EINA_TRUE if there was an error.
 513  *
 514  * (Should only be called from within a constructor/destructor).
 515  *
 516  * @see eo_constructor_error_set()
 517  */
 518 EAPI Eina_Bool eo_constructor_error_get(const Eo *obj);
 519
 520 /**
 521  * @brief Create a new object.
 522  * @param klass the class of the object to create.
 523  * @param parent the parent to set to the object.
 524  * @return An handle to the new object on success, NULL otherwise.
 525  */
 526 EAPI Eo *eo_add(const Eo_Class *klass, Eo *parent);
 527
 528 /**
 529  * @brief Get the parent of an object
 530  * @param obj the object to get the parent of.
 531  * @return a pointer to the parent object.
 532  */
 533 EAPI Eo *eo_parent_get(const Eo *obj);
 534
 535 /**
 536  * @brief Get a pointer to the data of an object for a specific class.
 537  * @param obj the object to work on.
 538  * @param klass the klass associated with the data.
 539  * @return a pointer to the data.
 540  */
 541 EAPI void *eo_data_get(const Eo *obj, const Eo_Class *klass);
 542
 543 /**
 544  * @brief Increment the object's reference count by 1.
 545  * @param obj the object to work on.
 546  * @return The object passed.
 547  *
 548  * It's very easy to get a refcount leak and start leaking memory because
 549  * of a forgotten unref or an extra ref. That is why there are eo_xref
 550  * and eo_xunref that will make debugging easier in such a case.
 551  * Therefor, these functions should only be used in small scopes, i.e at the
 552  * start of some section in which the object may get freed, or if you know
 553  * what you are doing.
 554  *
 555  * @see eo_unref()
 556  * @see eo_ref_get()
 557  */
 558 EAPI Eo *eo_ref(Eo *obj);
 559
 560 /**
 561  * @brief Decrement the object's reference count by 1 and free it if needed.
 562  * @param obj the object to work on.
 563  *
 564  * @see eo_ref()
 565  * @see eo_ref_get()
 566  */
 567 EAPI void eo_unref(Eo *obj);
 568
 569 /**
 570  * @brief Return the ref count of the object passed.
 571  * @param obj the object to work on.
 572  * @return the ref count of the object.
 573  *
 574  * @see eo_ref()
 575  * @see eo_unref()
 576  */
 577 EAPI int eo_ref_get(const Eo *obj);
 578
 579 /**
 580  * @def eo_xref(obj, ref_obj)
 581  * Convenience macro around eo_xref_internal()
 582  * @see eo_xref()
 583  */
 584 #define eo_xref(obj, ref_obj) eo_xref_internal(obj, ref_obj, __FILE__, __LINE__)
 585
 586 /**
 587  * @brief Increment the object's reference count by 1 (and associate the ref with ref_obj)
 588  * @param obj the object to work on.
 589  * @param ref_obj the object that references obj.
 590  * @param file the call's filename.
 591  * @param line the call's line number.
 592  * @return The object passed (obj)
 593  *
 594  * People should not use this function, use #eo_xref instead.
 595  * A compile flag my make it and eobj_xunref() behave the same as eobj_ref()
 596  * and eobj_unref() respectively. So this should be used wherever possible.
 597  *
 598  * @see eo_xunref()
 599  */
 600 EAPI Eo *eo_xref_internal(Eo *obj, const Eo *ref_obj, const char *file, int line);
 601
 602 /**
 603  * @brief Decrement the object's reference count by 1 and free it if needed. Will free the ref associated with ref_obj).
 604  * @param obj the object to work on.
 605  * @param ref_obj the object that references obj.
 606  *
 607  * This function only enforces the checks for object association. I.e don't rely
 608  * on it. If such enforces are compiled out, this function behaves the same as
 609  * eo_unref().
 610  *
 611  * @see eo_xref_internal()
 612  */
 613 EAPI void eo_xunref(Eo *obj, const Eo *ref_obj);
 614
 615 /**
 616  * @brief Delete the object passed (disregarding ref count).
 617  * @param obj the object to work on.
 618  *
 619  * @see eo_unref()
 620  */
 621 EAPI void eo_del(Eo *obj);
 622
 623 /**
 624  * @addtogroup Eo_Composite_Objects Composite Objects.
 625  * @{
 626  */
 627
 628 /**
 629  * @brief Make an object a composite object of another.
 630  * @param obj the "parent" object.
 631  * @param comp_obj the object that will be used to composite obj.
 632  *
 633  * @see eo_composite_object_detach()
 634  * @see eo_composite_is()
 635  */
 636 EAPI void eo_composite_object_attach(Eo *obj, Eo *comp_obj);
 637
 638 /**
 639  * @brief Detach a composite object from another object.
 640  * @param obj the "parent" object.
 641  * @param comp_obj the object attached to obj.
 642  *
 643  * @see eo_composite_object_attach()
 644  * @see eo_composite_is()
 645  */
 646 EAPI void eo_composite_object_detach(Eo *obj, Eo *comp_obj);
 647
 648 /**
 649  * @brief Check if an object is a composite object.
 650  * @param comp_obj the object to be checked.
 651  * @return @c EINA_TRUE if it is, @c EINA_FALSE otherwise.
 652  *
 653  * @see eo_composite_object_attach()
 654  * @see eo_composite_object_detach()
 655  */
 656 EAPI Eina_Bool eo_composite_is(Eo *comp_obj);
 657
 658 /**
 659  * @}
 660  */
 661
 662 /**
 663  * @addtogroup Eo_Events Eo's Event Handling
 664  * @{
 665  */
 666
 667 /**
 668  * @def EO_CALLBACK_PRIORITY_BEFORE
 669  * Slightly more prioritized than default.
 670  */
 671 #define EO_CALLBACK_PRIORITY_BEFORE -100
 672 /**
 673  * @def EO_CALLBACK_PRIORITY_DEFAULT
 674  * Default callback priority level
 675  */
 676 #define EO_CALLBACK_PRIORITY_DEFAULT 0
 677 /**
 678  * @def EO_CALLBACK_PRIORITY_AFTER
 679  * Slightly less prioritized than default.
 680  */
 681 #define EO_CALLBACK_PRIORITY_AFTER 100
 682
 683 /**
 684  * @typedef Eo_Callback_Priority
 685  *
 686  * Callback priority value. Range is -32k - 32k. The lower the number, the
 687  * higher the priority.
 688  *
 689  * @see EO_CALLBACK_PRIORITY_AFTER
 690  * @see EO_CALLBACK_PRIORITY_BEFORE
 691  * @see EO_CALLBACK_PRIORITY_DEFAULT
 692  */
 693 typedef short Eo_Callback_Priority;
 694
 695 /**
 696  * @def EO_CALLBACK_STOP
 697  * Stop calling callbacks for the even of which the callback was called for.
 698  * @see EO_CALLBACK_CONTINUE
 699  */
 700 #define EO_CALLBACK_STOP EINA_FALSE
 701
 702 /**
 703  * @def EO_CALLBACK_CONTINUE
 704  * Continue calling callbacks for the even of which the callback was called for.
 705  * @see EO_CALLBACK_STOP
 706  */
 707 #define EO_CALLBACK_CONTINUE EINA_TRUE
 708
 709 /**
 710  * @typedef Eo_Event_Cb
 711  *
 712  * An event callback prototype.
 713  *
 714  * @param data The user data registered with the callback.
 715  * @param obj The object which initiated the event.
 716  * @param desc The event's description.
 717  * @param event_info additional data passed with the event.
 718  * @return #EO_CALLBACK_STOP to stop calling additional callbacks for the event, #EO_CALLBACK_CONTINUE to continue.
 719  */
 720 typedef Eina_Bool (*Eo_Event_Cb)(void *data, Eo *obj, const Eo_Event_Description *desc, void *event_info);
 721
 722 /**
 723  * @brief Add an event callback forwarder for an event and an object.
 724  * @param obj The object to listen to events on.
 725  * @param desc The description of the event to listen to.
 726  * @param new_obj The object to emit events from.
 727  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 728  *
 729  * @see eo_event_callback_forwarder_del()
 730  */
 731 EAPI Eina_Bool eo_event_callback_forwarder_add(Eo *obj, const Eo_Event_Description *desc, Eo *new_obj);
 732
 733 /**
 734  * @brief Remove an event callback forwarder for an event and an object.
 735  * @param obj The object to listen to events on.
 736  * @param desc The description of the event to listen to.
 737  * @param new_obj The object to emit events from.
 738  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 739  *
 740  * @see eo_event_callback_forwarder_add()
 741  */
 742 EAPI Eina_Bool eo_event_callback_forwarder_del(Eo *obj, const Eo_Event_Description *desc, Eo *new_obj);
 743
 744 /**
 745  * @def eo_event_callback_add(obj, desc, cb, data)
 746  * Add a callback for an event.
 747  * @param obj The object to listen to events on.
 748  * @param desc The description of the event to listen to.
 749  * @param cb the callback to call.
 750  * @param data additional data to pass to the callback.
 751  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 752  *
 753  * callbacks of the same priority are called in reverse order of creation.
 754  *
 755  * @see eo_event_callback_priority_add()
 756  */
 757 #define eo_event_callback_add(obj, desc, cb, data) \
 758    eo_event_callback_priority_add(obj, desc, \
 759          EO_CALLBACK_PRIORITY_DEFAULT, cb, data)
 760
 761 /**
 762  * @brief Add a callback for an event with a specific priority.
 763  * @param obj The object to listen to events on.
 764  * @param desc The description of the event to listen to.
 765  * @param priority The priority of the callback.
 766  * @param cb the callback to call.
 767  * @param data additional data to pass to the callback.
 768  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 769  *
 770  * callbacks of the same priority are called in reverse order of creation.
 771  *
 772  * @see #eo_event_callback_add
 773  */
 774 EAPI Eina_Bool eo_event_callback_priority_add(Eo *obj, const Eo_Event_Description *desc, Eo_Callback_Priority priority, Eo_Event_Cb cb, const void *data);
 775
 776 /**
 777  * @brief Del a callback for an event
 778  * @param obj The object to listen to delete from.
 779  * @param desc The description of the event to listen to.
 780  * @param func the callback to delete.
 781  * @return The additional data that was set to be passed to the callback.
 782  *
 783  * @see eo_event_callback_del()
 784  */
 785 EAPI void *eo_event_callback_del_lazy(Eo *obj, const Eo_Event_Description *desc, Eo_Event_Cb func);
 786
 787 /**
 788  * @brief Del a callback with a specific data associated to it for an event.
 789  * @param obj The object to listen to delete from.
 790  * @param desc The description of the event to listen to.
 791  * @param func the callback to delete.
 792  * @param user_data The data to compare.
 793  * @return The additional data that was set to be passed to the callback.
 794  *
 795  * @see eo_event_callback_del_lazy()
 796  */
 797 EAPI void *eo_event_callback_del(Eo *obj, const Eo_Event_Description *desc, Eo_Event_Cb func, const void *user_data);
 798
 799 /**
 800  * @brief Call the callbacks for an event of an object.
 801  * @param obj The object to work on.
 802  * @param desc The description of the event to call.
 803  * @param event_info Extra event info to pass to the callbacks.
 804  * @return @c EINA_FALSE if one of the callbacks aborted the callback calls or @c EINA_TRUE otherwise.
 805  */
 806 EAPI Eina_Bool eo_event_callback_call(Eo *obj, const Eo_Event_Description *desc, const void *event_info);
 807
 808 /**
 809  * @}
 810  */
 811
 812 /**
 813  * @addtogroup Eo_Class_Base Eo's Base class.
 814  * @{
 815  */
 816
 817 /**
 818  * @def EO_BASE_CLASS
 819  * The class type for the Eo base class.
 820  */
 821 #define EO_BASE_CLASS eo_base_class_get()
 822 /**
 823  * @brief Use #EO_BASE_CLASS
 824  * @internal
 825  * */
 826 EAPI const Eo_Class *eo_base_class_get(void) EINA_CONST;
 827
 828 /**
 829  * @typedef eo_base_data_free_func
 830  * Data free func prototype.
 831  */
 832 typedef void (*eo_base_data_free_func)(void *);
 833
 834 /**
 835  * @var EO_BASE_BASE_ID
 836  * #EO_BASE_CLASS 's base id.
 837  */
 838 extern EAPI Eo_Op EO_BASE_BASE_ID;
 839
 840 enum {
 841      EO_BASE_SUB_ID_DATA_SET,
 842      EO_BASE_SUB_ID_DATA_GET,
 843      EO_BASE_SUB_ID_DATA_DEL,
 844      EO_BASE_SUB_ID_WREF_ADD,
 845      EO_BASE_SUB_ID_WREF_DEL,
 846      EO_BASE_SUB_ID_LAST
 847 };
 848
 849 /**
 850  * @def EO_BASE_ID(sub_id)
 851  * Helper macro to get the full Op ID out of the sub_id for EO_BASE.
 852  * @param sub_id the sub id inside EO_BASE.
 853  */
 854 #define EO_BASE_ID(sub_id) (EO_BASE_BASE_ID + sub_id)
 855
 856 /**
 857  * @def eo_base_data_set(key, data, free_func)
 858  * Set generic data to object.
 859  * @param[in] key the key associated with the data
 860  * @param[in] data the data to set.
 861  * @param[in] free_func the func to free data with (NULL means "do nothing").
 862  *
 863  * @see #eo_base_data_get
 864  * @see #eo_base_data_del
 865  */
 866 #define eo_base_data_set(key, data, free_func) EO_BASE_ID(EO_BASE_SUB_ID_DATA_SET), EO_TYPECHECK(const char *, key), EO_TYPECHECK(const void *, data), EO_TYPECHECK(eo_base_data_free_func, free_func)
 867
 868 /**
 869  * @def eo_base_data_get(key, data)
 870  * Get generic data from object.
 871  * @param[in] key the key associated with the data
 872  * @param[out] data the data for the key
 873  *
 874  * @see #eo_base_data_set
 875  * @see #eo_base_data_del
 876  */
 877 #define eo_base_data_get(key, data) EO_BASE_ID(EO_BASE_SUB_ID_DATA_GET), EO_TYPECHECK(const char *, key), EO_TYPECHECK(void **, data)
 878
 879 /**
 880  * @def eo_base_data_del(key)
 881  * Del generic data from object.
 882  * @param[in] key the key associated with the data
 883  *
 884  * @see #eo_base_data_set
 885  * @see #eo_base_data_get
 886  */
 887 #define eo_base_data_del(key) EO_BASE_ID(EO_BASE_SUB_ID_DATA_DEL), EO_TYPECHECK(const char *, key)
 888
 889 /**
 890  * @def eo_wref_add
 891  * @brief Add a new weak reference to obj.
 892  * @param wref The pointer to use for the weak ref.
 893  *
 894  * This function registers the object handle pointed by wref to obj so when
 895  * obj is deleted it'll be updated to NULL. This functions should be used
 896  * when you want to keep track of an object in a safe way, but you don't want
 897  * to prevent it from being freed.
 898  *
 899  * @see #eo_wref_del
 900  */
 901 #define eo_wref_add(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_ADD), EO_TYPECHECK(Eo **, wref)
 902
 903 /**
 904  * @def eo_wref_del
 905  * @brief Delete the weak reference passed.
 906  * @param wref the weak reference to free.
 907  *
 908  * @see #eo_wref_add
 909  */
 910 #define eo_wref_del(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_DEL), EO_TYPECHECK(Eo **, wref)
 911
 912 /**
 913  * @def eo_wref_del_safe
 914  * @brief Delete the weak reference passed.
 915  * @param wref the weak reference to free.
 916  *
 917  * Same as eo_wref_del(), with the different that it's not called from eobj_do()
 918  * so you don't need to check if *wref is not NULL.
 919  *
 920  * @see #eo_wref_del
 921  */
 922 #define eo_wref_del_safe(wref) \
 923    do { \
 924         if (*wref) eo_do(*wref, eo_wref_del(wref)); \
 925    } while (0)
 926
 927 /**
 928  * @var _EO_EV_CALLBACK_ADD
 929  * see EO_EV_CALLBACK_ADD
 930  */
 931 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_ADD;
 932
 933 /**
 934  * @def EO_EV_CALLBACK_ADD
 935  * The event description (of type #Eo_Event_Description) for
 936  * The "Callback listener added" event.
 937  */
 938 #define EO_EV_CALLBACK_ADD (&(_EO_EV_CALLBACK_ADD))
 939
 940 /**
 941  * @var _EO_EV_CALLBACK_DEL
 942  * see EO_EV_CALLBACK_DEL
 943  */
 944 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_DEL;
 945
 946 /**
 947  * @def EO_EV_CALLBACK_DEL
 948  * The event description (of type #Eo_Event_Description) for
 949  * The "Callback listener deleted" event.
 950  */
 951 #define EO_EV_CALLBACK_DEL (&(_EO_EV_CALLBACK_DEL))
 952
 953 /**
 954  * @var _EO_EV_FREE
 955  * see #EO_EV_FREE
 956  */
 957 EAPI extern const Eo_Event_Description _EO_EV_FREE;
 958
 959 /**
 960  * @def EO_EV_FREE
 961  * Object is being freed.
 962  */
 963 #define EO_EV_FREE (&(_EO_EV_FREE))
 964
 965 /**
 966  * @var _EO_EV_DEL
 967  * see #EO_EV_DEL
 968  */
 969 EAPI extern const Eo_Event_Description _EO_EV_DEL;
 970
 971 /**
 972  * @def EO_EV_DEL
 973  * Object is being deleted.
 974  */
 975 #define EO_EV_DEL (&(_EO_EV_DEL))
 976
 977 /**
 978  * @}
 979  */
 980
 981 /**
 982  * @}
 983  */
 984
 985 #endif