src/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 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @var _eo_class_creation_lock
  39  * This variable is used for locking purposes in the class_get function
  40  * defined in #EO_DEFINE_CLASS.
  41  * This is just to work around the fact that we need to init locks before
  42  * using them.
  43  * Don't touch it if you don't know what you are doing.
  44  * @internal
  45  */
  46 EAPI extern Eina_Lock _eo_class_creation_lock;
  47
  48 /**
  49  * @internal
  50  * An enum representing the possible types of an Op.
  51  */
  52 enum _Eo_Op_Type
  53 {
  54    EO_OP_TYPE_INVALID = -1, /**< Invalid op. */
  55    EO_OP_TYPE_REGULAR = 0, /**< Regular op. */
  56    EO_OP_TYPE_CLASS, /**< Class op - a class op. Like static in Java/C++. */
  57 };
  58
  59 /**
  60  * @internal
  61  * @typedef Eo_Op_Type
  62  * A convenience typedef for #_Eo_Op_Type.
  63  */
  64 typedef enum _Eo_Op_Type Eo_Op_Type;
  65
  66 /**
  67  * @defgroup Eo Eo Generic Object System
  68  *
  69  * The Eo generic object system. It was designed to be the base object
  70  * system for the EFL.
  71  *
  72  * @{
  73  */
  74
  75 /**
  76  * @def EO_TYPECHECK(type, x)
  77  *
  78  * Checks x is castable to type "type" and casts it to it.
  79  * @param type The C type to check against.
  80  * @param x the variable to test and cast.
  81  */
  82 #define EO_TYPECHECK(type, x) \
  83    ({ \
  84     type __x; \
  85     __x = x; \
  86     (type) __x; \
  87     })
  88
  89 /**
  90  * @typedef Eo
  91  * The basic Object type.
  92  */
  93 typedef struct _Eo Eo;
  94 /**
  95  * @typedef Eo_Op
  96  * The Eo operation type id.
  97  */
  98 typedef unsigned int Eo_Op;
  99
 100 /**
 101  * @typedef Eo_Class
 102  * The basic Object class type.
 103  * @ingroup Eo_Class
 104  */
 105 typedef struct _Eo_Class Eo_Class;
 106
 107 /**
 108  * @typedef Eo_Class_Id
 109  * An Id of a class.
 110  * @ingroup Eo_Class
 111  */
 112 typedef size_t Eo_Class_Id;
 113
 114 /**
 115  * @def EO_NOOP
 116  * A special #Eo_Op meaning "No operation".
 117  */
 118 #define EO_NOOP ((Eo_Op) 0)
 119
 120 /**
 121  * @typedef eo_op_func_type
 122  * The type of the Op functions. This is the type of the functions used by
 123  * Eo.
 124  *
 125  * @see eo_op_func_type_class
 126  */
 127 typedef void (*eo_op_func_type)(Eo *, void *class_data, va_list *list);
 128
 129 /**
 130  * @typedef eo_op_func_type_class
 131  * The type of the class Op functions. This is the same as #eo_op_func_type,\
 132  * exepct that it's for usage with class functions, and not with object
 133  * functions.
 134  *
 135  * @see eo_op_func_type
 136  */
 137 typedef void (*eo_op_func_type_class)(const Eo_Class *, va_list *list);
 138
 139 /**
 140  * @addtogroup Eo_Events Eo's Event Handling
 141  * @{
 142  */
 143
 144 /**
 145  * @struct _Eo_Event_Description
 146  * This struct holds the description of a specific event.
 147  */
 148 struct _Eo_Event_Description
 149 {
 150    const char *name; /**< name of the event. */
 151    const char *doc; /**< Explanation about the event. */
 152 };
 153
 154 /**
 155  * @typedef Eo_Event_Description
 156  * A convenience typedef for #_Eo_Event_Description
 157  */
 158 typedef struct _Eo_Event_Description Eo_Event_Description;
 159
 160 /**
 161  * @def EO_EVENT_DESCRIPTION(name, doc)
 162  * An helper macro to help populating #Eo_Event_Description
 163  * @param name The name of the event.
 164  * @param doc Additional doc for the event.
 165  * @see Eo_Event_Description
 166  */
 167 #define EO_EVENT_DESCRIPTION(name, doc) { name, doc }
 168
 169 /**
 170  * @}
 171  */
 172
 173 /**
 174  * @addtogroup Eo_Class Eo Class
 175  * @{
 176  */
 177
 178 /**
 179  * @def EO_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...)
 180  * A convenience macro to be used for creating the class_get function. This
 181  * macro is fairly simple but should still be used as it'll let us improve
 182  * things easily.
 183  * @param class_get_func_name the name of the wanted class_get function name.
 184  * @param class_desc the class description.
 185  * @param parent_class The parent class for the function. Look at eo_class_new() for more information.
 186  * @param ... List of etxensions. Look at eo_class_new() for more information.
 187  *
 188  * You must use this macro if you want thread safety in class creation.
 189  */
 190 #define EO_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...) \
 191 EAPI const Eo_Class * \
 192 class_get_func_name(void) \
 193 { \
 194    const Eo_Class *_tmp_parent_class; \
 195    static volatile char lk_init = 0; \
 196    static Eina_Lock _my_lock; \
 197    static const Eo_Class * volatile _my_class = NULL; \
 198    if (EINA_LIKELY(!!_my_class)) return _my_class; \
 199    \
 200    eina_lock_take(&_eo_class_creation_lock); \
 201    if (!lk_init) \
 202       eina_lock_new(&_my_lock); \
 203    if (lk_init < 2) eina_lock_take(&_my_lock); \
 204    if (!lk_init) \
 205       lk_init = 1; \
 206    else \
 207      { \
 208         if (lk_init < 2) eina_lock_release(&_my_lock); \
 209         eina_lock_release(&_eo_class_creation_lock); \
 210         return _my_class; \
 211      } \
 212    eina_lock_release(&_eo_class_creation_lock); \
 213    _tmp_parent_class = parent_class; \
 214    _my_class = eo_class_new(class_desc, _tmp_parent_class, __VA_ARGS__); \
 215    eina_lock_release(&_my_lock); \
 216    \
 217    eina_lock_take(&_eo_class_creation_lock); \
 218    eina_lock_free(&_my_lock); \
 219    lk_init = 2; \
 220    eina_lock_release(&_eo_class_creation_lock); \
 221    return _my_class; \
 222 }
 223
 224
 225 /**
 226  * An enum representing the possible types of an Eo class.
 227  */
 228 enum _Eo_Class_Type
 229 {
 230    EO_CLASS_TYPE_REGULAR = 0, /**< Regular class. */
 231    EO_CLASS_TYPE_REGULAR_NO_INSTANT, /**< Regular non instant-able class. */
 232    EO_CLASS_TYPE_INTERFACE, /**< Interface */
 233    EO_CLASS_TYPE_MIXIN /**< Mixin */
 234 };
 235
 236 /**
 237  * @typedef Eo_Class_Type
 238  * A convenience typedef for #_Eo_Class_Type.
 239  */
 240 typedef enum _Eo_Class_Type Eo_Class_Type;
 241
 242 /**
 243  * @struct _Eo_Op_Func_Description
 244  * Used to associate an Op with a func.
 245  * @see eo_class_funcs_set
 246  */
 247 struct _Eo_Op_Func_Description
 248 {
 249    Eo_Op op; /**< The op */
 250    eo_op_func_type func; /**< The function to call for the op. */
 251    Eo_Op_Type op_type; /**< The type of the op */
 252 };
 253
 254 /**
 255  * @typedef Eo_Op_Func_Description
 256  * A convenience typedef for #_Eo_Op_Func_Description
 257  */
 258 typedef struct _Eo_Op_Func_Description Eo_Op_Func_Description;
 259
 260 /**
 261  * @def EO_OP_FUNC(op, func)
 262  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 263  * array.
 264  */
 265 #define EO_OP_FUNC(op, func) { op, EO_TYPECHECK(eo_op_func_type, func), EO_OP_TYPE_REGULAR }
 266
 267 /**
 268  * @def EO_OP_FUNC_CLASS(op, func)
 269  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 270  * array.
 271  * The same as #EO_OP_FUNC but for class functions.
 272  *
 273  * @see EO_OP_FUNC
 274  */
 275 #define EO_OP_FUNC_CLASS(op, func) { op, (eo_op_func_type) EO_TYPECHECK(eo_op_func_type_class, func), EO_OP_TYPE_CLASS }
 276
 277 /**
 278  * @def EO_OP_FUNC_SENTINEL
 279  * A convenience macro to be used when populating the #Eo_Op_Func_Description
 280  * array. It must appear at the end of the ARRAY.
 281  */
 282 #define EO_OP_FUNC_SENTINEL { 0, NULL, EO_OP_TYPE_INVALID }
 283
 284 /**
 285  * @struct _Eo_Op_Description
 286  * This struct holds the description of a specific op.
 287  */
 288 struct _Eo_Op_Description
 289 {
 290    Eo_Op sub_op; /**< The sub_id of the op in it's class. */
 291    const char *name; /**< The name of the op. */
 292    const char *doc; /**< Explanation about the Op. */
 293    Eo_Op_Type op_type; /**< The type of the Op. */
 294 };
 295
 296 /**
 297  * @typedef Eo_Op_Description
 298  * A convenience typedef for #_Eo_Op_Description
 299  */
 300 typedef struct _Eo_Op_Description Eo_Op_Description;
 301
 302 /**
 303  * @def EO_VERSION
 304  * The current version of EO.
 305  */
 306 #define EO_VERSION 1
 307
 308 /**
 309  * @struct _Eo_Class_Description
 310  * This struct holds the description of a class.
 311  * This description should be passed to eo_class_new.
 312  * Please use the #EO_CLASS_DESCRIPTION_OPS macro when populating it.
 313  */
 314 struct _Eo_Class_Description
 315 {
 316    unsigned int version; /**< The current version of eo, use #EO_VERSION */
 317    const char *name; /**< The name of the class. */
 318    Eo_Class_Type type; /**< The type of the class. */
 319    struct {
 320         Eo_Op *base_op_id;
 321         const Eo_Op_Description *descs;
 322         size_t count;
 323    } ops; /**< The ops description, should be filled using #EO_CLASS_DESCRIPTION_OPS */
 324    const Eo_Event_Description **events; /**< The event descriptions for this class. */
 325    size_t data_size; /**< The size of data (private + protected + public) this class needs per object. */
 326    void (*class_constructor)(Eo_Class *klass); /**< The constructor of the class. */
 327    void (*class_destructor)(Eo_Class *klass); /**< The destructor of the class. */
 328 };
 329
 330 /**
 331  * @typedef Eo_Class_Description
 332  * A convenience typedef for #_Eo_Class_Description
 333  */
 334 typedef struct _Eo_Class_Description Eo_Class_Description;
 335
 336 /**
 337  * @def EO_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count)
 338  * An helper macro to help populating #Eo_Class_Description.
 339  * @param base_op_id A pointer to the base op id of the class.
 340  * @param op_descs the op descriptions array.
 341  * @param count the number of ops in the op descriptions array.
 342  */
 343 #define EO_CLASS_DESCRIPTION_OPS(base_op_id, op_descs, count) { base_op_id, op_descs, count }
 344
 345 /**
 346  * @def EO_OP_DESCRIPTION(op, doc)
 347  * An helper macro to help populating #Eo_Op_Description
 348  * @param sub_id The sub id of the op being described.
 349  * @param doc Additional doc for the op.
 350  * @see Eo_Op_Description
 351  * @see EO_OP_DESCRIPTION_CLASS
 352  * @see EO_OP_DESCRIPTION_SENTINEL
 353  */
 354 #define EO_OP_DESCRIPTION(sub_id, doc) { sub_id, #sub_id, doc, EO_OP_TYPE_REGULAR }
 355
 356 /**
 357  * @def EO_OP_DESCRIPTION_CLASS(op, doc)
 358  * An helper macro to help populating #Eo_Op_Description
 359  * This macro is the same as EO_OP_DESCRIPTION but indicates that the op's
 360  * implementation is of type CLASS.
 361  * @param sub_id The sub id of the op being described.
 362  * @param doc Additional doc for the op.
 363  * @see Eo_Op_Description
 364  * @see EO_OP_DESCRIPTION
 365  * @see EO_OP_DESCRIPTION_SENTINEL
 366  */
 367 #define EO_OP_DESCRIPTION_CLASS(sub_id, doc) { sub_id, #sub_id, doc, EO_OP_TYPE_CLASS }
 368
 369 /**
 370  * @def EO_OP_DESCRIPTION_SENTINEL
 371  * An helper macro to help populating #Eo_Op_Description
 372  * Should be placed at the end of the array.
 373  * @see Eo_Op_Description
 374  * @see EO_OP_DESCRIPTION
 375  */
 376 #define EO_OP_DESCRIPTION_SENTINEL { 0, NULL, NULL, EO_OP_TYPE_INVALID }
 377
 378 /**
 379  * @brief Create a new class.
 380  * @param desc the class description to create the class with.
 381  * @param parent the class to inherit from.
 382  * @param ... A NULL terminated list of extensions (interfaces, mixins and the classes of any composite objects).
 383  * @return The new class's handle on success, or NULL otherwise.
 384  *
 385  * You should use #EO_DEFINE_CLASS. It'll provide thread safety and other
 386  * features easily.
 387  *
 388  * @see #EO_DEFINE_CLASS
 389  */
 390 EAPI const Eo_Class *eo_class_new(const Eo_Class_Description *desc, const Eo_Class *parent, ...);
 391
 392 /**
 393  * @brief Check if an object "is a" klass.
 394  * @param obj The object to check
 395  * @param klass The klass to check against.
 396  * @return @c EINA_TRUE if obj implements klass, @c EINA_FALSE otherwise.
 397  *
 398  * Notice: This function does not support composite objects.
 399  */
 400 EAPI Eina_Bool eo_isa(const Eo *obj, const Eo_Class *klass);
 401
 402 /**
 403  * @brief Sets the OP functions for a class.
 404  * @param klass the class to set the functions to.
 405  * @param func_descs a NULL terminated array of #Eo_Op_Func_Description
 406  *
 407  * Should be called from within the class constructor.
 408  */
 409 EAPI void eo_class_funcs_set(Eo_Class *klass, const Eo_Op_Func_Description *func_descs);
 410
 411 /**
 412  * @brief Gets the name of the passed class.
 413  * @param klass the class to work on.
 414  * @return The class's name.
 415  *
 416  * @see eo_class_get()
 417  */
 418 EAPI const char *eo_class_name_get(const Eo_Class *klass);
 419
 420 /**
 421  * @}
 422  */
 423
 424 /**
 425  * @brief Init the eo subsystem
 426  * @return @c EINA_TRUE on success.
 427  *
 428  * @see eo_shutfown()
 429  */
 430 EAPI Eina_Bool eo_init(void);
 431
 432 /**
 433  * @brief Shutdown the eo subsystem
 434  * @return @c EINA_TRUE on success.
 435  *
 436  * @see eo_init()
 437  */
 438 EAPI Eina_Bool eo_shutdown(void);
 439
 440 /**
 441  * @def eo_do
 442  * A convenience wrapper around eo_do_internal()
 443  * @see eo_do_internal
 444  */
 445 #define eo_do(obj, ...) eo_do_internal(obj, EO_OP_TYPE_REGULAR, __VA_ARGS__, EO_NOOP)
 446
 447 /**
 448  * @def eo_class_do
 449  * A convenience wrapper around eo_class_do_internal()
 450  * @see eo_class_do_internal
 451  */
 452 #define eo_class_do(klass, ...) eo_class_do_internal(klass, __VA_ARGS__, EO_NOOP)
 453
 454 /**
 455  * @brief Calls op functions of an object
 456  * @param obj The object to work on
 457  * @param op_type The type of the ops that are passed.
 458  * @param ... NULL terminated list of OPs and parameters.
 459  * @return @c EINA_TRUE on success.
 460  *
 461  * Use the helper macros, don't pass the parameters manually.
 462  * Use #eo_do instead of this function.
 463  *
 464  * @see #eo_do
 465  */
 466 EAPI Eina_Bool eo_do_internal(Eo *obj, Eo_Op_Type op_type, ...);
 467
 468 /**
 469  * @brief Calls op functions of a class.
 470  * @param klass The class to work on
 471  * @param ... NULL terminated list of OPs and parameters.
 472  * @return @c EINA_TRUE on success.
 473  *
 474  * Use the helper macros, don't pass the parameters manually.
 475  * Use #eo_do instead of this function.
 476  *
 477  * @see #eo_class_do
 478  */
 479 EAPI Eina_Bool eo_class_do_internal(const Eo_Class *klass, ...);
 480
 481 /**
 482  * @brief Calls the super function for the specific op.
 483  * @param obj The object to work on
 484  * @param ... list of parameters.
 485  * @return @c EINA_TRUE on success.
 486  *
 487  * Unlike eo_do(), this function only accepts one op.
 488  *
 489  * @see #eo_do
 490  */
 491 #define eo_do_super(obj, ...) eo_do_super_internal(obj, EO_OP_TYPE_REGULAR, __VA_ARGS__)
 492
 493 /**
 494  * @brief Calls the super function for the specific op.
 495  * @param klass The klass to work on
 496  * @param ... list of parameters.
 497  * @return @c EINA_TRUE on success.
 498  *
 499  * Unlike eo_class_do(), this function only accepts one op.
 500  *
 501  * @see #eo_class_do
 502  */
 503 #define eo_class_do_super(klass, ...) eo_class_do_super_internal(klass, __VA_ARGS__)
 504
 505 /**
 506  * @brief Calls the super function for the specific op.
 507  * @param obj The object to work on
 508  * @param op_type The type of the ops that are passed.
 509  * @param op The wanted op.
 510  * @param ... list of parameters.
 511  * @return @c EINA_TRUE on success.
 512  *
 513  * Don't use this function, use the wrapping macros instead.
 514  *
 515  * @see #eo_do
 516  * @see #eo_do_super
 517  */
 518 EAPI Eina_Bool eo_do_super_internal(Eo *obj, Eo_Op_Type op_type, Eo_Op op, ...);
 519
 520 /**
 521  * @brief Calls the super function for the specific op.
 522  * @param klass The klass to work on
 523  * @param op The wanted op.
 524  * @param ... list of parameters.
 525  * @return @c EINA_TRUE on success.
 526  *
 527  * Don't use this function, use the wrapping macros instead.
 528  *
 529  * @see #eo_class_do
 530  * @see #eo_class_do_super
 531  */
 532 EAPI Eina_Bool eo_class_do_super_internal(const Eo_Class *klass, Eo_Op op, ...);
 533
 534 /**
 535  * @brief Gets the class of the object.
 536  * @param obj The object to work on
 537  * @return The object's class.
 538  *
 539  * @see eo_class_name_get()
 540  */
 541 EAPI const Eo_Class *eo_class_get(const Eo *obj);
 542
 543 /**
 544  * @def eo_error_set
 545  * @brief Notify eo that there was an error when constructing, destructing or calling a function of the object.
 546  * @param obj the object to work on.
 547  *
 548  * @see eo_error_get()
 549  */
 550 #define eo_error_set(obj) eo_error_set_internal(obj, __FILE__, __LINE__)
 551
 552 /* @cond 0 */
 553 EAPI void eo_error_set_internal(const Eo *obj, const char *file, int line);
 554 /* @endcond */
 555
 556 /**
 557  * @def eo_add
 558  * @brief Create a new object with the default constructor.
 559  * @param klass the class of the object to create.
 560  * @param parent the parent to set to the object.
 561  * @param ... The ops to run.
 562  * @return An handle to the new object on success, NULL otherwise.
 563  *
 564  * @see #eo_add_custom
 565  */
 566 #define eo_add(klass, parent, ...) \
 567    ({ \
 568     const Eo_Class *_tmp_klass = klass; \
 569     eo_add_internal(_tmp_klass, parent, eo_constructor(), ## __VA_ARGS__, EO_NOOP); \
 570     })
 571
 572 /**
 573  * @def eo_add_custom
 574  * @brief Create a new object with a custom constructor.
 575  * @param klass the class of the object to create.
 576  * @param parent the parent to set to the object.
 577  * @param ... The ops to run. With the constructor being first.
 578  * @return An handle to the new object on success, NULL otherwise.
 579  *
 580  * @see #eo_add
 581  */
 582 #define eo_add_custom(klass, parent, ...) \
 583    ({ \
 584     const Eo_Class *_tmp_klass = klass; \
 585     eo_add_internal(_tmp_klass, parent, ## __VA_ARGS__, EO_NOOP); \
 586     })
 587
 588 /**
 589  * @brief Create a new object.
 590  * @param klass the class of the object to create.
 591  * @param parent the parent to set to the object.
 592  * @param ... The ops to run. With the constructor being first.
 593  * @return An handle to the new object on success, NULL otherwise.
 594  *
 595  * Use the helper macros, don't pass the parameters manually.
 596  * Use #eo_add or #eo_add_custom instead of this function.
 597  *
 598  * @see #eo_add
 599  */
 600 EAPI Eo *eo_add_internal(const Eo_Class *klass, Eo *parent, ...);
 601
 602 /**
 603  * @brief Get the parent of an object
 604  * @param obj the object to get the parent of.
 605  * @return a pointer to the parent object.
 606  *
 607  * @see eo_parent_set()
 608  */
 609 EAPI Eo *eo_parent_get(const Eo *obj);
 610
 611 /**
 612  * @brief Set the parent of an object
 613  * @param obj the object to get the parent of.
 614  * @param parent the new parent.
 615  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure.
 616  *
 617  * Parents keep references to their children so in order to delete objects
 618  * that have parents you need to set parent to NULL or use eo_del() that
 619  * does that for you (and also unrefs the object).
 620  *
 621  * @see eo_del()
 622  * @see eo_parent_get()
 623  */
 624 EAPI Eina_Bool eo_parent_set(Eo *obj, const Eo *parent);
 625
 626 /**
 627  * @brief Get a pointer to the data of an object for a specific class.
 628  * @param obj the object to work on.
 629  * @param klass the klass associated with the data.
 630  * @return a pointer to the data.
 631  */
 632 EAPI void *eo_data_get(const Eo *obj, const Eo_Class *klass);
 633
 634 /**
 635  * @brief Increment the object's reference count by 1.
 636  * @param obj the object to work on.
 637  * @return The object passed.
 638  *
 639  * It's very easy to get a refcount leak and start leaking memory because
 640  * of a forgotten unref or an extra ref. That is why there are eo_xref
 641  * and eo_xunref that will make debugging easier in such a case.
 642  * Therefor, these functions should only be used in small scopes, i.e at the
 643  * start of some section in which the object may get freed, or if you know
 644  * what you are doing.
 645  *
 646  * @see eo_unref()
 647  * @see eo_ref_get()
 648  */
 649 EAPI Eo *eo_ref(const Eo *obj);
 650
 651 /**
 652  * @brief Decrement the object's reference count by 1 and free it if needed.
 653  * @param obj the object to work on.
 654  *
 655  * @see eo_ref()
 656  * @see eo_ref_get()
 657  */
 658 EAPI void eo_unref(const Eo *obj);
 659
 660 /**
 661  * @brief Return the ref count of the object passed.
 662  * @param obj the object to work on.
 663  * @return the ref count of the object.
 664  *
 665  * @see eo_ref()
 666  * @see eo_unref()
 667  */
 668 EAPI int eo_ref_get(const Eo *obj);
 669
 670 /**
 671  * @brief Unrefs the object and reparents it to NULL.
 672  * @param obj the object to work on.
 673  *
 674  * Because eo_del() unrefs and reparents to NULL, it doesn't really delete the
 675  * object.
 676  *
 677  * @see eo_unref()
 678  * @see eo_parent_set()
 679  */
 680 EAPI void eo_del(const Eo *obj);
 681
 682 /**
 683  * @def eo_xref(obj, ref_obj)
 684  * Convenience macro around eo_xref_internal()
 685  * @see eo_xref()
 686  */
 687 #define eo_xref(obj, ref_obj) eo_xref_internal(obj, ref_obj, __FILE__, __LINE__)
 688
 689 /**
 690  * @brief Increment the object's reference count by 1 (and associate the ref with ref_obj)
 691  * @param obj the object to work on.
 692  * @param ref_obj the object that references obj.
 693  * @param file the call's filename.
 694  * @param line the call's line number.
 695  * @return The object passed (obj)
 696  *
 697  * People should not use this function, use #eo_xref instead.
 698  * A compile flag my make it and eobj_xunref() behave the same as eobj_ref()
 699  * and eobj_unref() respectively. So this should be used wherever possible.
 700  *
 701  * @see eo_xunref()
 702  */
 703 EAPI Eo *eo_xref_internal(Eo *obj, const Eo *ref_obj, const char *file, int line);
 704
 705 /**
 706  * @brief Decrement the object's reference count by 1 and free it if needed. Will free the ref associated with ref_obj).
 707  * @param obj the object to work on.
 708  * @param ref_obj the object that references obj.
 709  *
 710  * This function only enforces the checks for object association. I.e don't rely
 711  * on it. If such enforces are compiled out, this function behaves the same as
 712  * eo_unref().
 713  *
 714  * @see eo_xref_internal()
 715  */
 716 EAPI void eo_xunref(Eo *obj, const Eo *ref_obj);
 717
 718 /**
 719  * @brief Enable or disable the manual free feature.
 720  * @param obj the object to work on.
 721  * @param manual_free indicates if the free is manual (EINA_TRUE) or automatic (EINA_FALSE).
 722  *
 723  * The developer is in charge to call the function eo_manual_free to free the memory allocated for this object.
 724  *
 725  * Do not use, unless you really know what you are doing. It's used by Evas
 726  * because evas wants to keep its private data available even after the object
 727  * is deleted. Setting this to true makes Eo destruct the object but not free
 728  * the private data or the object itself.
 729  *
 730  * @see eo_manual_free()
 731  */
 732 EAPI void eo_manual_free_set(Eo *obj, Eina_Bool manual_free);
 733
 734 /**
 735  * @brief Frees the object.
 736  * @param obj the object to work on.
 737  * This function must be called by the developer if the function
 738  * eo_manual_free_set has been called before with the parameter EINA_TRUE.
 739  * An error will be printed if this function is called when the manual
 740  * free option is not set to EINA_TRUE or the number of refs is not 0.
 741  *
 742  * @see eo_manual_free_set()
 743  */
 744 EAPI void eo_manual_free(Eo *obj);
 745
 746 /**
 747  * @brief Checks if the object was already descructed (only relevant for manual_free objects).
 748  * @param obj the object to check.
 749  * This function checks if the object was already destructed (but not alraedy
 750  * freed). It should only be used with objects that are supposed to be manually
 751  * freed, but not yet freed (but possibly destructed).
 752  *
 753  * @see eo_manual_free_set()
 754  */
 755 EAPI Eina_Bool eo_destructed_is(const Eo *obj);
 756
 757 /**
 758  * @addtogroup Eo_Composite_Objects Composite Objects.
 759  * @{
 760  */
 761
 762 /**
 763  * @brief Make an object a composite object of another.
 764  * @param comp_obj the object that will be used to composite parent.
 765  * @param parent the "parent" object.
 766  *
 767  * This functions also sets the parent of comp_obj to parent.
 768  *
 769  * @see eo_composite_detach()
 770  * @see eo_composite_is()
 771  */
 772 EAPI void eo_composite_attach(Eo *comp_obj, Eo *parent);
 773
 774 /**
 775  * @brief Detach a composite object from another object.
 776  * @param comp_obj the object attached to parent.
 777  * @param parent the "parent" object.
 778  *
 779  * This functions also sets the parent of comp_obj to @c NULL.
 780  *
 781  * @see eo_composite_attach()
 782  * @see eo_composite_is()
 783  */
 784 EAPI void eo_composite_detach(Eo *comp_obj, Eo *parent);
 785
 786 /**
 787  * @brief Check if an object is a composite object.
 788  * @param comp_obj the object to be checked.
 789  * @return @c EINA_TRUE if it is, @c EINA_FALSE otherwise.
 790  *
 791  * @see eo_composite_attach()
 792  * @see eo_composite_detach()
 793  */
 794 EAPI Eina_Bool eo_composite_is(const Eo *comp_obj);
 795
 796 /**
 797  * @}
 798  */
 799
 800 /**
 801  * @addtogroup Eo_Class_Base Eo's Base class.
 802  * @{
 803  */
 804
 805 /**
 806  * @def EO_BASE_CLASS
 807  * The class type for the Eo base class.
 808  */
 809 #define EO_BASE_CLASS eo_base_class_get()
 810 /**
 811  * @brief Use #EO_BASE_CLASS
 812  * @internal
 813  * */
 814 EAPI const Eo_Class *eo_base_class_get(void);
 815
 816 /**
 817  * @typedef eo_base_data_free_func
 818  * Data free func prototype.
 819  */
 820 typedef void (*eo_base_data_free_func)(void *);
 821
 822 /**
 823  * @var EO_BASE_BASE_ID
 824  * #EO_BASE_CLASS 's base id.
 825  */
 826 extern EAPI Eo_Op EO_BASE_BASE_ID;
 827
 828 enum {
 829      EO_BASE_SUB_ID_CONSTRUCTOR,
 830      EO_BASE_SUB_ID_DESTRUCTOR,
 831      EO_BASE_SUB_ID_DATA_SET,
 832      EO_BASE_SUB_ID_DATA_GET,
 833      EO_BASE_SUB_ID_DATA_DEL,
 834      EO_BASE_SUB_ID_WREF_ADD,
 835      EO_BASE_SUB_ID_WREF_DEL,
 836      EO_BASE_SUB_ID_EVENT_CALLBACK_PRIORITY_ADD,
 837      EO_BASE_SUB_ID_EVENT_CALLBACK_DEL,
 838      EO_BASE_SUB_ID_EVENT_CALLBACK_CALL,
 839      EO_BASE_SUB_ID_EVENT_CALLBACK_FORWARDER_ADD,
 840      EO_BASE_SUB_ID_EVENT_CALLBACK_FORWARDER_DEL,
 841      EO_BASE_SUB_ID_EVENT_FREEZE,
 842      EO_BASE_SUB_ID_EVENT_THAW,
 843      EO_BASE_SUB_ID_EVENT_FREEZE_GET,
 844      EO_BASE_SUB_ID_EVENT_GLOBAL_FREEZE,
 845      EO_BASE_SUB_ID_EVENT_GLOBAL_THAW,
 846      EO_BASE_SUB_ID_EVENT_GLOBAL_FREEZE_GET,
 847      EO_BASE_SUB_ID_LAST
 848 };
 849
 850 /**
 851  * @def EO_BASE_ID(sub_id)
 852  * Helper macro to get the full Op ID out of the sub_id for EO_BASE.
 853  * @param sub_id the sub id inside EO_BASE.
 854  */
 855 #define EO_BASE_ID(sub_id) (EO_BASE_BASE_ID + (sub_id))
 856
 857 /**
 858  * @def eo_base_data_set(key, data, free_func)
 859  * Set generic data to object.
 860  * @param[in] key the key associated with the data
 861  * @param[in] data the data to set.
 862  * @param[in] free_func the func to free data with (NULL means "do nothing").
 863  *
 864  * @see #eo_base_data_get
 865  * @see #eo_base_data_del
 866  */
 867 #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)
 868
 869 /**
 870  * @def eo_base_data_get(key, data)
 871  * Get generic data from object.
 872  * @param[in] key the key associated with the data
 873  * @param[out] data the data for the key
 874  *
 875  * @see #eo_base_data_set
 876  * @see #eo_base_data_del
 877  */
 878 #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)
 879
 880 /**
 881  * @def eo_base_data_del(key)
 882  * Del generic data from object.
 883  * @param[in] key the key associated with the data
 884  *
 885  * @see #eo_base_data_set
 886  * @see #eo_base_data_get
 887  */
 888 #define eo_base_data_del(key) EO_BASE_ID(EO_BASE_SUB_ID_DATA_DEL), EO_TYPECHECK(const char *, key)
 889
 890 /**
 891  * @def eo_wref_add
 892  * @brief Add a new weak reference to obj.
 893  * @param wref The pointer to use for the weak ref.
 894  *
 895  * This function registers the object handle pointed by wref to obj so when
 896  * obj is deleted it'll be updated to NULL. This functions should be used
 897  * when you want to keep track of an object in a safe way, but you don't want
 898  * to prevent it from being freed.
 899  *
 900  * @see #eo_wref_del
 901  */
 902 #define eo_wref_add(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_ADD), EO_TYPECHECK(Eo **, wref)
 903
 904 /**
 905  * @def eo_wref_del
 906  * @brief Delete the weak reference passed.
 907  * @param wref the weak reference to free.
 908  *
 909  * @see #eo_wref_add
 910  */
 911 #define eo_wref_del(wref) EO_BASE_ID(EO_BASE_SUB_ID_WREF_DEL), EO_TYPECHECK(Eo **, wref)
 912
 913 /**
 914  * @def eo_wref_del_safe
 915  * @brief Delete the weak reference passed.
 916  * @param wref the weak reference to free.
 917  *
 918  * Same as eo_wref_del(), with the different that it's not called from eobj_do()
 919  * so you don't need to check if *wref is not NULL.
 920  *
 921  * @see #eo_wref_del
 922  */
 923 #define eo_wref_del_safe(wref) \
 924    do { \
 925         if (*wref) eo_do(*wref, eo_wref_del(wref)); \
 926    } while (0)
 927
 928 /**
 929  * @def eo_constructor
 930  * @brief Call the object's constructor.
 931  *
 932  * Should not be used with #eo_do. Only use it with #eo_do_super.
 933  *
 934  * @see #eo_destructor
 935  */
 936 #define eo_constructor() EO_BASE_ID(EO_BASE_SUB_ID_CONSTRUCTOR)
 937
 938 /**
 939  * @def eo_destructor
 940  * @brief Call the object's destructor.
 941  *
 942  * Should not be used with #eo_do. Only use it with #eo_do_super.
 943  *
 944  * @see #eo_constructor
 945  */
 946 #define eo_destructor() EO_BASE_ID(EO_BASE_SUB_ID_DESTRUCTOR)
 947
 948 /**
 949  * @addtogroup Eo_Events Eo's Event Handling
 950  * @{
 951  */
 952
 953 /**
 954  * @def EO_CALLBACK_PRIORITY_BEFORE
 955  * Slightly more prioritized than default.
 956  */
 957 #define EO_CALLBACK_PRIORITY_BEFORE -100
 958 /**
 959  * @def EO_CALLBACK_PRIORITY_DEFAULT
 960  * Default callback priority level
 961  */
 962 #define EO_CALLBACK_PRIORITY_DEFAULT 0
 963 /**
 964  * @def EO_CALLBACK_PRIORITY_AFTER
 965  * Slightly less prioritized than default.
 966  */
 967 #define EO_CALLBACK_PRIORITY_AFTER 100
 968
 969 /**
 970  * @typedef Eo_Callback_Priority
 971  *
 972  * Callback priority value. Range is -32k - 32k. The lower the number, the
 973  * higher the priority.
 974  *
 975  * @see EO_CALLBACK_PRIORITY_AFTER
 976  * @see EO_CALLBACK_PRIORITY_BEFORE
 977  * @see EO_CALLBACK_PRIORITY_DEFAULT
 978  */
 979 typedef short Eo_Callback_Priority;
 980
 981 /**
 982  * @def EO_CALLBACK_STOP
 983  * Stop calling callbacks for the even of which the callback was called for.
 984  * @see EO_CALLBACK_CONTINUE
 985  */
 986 #define EO_CALLBACK_STOP EINA_FALSE
 987
 988 /**
 989  * @def EO_CALLBACK_CONTINUE
 990  * Continue calling callbacks for the even of which the callback was called for.
 991  * @see EO_CALLBACK_STOP
 992  */
 993 #define EO_CALLBACK_CONTINUE EINA_TRUE
 994
 995 /**
 996  * @typedef Eo_Event_Cb
 997  *
 998  * An event callback prototype.
 999  *
1000  * @param data The user data registered with the callback.
1001  * @param obj The object which initiated the event.
1002  * @param desc The event's description.
1003  * @param event_info additional data passed with the event.
1004  * @return #EO_CALLBACK_STOP to stop calling additional callbacks for the event, #EO_CALLBACK_CONTINUE to continue.
1005  */
1006 typedef Eina_Bool (*Eo_Event_Cb)(void *data, Eo *obj, const Eo_Event_Description *desc, void *event_info);
1007
1008 /**
1009  * @def eo_event_callback_forwarder_add
1010  * @brief Add an event callback forwarder for an event and an object.
1011  * @param[in] desc The description of the event to listen to.
1012  * @param[in] new_obj The object to emit events from.
1013  *
1014  * @see eo_event_callback_forwarder_del()
1015  */
1016 #define eo_event_callback_forwarder_add(desc, new_obj) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_CALLBACK_FORWARDER_ADD), EO_TYPECHECK(const Eo_Event_Description *, desc), EO_TYPECHECK(Eo *, new_obj)
1017
1018 /**
1019  * @def eo_event_callback_forwarder_del
1020  * @brief Remove an event callback forwarder for an event and an object.
1021  * @param[in] desc The description of the event to listen to.
1022  * @param[in] new_obj The object to emit events from.
1023  *
1024  * @see eo_event_callback_forwarder_add()
1025  */
1026 #define eo_event_callback_forwarder_del(desc, new_obj) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_CALLBACK_FORWARDER_DEL), EO_TYPECHECK(const Eo_Event_Description *, desc), EO_TYPECHECK(Eo *, new_obj)
1027
1028 /**
1029  * @def eo_event_freeze
1030  * @brief freeze events of object.
1031  *
1032  * Prevents event callbacks from being called for the object.
1033  *
1034  * @see #eo_event_thaw
1035  */
1036 #define eo_event_freeze() EO_BASE_ID(EO_BASE_SUB_ID_EVENT_FREEZE)
1037
1038 /**
1039  * @def eo_event_thaw
1040  * @brief thaw events of object.
1041  *
1042  * Lets event callbacks be called for the object.
1043  *
1044  * @see #eo_event_freeze
1045  */
1046 #define eo_event_thaw() EO_BASE_ID(EO_BASE_SUB_ID_EVENT_THAW)
1047
1048 /**
1049  * @def eo_event_freeze_get
1050  * @brief return freeze events of object.
1051  *
1052  * @param[out] fcount The event freeze count of the object.
1053  *
1054  * Return event freeze count.
1055  *
1056  * @see #eo_event_freeze
1057  * @see #eo_event_thaw
1058  */
1059 #define eo_event_freeze_get(fcount) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_FREEZE_GET), EO_TYPECHECK(int *, fcount)
1060
1061 /**
1062  * @def eo_event_global_freeze
1063  * @brief freeze events of object.
1064  *
1065  * Prevents event callbacks from being called for the object.
1066  *
1067  * @see #eo_event_freeze
1068  * @see #eo_event_global_thaw
1069  */
1070 #define eo_event_global_freeze() EO_BASE_ID(EO_BASE_SUB_ID_EVENT_GLOBAL_FREEZE)
1071
1072 /**
1073  * @def eo_event_global_thaw
1074  * @brief thaw events of object.
1075  *
1076  * Lets event callbacks be called for the object.
1077  *
1078  * @see #eo_event_thaw
1079  * @see #eo_event_global_freeze
1080  */
1081 #define eo_event_global_thaw() EO_BASE_ID(EO_BASE_SUB_ID_EVENT_GLOBAL_THAW)
1082
1083 /**
1084  * @def eo_event_global_freeze_get
1085  * @brief return freeze events of object.
1086  *
1087  * @param[out] fcount The event freeze count of the object.
1088  *
1089  * Return event freeze count.
1090  *
1091  * @see #eo_event_freeze_get
1092  * @see #eo_event_global_freeze
1093  * @see #eo_event_global_thaw
1094  */
1095 #define eo_event_global_freeze_get(fcount) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_GLOBAL_FREEZE_GET), EO_TYPECHECK(int *, fcount)
1096
1097 /**
1098  * @def eo_event_callback_add(obj, desc, cb, data)
1099  * Add a callback for an event.
1100  * @param[in] desc The description of the event to listen to.
1101  * @param[in] cb the callback to call.
1102  * @param[in] data additional data to pass to the callback.
1103  *
1104  * callbacks of the same priority are called in reverse order of creation.
1105  *
1106  * @see eo_event_callback_priority_add()
1107  */
1108 #define eo_event_callback_add(desc, cb, data) \
1109    eo_event_callback_priority_add(desc, \
1110          EO_CALLBACK_PRIORITY_DEFAULT, cb, data)
1111
1112 /**
1113  * @def eo_event_callback_priority_add
1114  * @brief Add a callback for an event with a specific priority.
1115  * @param[in] desc The description of the event to listen to.
1116  * @param[in] priority The priority of the callback.
1117  * @param[in] cb the callback to call.
1118  * @param[in] data additional data to pass to the callback.
1119  *
1120  * callbacks of the same priority are called in reverse order of creation.
1121  *
1122  * @see #eo_event_callback_add
1123  */
1124 #define eo_event_callback_priority_add(desc, priority, cb, data) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_CALLBACK_PRIORITY_ADD), EO_TYPECHECK(const Eo_Event_Description *, desc), EO_TYPECHECK(Eo_Callback_Priority, priority), EO_TYPECHECK(Eo_Event_Cb, cb), EO_TYPECHECK(const void *, data)
1125
1126
1127 /**
1128  * @def eo_event_callback_del
1129  * @brief Del a callback with a specific data associated to it for an event.
1130  * @param[in] desc The description of the event to listen to.
1131  * @param[in] func the callback to delete.
1132  * @param[in] user_data The data to compare.
1133  *
1134  */
1135 #define eo_event_callback_del(desc, func, user_data) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_CALLBACK_DEL), EO_TYPECHECK(const Eo_Event_Description *, desc), EO_TYPECHECK(Eo_Event_Cb, func), EO_TYPECHECK(const void *, user_data)
1136
1137 /**
1138  * @def eo_event_callback_call
1139  * @brief Call the callbacks for an event of an object.
1140  * @param[in] desc The description of the event to call.
1141  * @param[in] event_info Extra event info to pass to the callbacks.
1142  * @param[out] aborted @c EINA_TRUE if one of the callbacks aborted the call, @c EINA_FALSE otherwise.
1143  */
1144 #define eo_event_callback_call(desc, event_info, aborted) EO_BASE_ID(EO_BASE_SUB_ID_EVENT_CALLBACK_CALL), EO_TYPECHECK(const Eo_Event_Description *, desc), EO_TYPECHECK(const void *, event_info), EO_TYPECHECK(Eina_Bool *, aborted)
1145
1146 /**
1147  * @}
1148  */
1149
1150 /**
1151  * @var _EO_EV_CALLBACK_ADD
1152  * see EO_EV_CALLBACK_ADD
1153  */
1154 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_ADD;
1155
1156 /**
1157  * @def EO_EV_CALLBACK_ADD
1158  * The event description (of type #Eo_Event_Description) for
1159  * The "Callback listener added" event.
1160  */
1161 #define EO_EV_CALLBACK_ADD (&(_EO_EV_CALLBACK_ADD))
1162
1163 /**
1164  * @var _EO_EV_CALLBACK_DEL
1165  * see EO_EV_CALLBACK_DEL
1166  */
1167 EAPI extern const Eo_Event_Description _EO_EV_CALLBACK_DEL;
1168
1169 /**
1170  * @def EO_EV_CALLBACK_DEL
1171  * The event description (of type #Eo_Event_Description) for
1172  * The "Callback listener deleted" event.
1173  */
1174 #define EO_EV_CALLBACK_DEL (&(_EO_EV_CALLBACK_DEL))
1175
1176 /**
1177  * @var _EO_EV_DEL
1178  * see #EO_EV_DEL
1179  */
1180 EAPI extern const Eo_Event_Description _EO_EV_DEL;
1181
1182 /**
1183  * @def EO_EV_DEL
1184  * Object is being deleted.
1185  */
1186 #define EO_EV_DEL (&(_EO_EV_DEL))
1187
1188 /**
1189  * @}
1190  */
1191
1192 /**
1193  * @}
1194  */
1195
1196 #ifdef __cplusplus
1197 }
1198 #endif
1199
1200 #endif