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