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; /**< #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; /**< #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 #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 #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 #EINA_TRUE if this call is on a constant object.
 418  * @param ... NULL terminated list of OPs and parameters.
 419  * @return #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 #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 #EINA_TRUE on success.
 450  *
 451  * Unlike eo_do() and eo_query(), this function only accepts one op.
 452  *
 453  * @see #eo_query
 454  * @see eo_query_super()
 455  */
 456 #define eo_do_super(obj, ...) eo_do_super_internal((Eo *) EO_TYPECHECK(const Eo *, 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 #EINA_TRUE if this call is on a constant object.
 462  * @param op The wanted op.
 463  * @param ... list of parameters.
 464  * @return #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 #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(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()
 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  *
 596  * @see eo_xunref()
 597  */
 598 EAPI Eo *eo_xref_internal(Eo *obj, const Eo *ref_obj, const char *file, int line);
 599
 600 /**
 601  * @brief Decrement the object's reference count by 1 and free it if needed. Will free the ref associated with ref_obj).
 602  * @param obj the object to work on.
 603  * @param ref_obj the object that references obj.
 604  *
 605  * This function only enforces the checks for object association. I.e don't rely
 606  * on it. If such enforces are compiled out, this function behaves the same as
 607  * eo_unref().
 608  *
 609  * @see eo_xref_internal()
 610  */
 611 EAPI void eo_xunref(Eo *obj, const Eo *ref_obj);
 612
 613 /**
 614  * @brief Delete the object passed (disregarding ref count).
 615  * @param obj the object to work on.
 616  *
 617  * @see eo_unref()
 618  */
 619 EAPI void eo_del(Eo *obj);
 620
 621 /**
 622  * @addtogroup Eo_Composite_Objects Composite Objects.
 623  * @{
 624  */
 625
 626 /**
 627  * @brief Make an object a composite object of another.
 628  * @param obj the "parent" object.
 629  * @param comp_obj the object that will be used to composite obj.
 630  *
 631  * @see eo_composite_object_detach()
 632  * @see eo_composite_is()
 633  */
 634 EAPI void eo_composite_object_attach(Eo *obj, Eo *comp_obj);
 635
 636 /**
 637  * @brief Detach a composite object from another object.
 638  * @param obj the "parent" object.
 639  * @param comp_obj the object attached to obj.
 640  *
 641  * @see eo_composite_object_attach()
 642  * @see eo_composite_is()
 643  */
 644 EAPI void eo_composite_object_detach(Eo *obj, Eo *comp_obj);
 645
 646 /**
 647  * @brief Check if an object is a composite object.
 648  * @param comp_obj the object to be checked.
 649  * @return #EINA_TRUE if it is, #EINA_FALSE otherwise.
 650  *
 651  * @see eo_composite_object_attach()
 652  * @see eo_composite_object_detach()
 653  */
 654 EAPI Eina_Bool eo_composite_is(Eo *comp_obj);
 655
 656 /**
 657  * @}
 658  */
 659
 660 /**
 661  * @addtogroup Eo_Events Eo's Event Handling
 662  * @{
 663  */
 664
 665 /**
 666  * @def EO_CALLBACK_PRIORITY_BEFORE
 667  * Slightly more prioritized than default.
 668  */
 669 #define EO_CALLBACK_PRIORITY_BEFORE -100
 670 /**
 671  * @def EO_CALLBACK_PRIORITY_DEFAULT
 672  * Default callback priority level
 673  */
 674 #define EO_CALLBACK_PRIORITY_DEFAULT 0
 675 /**
 676  * @def EO_CALLBACK_PRIORITY_AFTER
 677  * Slightly less prioritized than default.
 678  */
 679 #define EO_CALLBACK_PRIORITY_AFTER 100
 680
 681 /**
 682  * @typedef Eo_Callback_Priority
 683  *
 684  * Callback priority value. Range is -32k - 32k. The lower the number, the
 685  * higher the priority.
 686  *
 687  * @see EO_CALLBACK_PRIORITY_AFTER
 688  * @see EO_CALLBACK_PRIORITY_BEFORE
 689  * @see EO_CALLBACK_PRIORITY_DEFAULT
 690  */
 691 typedef short Eo_Callback_Priority;
 692
 693 /**
 694  * @def EO_CALLBACK_STOP
 695  * Stop calling callbacks for the even of which the callback was called for.
 696  * @see EO_CALLBACK_CONTINUE
 697  */
 698 #define EO_CALLBACK_STOP EINA_FALSE
 699
 700 /**
 701  * @def EO_CALLBACK_CONTINUE
 702  * Continue calling callbacks for the even of which the callback was called for.
 703  * @see EO_CALLBACK_STOP
 704  */
 705 #define EO_CALLBACK_CONTINUE EINA_TRUE
 706
 707 /**
 708  * @typedef Eo_Event_Cb
 709  *
 710  * An event callback prototype.
 711  *
 712  * @param data The user data registered with the callback.
 713  * @param obj The object which initiated the event.
 714  * @param desc The event's description.
 715  * @param event_info additional data passed with the event.
 716  * @return #EO_CALLBACK_STOP to stop calling additional callbacks for the event, #EO_CALLBACK_CONTINUE to continue.
 717  */
 718 typedef Eina_Bool (*Eo_Event_Cb)(void *data, Eo *obj, const Eo_Event_Description *desc, void *event_info);
 719
 720 /**
 721  * @brief Add an event callback forwarder for an event and an object.
 722  * @param obj The object to listen to events on.
 723  * @param desc The description of the event to listen to.
 724  * @param new_obj The object to emit events from.
 725  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 726  *
 727  * @see eo_event_callback_forwarder_del()
 728  */
 729 EAPI Eina_Bool eo_event_callback_forwarder_add(Eo *obj, const Eo_Event_Description *desc, Eo *new_obj);
 730
 731 /**
 732  * @brief Remove an event callback forwarder for an event and an object.
 733  * @param obj The object to listen to events on.
 734  * @param desc The description of the event to listen to.
 735  * @param new_obj The object to emit events from.
 736  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 737  *
 738  * @see eo_event_callback_forwarder_add()
 739  */
 740 EAPI Eina_Bool eo_event_callback_forwarder_del(Eo *obj, const Eo_Event_Description *desc, Eo *new_obj);
 741
 742 /**
 743  * @def eo_event_callback_add(obj, desc, cb, data)
 744  * Add a callback for an event.
 745  * @param obj The object to listen to events on.
 746  * @param desc The description of the event to listen to.
 747  * @param cb the callback to call.
 748  * @param data additional data to pass to the callback.
 749  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 750  *
 751  * callbacks of the same priority are called in reverse order of creation.
 752  *
 753  * @see eo_event_callback_priority_add()
 754  */
 755 #define eo_event_callback_add(obj, desc, cb, data) \
 756    eo_event_callback_priority_add(obj, desc, \
 757          EO_CALLBACK_PRIORITY_DEFAULT, cb, data)
 758
 759 /**
 760  * @brief Add a callback for an event with a specific priority.
 761  * @param obj The object to listen to events on.
 762  * @param desc The description of the event to listen to.
 763  * @param priority The priority of the callback.
 764  * @param cb the callback to call.
 765  * @param data additional data to pass to the callback.
 766  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 767  *
 768  * callbacks of the same priority are called in reverse order of creation.
 769  *
 770  * @see #eo_event_callback_add
 771  */
 772 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);
 773
 774 /**
 775  * @brief Del a callback for an event
 776  * @param obj The object to listen to delete from.
 777  * @param desc The description of the event to listen to.
 778  * @param func the callback to delete.
 779  * @return The additional data that was set to be passed to the callback.
 780  *
 781  * @see eo_event_callback_del()
 782  */
 783 EAPI void *eo_event_callback_del_lazy(Eo *obj, const Eo_Event_Description *desc, Eo_Event_Cb func);
 784
 785 /**
 786  * @brief Del a callback with a specific data associated to it for an event.
 787  * @param obj The object to listen to delete from.
 788  * @param desc The description of the event to listen to.
 789  * @param func the callback to delete.
 790  * @param user_data The data to compare.
 791  * @return The additional data that was set to be passed to the callback.
 792  *
 793  * @see eo_event_callback_del_lazy()
 794  */
 795 EAPI void *eo_event_callback_del(Eo *obj, const Eo_Event_Description *desc, Eo_Event_Cb func, const void *user_data);
 796
 797 /**
 798  * @brief Call the callbacks for an event of an object.
 799  * @param obj The object to work on.
 800  * @param desc The description of the event to call.
 801  * @param event_info Extra event info to pass to the callbacks.
 802  * @return #EINA_FALSE if one of the callbacks aborted the callback calls or #EINA_TRUE otherwise.
 803  */
 804 EAPI Eina_Bool eo_event_callback_call(Eo *obj, const Eo_Event_Description *desc, const void *event_info);
 805
 806 /**
 807  * @}
 808  */
 809
 810 /**
 811  * @addtogroup Eo_Class_Base Eo's Base class.
 812  * @{
 813  */
 814
 815 /**
 816  * @def EO_BASE_CLASS
 817  * The class type for the Eo base class.
 818  */
 819 #define EO_BASE_CLASS eo_base_class_get()
 820 /**
 821  * @brief Use #EO_BASE_CLASS
 822  * @internal
 823  * */
 824 EAPI const Eo_Class *eo_base_class_get(void) EINA_CONST;
 825
 826 /**
 827  * @typedef eo_base_data_free_func
 828  * Data free func prototype.
 829  */
 830 typedef void (*eo_base_data_free_func)(void *);
 831
 832 /**
 833  * @var EO_BASE_BASE_ID
 834  * #EO_BASE_CLASS 's base id.
 835  */
 836 extern EAPI Eo_Op EO_BASE_BASE_ID;
 837
 838 enum {
 839      EO_BASE_SUB_ID_DATA_SET,
 840      EO_BASE_SUB_ID_DATA_GET,
 841      EO_BASE_SUB_ID_DATA_DEL,
 842      EO_BASE_SUB_ID_WREF_ADD,
 843      EO_BASE_SUB_ID_WREF_DEL,
 844      EO_BASE_SUB_ID_LAST
 845 };
 846
 847 /**
 848  * @def EO_BASE_ID(sub_id)
 849  * Helper macro to get the full Op ID out of the sub_id for EO_BASE.
 850  * @param sub_id the sub id inside EO_BASE.
 851  */
 852 #define EO_BASE_ID(sub_id) (EO_BASE_BASE_ID + sub_id)
 853
 854 /**
 855  * @def eo_base_data_set(key, data, free_func)
 856  * Set generic data to object.
 857  * @param[in] key the key associated with the data
 858  * @param[in] data the data to set.
 859  * @param[in] free_func the func to free data with (NULL means "do nothing").
 860  *
 861  * @see #eo_base_data_get
 862  * @see #eo_base_data_del
 863  */
 864 #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)
 865
 866 /**
 867  * @def eo_base_data_get(key, data)
 868  * Get generic data from object.
 869  * @param[in] key the key associated with the data
 870  * @param[out] data the data for the key
 871  *
 872  * @see #eo_base_data_set
 873  * @see #eo_base_data_del
 874  */
 875 #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)
 876
 877 /**
 878  * @def eo_base_data_del(key)
 879  * Del generic data from object.
 880  * @param[in] key the key associated with the data
 881  *
 882  * @see #eo_base_data_set
 883  * @see #eo_base_data_get
 884  */
 885 #define eo_base_data_del(key) EO_BASE_ID(EO_BASE_SUB_ID_DATA_DEL), EO_TYPECHECK(const char *, key)
 886
 887 /**
 888  * @def eo_wref_add
 889  * @brief Add a new weak reference to obj.
 890  * @param wref The pointer to use for the weak ref.
 891  *
 892  * This function registers the object handle pointed by wref to obj so when
 893  * obj is deleted it'll be updated to NULL. This functions should be used
 894  * when you want to keep track of an object in a safe way, but you don't want
 895  * to prevent it from being freed.
 896  *
 897  * @see #eo_wref_del
 898  */
 899 #define eo_wref_add(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_ADD), EO_TYPECHECK(Eo **, wref)
 900
 901 /**
 902  * @def eo_wref_del
 903  * @brief Delete the weak reference passed.
 904  * @param wref the weak reference to free.
 905  *
 906  * @see #eo_wref_add
 907  */
 908 #define eo_wref_del(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_DEL), EO_TYPECHECK(Eo **, wref)
 909
 910 /**
 911  * @var _EO_EV_CALLBACK_ADD
 912  * see EO_EV_CALLBACK_ADD
 913  */
 914 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_ADD;
 915
 916 /**
 917  * @def EO_EV_CALLBACK_ADD
 918  * The event description (of type #Eo_Event_Description) for
 919  * The "Callback listener added" event.
 920  */
 921 #define EO_EV_CALLBACK_ADD (&(_EO_EV_CALLBACK_ADD))
 922
 923 /**
 924  * @var _EO_EV_CALLBACK_DEL
 925  * see EO_EV_CALLBACK_DEL
 926  */
 927 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_DEL;
 928
 929 /**
 930  * @def EO_EV_CALLBACK_DEL
 931  * The event description (of type #Eo_Event_Description) for
 932  * The "Callback listener deleted" event.
 933  */
 934 #define EO_EV_CALLBACK_DEL (&(_EO_EV_CALLBACK_DEL))
 935
 936 /**
 937  * @var _EO_EV_FREE
 938  * see #EO_EV_FREE
 939  */
 940 EAPI extern const Eo_Event_Description _EO_EV_FREE;
 941
 942 /**
 943  * @def EO_EV_FREE
 944  * Object is being freed.
 945  */
 946 #define EO_EV_FREE (&(_EO_EV_FREE))
 947
 948 /**
 949  * @var _EO_EV_DEL
 950  * see #EO_EV_DEL
 951  */
 952 EAPI extern const Eo_Event_Description _EO_EV_DEL;
 953
 954 /**
 955  * @def EO_EV_DEL
 956  * Object is being deleted.
 957  */
 958 #define EO_EV_DEL (&(_EO_EV_DEL))
 959
 960 /**
 961  * @}
 962  */
 963
 964 /**
 965  * @}
 966  */
 967
 968 #endif