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