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 #define EOLIAN
12
13 #ifdef _WIN32
14 # ifdef EFL_BUILD
15 # ifdef DLL_EXPORT
16 # define EAPI __declspec(dllexport)
17 # else
18 # define EAPI
19 # endif
20 # else
21 # define EAPI __declspec(dllimport)
22 # endif
23 # define EAPI_WEAK
24 #else
25 # ifdef __GNUC__
26 # if __GNUC__ >= 4
27 # define EAPI __attribute__ ((visibility("default")))
28 # define EAPI_WEAK __attribute__ ((weak))
29 # else
30 # define EAPI
31 # define EAPI_WEAK
32 # endif
33 # else
34 # define EAPI
35 # define EAPI_WEAK
36 # endif
37 #endif
38
39 /* When used, this indicates that the function is an Eo API. */
40 #define EOAPI EAPI EAPI_WEAK
41
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46 /**
47 * @page eo_main Eo
48 *
49 * @date 2012 (created)
50 *
51 * @section eo_toc Table of Contents
52 *
53 * @li @ref eo_main_intro
54 * @li @ref eo_main_compiling
55 * @li @ref eo_main_next_steps
56 * @li @ref eo_main_intro_example
57 * @li @ref eo_lifecycle_debug
58 *
59 * @section eo_main_intro Introduction
60 *
61 * The Eo generic object system. It's designed to be the base object
62 * system for the EFL.
63
64 * @section eo_main_compiling How to compile
65 *
66 * Eo is a library to which your application can link. The procedure for this is
67 * very simple. You simply have to compile your application with the
68 * appropriate compiler flags that the @c pkg-config script outputs. For
69 * example:
70 *
71 * Compiling C or C++ files into object files:
72 *
73 * @verbatim
74 gcc -c -o main.o main.c `pkg-config --cflags eo`
75 @endverbatim
76 *
77 * Linking object files into a binary executable:
78 *
79 * @verbatim
80 gcc -o my_application main.o `pkg-config --libs eo`
81 @endverbatim
82 *
83 * See @ref pkgconfig
84 *
85 * @section eo_main_next_steps Next Steps
86 *
87 * After you've understood and installed Eo,
88 * you can then learn more about the programming interface.
89 *
90 * Recommended reading:
91 *
92 * @li @ref Efl_Class_Base
93 * @li @ref Efl_Class
94 * @li @ref Efl_Events
95 * @li @ref Eo_Composite_Objects
96 *
97 * @section eo_lifecycle_debug Debug Object Lifecycle
98 *
99 * When dealing with objects it's important to investigate the object
100 * lifecycle: in other words when they were created and deleted. This is not
101 * that trivial since objects can have extra references added with
102 * efl_ref() as well as removed with efl_unref(), efl_parent_set() to
103 * NULL or efl_del().
104 *
105 * To aid development process as well as debug memory leaks and invalid
106 * access, you can use the eo_debug script helper to preload
107 * libeo_dbg.so, run as:
108 *
109 * @verbatim
110 export EO_LIFECYCLE_DEBUG=1
111 export EINA_LOG_LEVELS=eo_lifecycle:4
112 eo_debug my_app
113 * @endverbatim
114 *
115 * This will print out all the objects that were created and deleted,
116 * as well as keep the stack trace that originated those. If a double
117 * free or user-after-free occurs it will print out the backtrace
118 * where the object was created and where it was deleted. If only
119 * errors should be displayed decrease the log level to 2:
120 *
121 * @verbatim
122 export EO_LIFECYCLE_DEBUG=1
123 export EINA_LOG_LEVELS=eo_lifecycle:2 # just critical, error and warning
124 eo_debug my_app
125 * @endverbatim
126 *
127 * Keep in mind that the log will consume memory for all objects and
128 * that main loop primitives such as timers, jobs, promises and
129 * futures are all objects. If created in large numbers, they will
130 * consume large amounts of of memory.
131 *
132 * To address log pollution and memory consumption, you can
133 * select just a handful classes to be logged using @c
134 * EO_LIFECYCLE_DEBUG with a list of comma-separated class names. Use
135 * @c EO_LIFECYCLE_DEBUG=1 or @c EO_LIFECYCLE_DEBUG=* to log all
136 * classes, otherwise just the classes listed will be
137 * (whitelist).
138 *
139 * @verbatim
140 # Log only 2 classes: Efl_Loop and Efl_Net_Dialer_Tcp
141 export EO_LIFECYCLE_DEBUG=Efl_Loop,Efl_Net_Dialer_Tcp
142 export EINA_LOG_LEVELS=eo_lifecycle:4
143 eo_debug my_app
144 * @endverbatim
145 *
146 * Another approach is to log all but a few classes, also known as
147 * a blacklist. This is done with another environment variable @c
148 * EO_LIFECYCLE_NO_DEBUG=class1,class2.
149 *
150 * @verbatim
151 # Log all but Efl_Loop_Timer
152 export EO_LIFECYCLE_NO_DEBUG=Efl_Loop_Timer
153 export EINA_LOG_LEVELS=eo_lifecycle:4
154 eo_debug my_app
155 * @endverbatim
156 *
157 * @section eo_main_intro_example Introductory Example
158 *
159 * @ref Eo_Tutorial
160
161 *
162 *
163 * @addtogroup Eo
164 * @{
165 */
166
167 typedef struct _Eo_Object _Eo_Object;
168
169 /**
170 * @typedef Eo
171 * The basic Object type.
172 */
173 typedef struct _Eo_Opaque Eo;
174
175 /**
176 * @typedef Efl_Class
177 * The basic class type - should be removed, for compatibility reasons.
178 */
179 typedef Eo Efl_Class;
180 #define _EFL_CLASS_EO_CLASS_TYPE
181
182 typedef Eo Efl_Object;
183 #define _EFL_OBJECT_EO_CLASS_TYPE
184
185 /**
186 * @var _efl_class_creation_lock
187 * This variable is used for locking purposes in the class_get function
188 * defined in #EFL_DEFINE_CLASS.
189 * This is just to work around the fact that you need to init locks before
190 * using them.
191 * Don't touch it if you don't know what you are doing.
192 * @internal
193 */
194 EAPI extern Eina_Lock _efl_class_creation_lock;
195
196 /**
197 * @var _efl_object_init_generation
198 * This variable stores the current eo init generation. In other words how many times
199 * you have completed full init/shutdown cycles. This starts at 1 and is incremeted on
200 * every call to shutdown that actually shuts down eo.
201 * @internal
202 */
203 EAPI extern unsigned int _efl_object_init_generation;
204
205 /**
206 * @typedef Efl_Del_Intercept
207 *
208 * A function to be called on object deletion/destruction instead of normal
209 * destruction taking place.
210 *
211 * @param obj_id The object needing to be destroyed.
212 */
213 typedef void (*Efl_Del_Intercept) (Eo *obj_id);
214
215 /**
216 * This is a no-operation. Its presence behind a function parameter indicates that
217 * ownership of the parameter is transferred to the callee.
218 * When present after a method, it indicates that the return value of the method is
219 * transferred to the caller.
220 * For objects, ownership transfer means that exactly one reference is transferred.
221 * If you transfer ownership without owning a reference in the first place, you will
222 * get unexpected behavior.
223 * For non-Objects, ownership transfer means that the responsibility of freeing a
224 * segment of memory is passed on.
225 */
226 #define EFL_TRANSFER_OWNERSHIP
227
228 #include "efl_object_override.eo.h"
229 #include "efl_object.eo.h"
230
231 /**
232 * @brief A parameter passed in event callbacks holding extra event parameters.
233 *
234 * This is the full event information passed to callbacks in C.
235 *
236 * @since 1.22
237 *
238 * @ingroup Efl
239 */
240 typedef struct _Efl_Event
241 {
242 Efl_Object *object; /**< The object the callback was called on.
243 *
244 * @since 1.22 */
245 const Efl_Event_Description *desc; /**< The event description.
246 *
247 * @since 1.22 */
248 void *info; /**< Extra event information passed by the event caller. Must be
249 * cast to the event type declared in the EO file. Keep in mind
250 * that: 1) Objects are passed as a normal Eo*. Event subscribers
251 * can call functions on these objects. 2) Structs, built-in
252 * types and containers are passed as const pointers, with one
253 * level of indirection.
254 *
255 * @since 1.22 */
256 } Efl_Event;
257
258 #define EO_CLASS EFL_OBJECT_CLASS
259
260 /** An event callback prototype. */
261 typedef void (*Efl_Event_Cb)(void *data, const Efl_Event *event);
262
263 /**
264 * @struct _Efl_Callback_Array_Item
265 * @brief An item in an array of callback desc/func.
266 *
267 * See also efl_event_callback_array_add().
268 */
269 typedef struct _Efl_Callback_Array_Item
270 {
271 const Efl_Event_Description *desc; /**< The event description. */
272 Efl_Event_Cb func; /**< The callback function. */
273 } Efl_Callback_Array_Item;
274
275
276 /**
277 * @struct _Efl_Callback_Array_Item_Full
278 * @brief An item provided by EFL_EVENT_CALLBACK_ADD/EFL_EVENT_CALLBACK_DEL.
279 *
280 * See also EFL_EVENT_CALLBACK_ADD EFL_EVENT_CALLBACK_DEL.
281 */
282 typedef struct _Efl_Callback_Array_Item_Full
283 {
284 const Efl_Event_Description *desc; /**< The event description. */
285 Efl_Callback_Priority priority; /** < The priorit of the event */
286 Efl_Event_Cb func; /**< The callback function. */
287 void *user_data; /**< The user data pointer to be passed to the func */
288 } Efl_Callback_Array_Item_Full;
289
290 /**
291 * @brief Add a callback for an event with a specific priority.
292 *
293 * Callbacks of the same priority are called in reverse order of creation.
294 *
295 * A callback is only executed on events emitted after this call finished.
296 *
297 * @param[in] desc The description of the event to listen to
298 * @param[in] priority The priority of the callback
299 * @param[in] cb the callback to call
300 * @param[in] data additional data to pass to the callback
301 *
302 * @return Return @c true when the callback has been successfully added.
303 */
304 EOAPI Eina_Bool efl_event_callback_priority_add(Eo *obj, const Efl_Event_Description *desc, Efl_Callback_Priority priority, Efl_Event_Cb cb, const void *data);
305
306 /**
307 * @brief Delete a callback with a specific data associated with it for an event.
308 *
309 * The callback will never be emitted again after this call, even if a event
310 * emission is taking place.
311 *
312 * @param[in] desc The description of the event to listen to
313 * @param[in] func The callback to delete
314 * @param[in] user_data The data to compare
315 *
316 * @return Return @c true when the callback has been successfully removed.
317 */
318 EOAPI Eina_Bool efl_event_callback_del(Eo *obj, const Efl_Event_Description *desc, Efl_Event_Cb func, const void *user_data);
319
320 /**
321 * @brief Get the Eina_Future scheduler that trigger them on a specific set of events on an object.
322 *
323 * @param[in] obj The object that the scheduler is attached to.
324 * @param[in] array The events that when triggered on the object will trigger the Eina_Future.
325 *
326 * @return Return a scheduler that will trigger future exactly when the event are triggered.
327 *
328 * @note You must use EFL_SCHEDULER_ARRAY_DEFINE() to create the @p array.
329 */
330 EOAPI Eina_Future_Scheduler *efl_event_future_scheduler_get(const Eo *obj, Efl_Callback_Array_Item *array);
331
332 /**
333 * @brief Add an array of callbacks created by @ref EFL_CALLBACKS_ARRAY_DEFINE
334 * for an event with a specific priority. The array need to be sorted with @ref
335 * efl_callbacks_cmp if you are not using the @ref EFL_CALLBACKS_ARRAY_DEFINE
336 * macro.
337 *
338 * Callbacks of the same priority are called in reverse order of creation.
339 *
340 * A callback from the array is only executed on events emitted after this
341 * call finished.
342 *
343 * @param[in] array An #Efl_Callback_Array_Item of events to listen to
344 * @param[in] priority The priority of the callback
345 * @param[in] data Additional data to pass to the callback
346 *
347 * @return Return @c true when the callback has been successfully added.
348 */
349 EOAPI Eina_Bool efl_event_callback_array_priority_add(Eo *obj, const Efl_Callback_Array_Item *array, Efl_Callback_Priority priority, const void *data);
350
351 /**
352 * @brief Del a callback array with a specific data associated to it for an
353 * event. The callbacks from the array will never be emitted again after this
354 * call, even if a event emission is going on.
355 *
356 * @param[in] array An #Efl_Callback_Array_Item of events to listen to
357 * @param[in] user_data The data to compare
358 *
359 * @return Return @c true when the callback has been successfully removed.
360 */
361 EOAPI Eina_Bool efl_event_callback_array_del(Eo *obj, const Efl_Callback_Array_Item *array, const void *user_data);
362
363 /**
364 * @brief Call the callbacks for an event of an object.
365 *
366 * @param[in] desc The description of the event to call.
367 * @param[in] event_info Extra event info to pass to the callbacks. Please provide objects of the same type as
368 * advertised in the EO file, as this is what listeners of this event will be expecting. Keep in mind that:
369 * 1) Objects must be passed as a normal Eo*. Event subscribers can call functions on these objects.
370 * 2) Structs, built-in types and containers must be passed as const pointers, with one level of indirection.
371 *
372 * @return @c false If one of the callbacks aborted the call, @c true otherwise
373 */
374 EOAPI Eina_Bool efl_event_callback_call(Eo *obj, const Efl_Event_Description *desc, void *event_info);
375
376 /**
377 * @brief Call the callbacks for an event of an object.
378 *
379 * Like @ref efl_event_callback_call but also call legacy smart callbacks that
380 * have the same name of the given event.
381 *
382 * @param[in] desc The description of the event to call.
383 * @param[in] event_info Extra event info to pass to the callbacks.
384 *
385 * @return @c false If one of the callbacks aborted the call, @c true otherwise
386 *
387 * @since 1.19
388 */
389 EOAPI Eina_Bool efl_event_callback_legacy_call(Eo *obj, const Efl_Event_Description *desc, void *event_info);
390
391
392 /**
393 * @struct _Efl_Future_Cb_Desc
394 *
395 * A structure with callbacks to be used by efl_future_cb_from_desc() and efl_future_chain_array()
396 *
397 * @see efl_future_cb_from_desc()
398 * @see efl_future_chain_array()
399 */
400 typedef struct _Efl_Future_Cb_Desc {
401 /**
402 * Called on success (value.type is not @c EINA_VALUE_TYPE_ERROR).
403 *
404 * If @c success_type is not NULL, then the value is guaranteed to be of that type.
405 * If not, it will trigger @c error with @c EINVAL.
406 *
407 * After this function returns, @c free callback is called if provided.
408 *
409 * @note This function is always called from a safe context (main loop or some platform defined safe context).
410 *
411 * @param o The object used to create the link in efl_future_cb_from_desc() or efl_future_chain_array().
412 * @param value The operation result
413 * @return An Eina_Value to pass to the next Eina_Future in the chain (if any).
414 * If there is no need to convert the received value, it's @b recommended
415 * to passthrough @p value argument. If you need to convert to a different type
416 * or generate a new value, use @c eina_value_setup() on @b another Eina_Value
417 * and return it. By returning a promise Eina_Value (eina_promise_as_value()) the
418 * whole chain will wait until the promise is resolved in
419 * order to continue execution.
420 * Note that the value contents must survive this function scope.
421 * In other words, do @b not use stack allocated blobs, arrays, structures or types that
422 * keeps references to memory you assign. Values will be automatically cleaned up
423 * using @c eina_value_flush() once they are unused (no more future or futures
424 * returned a new value).
425 */
426 Eina_Value (*success)(Eo *o, void *data, const Eina_Value value);
427 /**
428 * Called on error (value.type is @c EINA_VALUE_TYPE_ERROR).
429 *
430 * This function can return another error then propagate or convert it. However it
431 * may also return a non-error, in which case the next future in the chain will receive a regular
432 * value, which may call its @c success.
433 *
434 * If this function is not provided, then it will passthrough the error to the next error handler.
435 *
436 * It may be called with @c EINVAL if @c success_type is provided and doesn't
437 * match the received type.
438 *
439 * It may be called with @c ECANCELED if future was canceled.
440 *
441 * It may be called with @c ENOMEM if memory allocation failed during callback creation.
442 *
443 * After this function returns, @c free callback is called if provided.
444 *
445 * @note On future creation errors and future cancellation this function is called
446 * from the current context with the following errors respectively: `EINVAL`, `ENOMEM` and `ECANCELED`.
447 * Otherwise this function is called from a safe context.
448 *
449 *
450 * @param o The object used to create the link in efl_future_cb_from_desc() or efl_future_chain_array().
451 * @param error The operation error
452 * @return An Eina_Value to pass to the next Eina_Future in the chain (if any).
453 * If you need to convert to a different type or generate a new value,
454 * use @c eina_value_setup() on @b another Eina_Value
455 * and return it. By returning a promise Eina_Value (eina_promise_as_value()) the
456 * whole chain will wait until the promise is resolved in
457 * order to continue execution.
458 * Note that the value contents must survive this function scope.
459 * In other words @b not use stack allocated blobs, arrays, structures or types that
460 * keeps references to memory you give. Values will be automatically cleaned up
461 * using @c eina_value_flush() once they are unused (no more future or futures
462 * returned a new value).
463 */
464 Eina_Value (*error)(Eo *o, void *data, Eina_Error error);
465 /**
466 * Called on @b all situations to notify future destruction.
467 *
468 * This is called after @c success or @c error, as well as it's called if none of them are
469 * provided. Thus can be used as a "weak ref" mechanism.
470 *
471 * @note On future creation errors and future cancellation this function is called
472 * from the current context with the following errors respectively: `EINVAL`, `ENOMEM` and `ECANCELED`.
473 * Otherwise this function is called from a safe context.
474 *
475 * @param o The object used to create the link in efl_future_cb_from_desc() or efl_future_chain_array().
476 * @param dead_future The future that's been freed.
477 */
478 void (*free)(Eo *o, void *data, const Eina_Future *dead_future);
479 /**
480 * If provided, then @c success will only be called if the value type matches the given pointer.
481 *
482 * If provided and no match is found, @c error will be called with @c EINVAL. If there's no @c error,
483 * then it will be propagated to the next future in the chain.
484 */
485 const Eina_Value_Type *success_type;
486 /**
487 * Context data given to every callback.
488 *
489 * This must be freed @b only by @c free callback as it's called from every case,
490 * otherwise it may lead to memory leaks.
491 */
492 const void *data;
493 /**
494 * This is used by Eo to cancel pending futures in case
495 * an Eo object is deleted. It can be @c NULL.
496 */
497 Eina_Future **storage;
498 } Efl_Future_Cb_Desc;
499
500 /**
501 * Creates an Eina_Future_Desc for an EO object.
502 *
503 * This function creates an Eina_Future_Desc based on an Efl_Future_Cb_Desc.
504 * The main purpose of this function is create a "link" between the future
505 * and the object. In case the object is deleted before the future is resolved/rejected,
506 * the object destructor will cancel the future.
507 *
508 * @note In case context info is required for the #Efl_Future_Desc, callbacks efl_key_data_set()
509 * can be used.
510 *
511 * The example below demonstrates a file download using an Eo object. If the download
512 * lasts more than 30 seconds the Eo object will be deleted along with the future.
513 * Usually this would be done with an eina_future_race() of the download promise and a timeout promise,
514 * however the following example is useful to illustrate efl_key_data_set() usage.
515 *
516 * @code
517 *
518 * static Eina_Bool
519 * _timeout(void *data)
520 * {
521 * Eo *downloader = data;
522 * //In case the download is not completed yet.
523 * //Delete the downloader (cancels the file download and the future)
524 * efl_key_data_set(downloader, "timer", NULL);
525 * efl_unref(downloader);
526 * return EINA_FALSE;
527 * }
528 *
529 * static Eina_Value
530 * _file_ok(Eo *o EINA_UNUSED, void *data EINA_UNUSED, const Eina_Value value)
531 * {
532 * const char *data;
533 * //There's no need to check the value type since EO infra already has done so.
534 * eina_value_get(&value, &data);
535 * //Deliver the data to the user
536 * data_deliver(data);
537 * return v;
538 * }
539 *
540 * static Eina_Value
541 * _file_err(Eo *o EINA_UNUSED, void *data EINA_UNUSED, Eina_Error error)
542 * {
543 * //In case the downloader is deleted before the future is resolved, the future will be canceled thus this callback will be called.
544 * fprintf(stderr, "Could not download the file. Reason: %s\n", eina_error_msg_get(error));
545 * return EINA_VALUE_EMPTY;
546 * }
547 *
548 * static void
549 * _downlader_free(Eo *o, void *data EINA_UNUSED, const Eina_Future *dead_future EINA_UNUSED)
550 * {
551 * Ecore_Timer *t = efl_key_data_get(o, "timer");
552 * //The download finished before the timer expired. Cancel it...
553 * if (t)
554 * {
555 * ecore_timer_del(t);
556 * efl_unref(o); //Delete the object
557 * } //else - In this case the future was canceled due efl_unref() in _timeout - No need to call efl_unref()
558 * }
559 *
560 * void download_file(const char *file)
561 * {
562 * //This could be rewritten using eina_future_race()
563 * Eo *downloader = efl_add(MY_DOWNLOADER_CLASS, NULL);
564 * Eina_Future *f = downloader_download_file(downloader, file);
565 * timer = ecore_timer_add(30, _timeout, downloader);
566 * //Usually this would be done with an eina_future_race() of the download promise and a timeout promise,
567 * //however the following example is useful to illustrate efl_key_data_set() usage.
568 * efl_key_data_set(downloader, "timer", timer);
569 * efl_future_then(downloader, f, .success = _file_ok, .error = _file_err, .success_type = EINA_VALUE_TYPE_STRING, .free = downloader_free);
570 * }
571 * @endcode
572 *
573 * @param obj The object to create the link.
574 * @param desc An Efl_Future_Cb_Desc
575 * @return An Eina_Future_Desc to be used by eina_future_then(), eina_future_chain() and friends.
576 * @see efl_future_chain_array()
577 * @see efl_future_cb()
578 * @see #Efl_Future_Cb_Desc
579 * @see efl_key_data_set()
580 */
581 EOAPI Eina_Future_Desc efl_future_cb_from_desc(const Eo *obj, const Efl_Future_Cb_Desc desc) EINA_ARG_NONNULL(1);
582
583 /**
584 * Syntax suger over efl_future_cb_from_desc()
585 *
586 * Usage:
587 * @code
588 * eina_future_then_from_desc(future, efl_future_cb(my_object, .succes = success, .success_type = EINA_VALUE_TYPE_INT));
589 * @endcode
590 *
591 * @see efl_future_cb_from_desc()
592 * @see efl_future_then()
593 */
594 #define efl_future_cb(_eo, ...) efl_future_cb_from_desc(_eo, (Efl_Future_Cb_Desc){__VA_ARGS__})
595
596 /**
597 * Syntax sugar over eina_future_then_from_desc() and efl_future_cb().
598 *
599 * Usage:
600 * @code
601 * efl_future_then(o, future, .success = success, .success_type = EINA_VALUE_TYPE_INT);
602 * @endcode
603 *
604 */
605 #define efl_future_then(_eo, _future, ...) eina_future_then_from_desc(_future, efl_future_cb(_eo, ## __VA_ARGS__))
606
607 /**
608 * Creates a Future chain based on #Efl_Future_Cb_Desc
609 *
610 * This function is an wrapper around efl_future_cb_from_desc() and eina_future_then_from_desc()
611 *
612 * For more information about these check the documentation.
613 *
614 *
615 * @param obj An EO object to link to the future
616 * @param prev The previous future
617 * @param descs An array of Efl_Future_Cb_Desc
618 * @return An Eina_Future or @c NULL on error.
619 * @note If an error occurs the whole future chain will be CANCELED, causing
620 * desc.error to be called passing `ENOMEM` or `EINVAL` and desc.free
621 * to free the @p obj if necessary.
622 *
623 * @see efl_future_chain()
624 * @see efl_future_cb()
625 * @see eina_future_then_from_desc()
626 * @see #Efl_Future_Cb_Desc
627 */
628 EOAPI Eina_Future *efl_future_chain_array(Eo *obj, Eina_Future *prev, const Efl_Future_Cb_Desc descs[]) EINA_ARG_NONNULL(1, 2);
629
630 /**
631 * Syntax suger over efl_future_chain_array()
632 *
633 * Usage:
634 * @code
635 * Eina_Future *f = efl_future_chain(my_object, prev_future, {}, {});
636 * @endcode
637 *
638 * @see efl_future_chain_array()
639 */
640 #define efl_future_chain(_eo, _prev, ...) efl_future_chain_array(_eo, _prev, (Efl_Future_Cb_Desc []){__VA_ARGS__, {NULL, NULL, NULL, NULL, NULL}})
641
642 /**
643 * @addtogroup Eo_Debug_Information Eo's Debug information helper.
644 * @{
645 */
646
647 /**
648 * @struct _Efl_Dbg_Info
649 * The structure for the debug info used by Eo.
650 */
651 typedef struct _Efl_Dbg_Info
652 {
653 Eina_Stringshare *name; /**< The name of the part (stringshare). */
654 Eina_Value value; /**< The value. */
655 } Efl_Dbg_Info;
656
657 /**
658 * @brief Get debug information from an object.
659 *
660 * @param[in] root_node the tree Node
661 */
662 EOAPI void efl_dbg_info_get(Eo *obj, Efl_Dbg_Info *root_node);
663
664 /**
665 * @var EFL_DBG_INFO_TYPE
666 * The Eina_Value_Type for the debug info.
667 */
668 EAPI extern const Eina_Value_Type *EFL_DBG_INFO_TYPE;
669
670 /**
671 * Creates a list inside debug info list.
672 * @param[in] list list where to append
673 * @param[in] name name of the list
674 * @return the new list
675 */
676 static inline Efl_Dbg_Info *
EFL_DBG_INFO_LIST_APPEND(Efl_Dbg_Info * list,const char * name)677 EFL_DBG_INFO_LIST_APPEND(Efl_Dbg_Info *list, const char *name)
678 {
679 Efl_Dbg_Info *tmp = (Efl_Dbg_Info *)calloc(1, sizeof(*tmp));
680
681 if (!tmp) return NULL;
682 tmp->name = eina_stringshare_add(name);
683 eina_value_list_setup(&(tmp->value), EFL_DBG_INFO_TYPE);
684 if (list)
685 {
686 eina_value_list_pappend(&(list->value), tmp);
687 }
688 return tmp;
689 }
690
691 /**
692 * @def EFL_DBG_INFO_APPEND
693 * Creates a new debug info into a list
694 * @param[in] LIST list where to append (Efl_Dbg_Info *)
695 * @param[in] NAME name of the parameter (const char *)
696 * @param[in] TYPE type of the parameter (Eina_Value_Type *)
697 * @param[in] VALUE value of the parameter
698 */
699 #define EFL_DBG_INFO_APPEND(LIST, NAME, TYPE, VALUE) \
700 do { \
701 Efl_Dbg_Info *List = LIST; \
702 if (List) \
703 { \
704 Efl_Dbg_Info *Tmp = calloc(1, sizeof(*Tmp)); \
705 \
706 if (!Tmp) break; \
707 Tmp->name = eina_stringshare_add(NAME); \
708 eina_value_setup(&(Tmp->value), TYPE); \
709 eina_value_set(&(Tmp->value), VALUE); \
710 eina_value_list_pappend(&(List->value), Tmp); \
711 } \
712 } while (0)
713
714 /**
715 * Frees the Efl_Dbg_Info tree. (The whole tree recursively).
716 * @param[in] info The tree to delete.
717 */
718 EAPI void efl_dbg_info_free(Efl_Dbg_Info *info);
719
720 /**
721 * @}
722 */
723
724 /**
725 * @typedef Efl_Object_Op
726 * The Eo operation type id.
727 */
728 typedef unsigned int Efl_Object_Op;
729
730 /**
731 * @def EFL_NOOP
732 * A special #Efl_Object_Op meaning "No operation".
733 */
734 #define EFL_NOOP ((Efl_Object_Op) 0)
735
736 /**
737 * @addtogroup Efl_Events Eo's Event Handling
738 * @{
739 */
740
741 /**
742 * @def EFL_EVENT_DESCRIPTION(name)
743 * A helper macro to help populate #Efl_Event_Description
744 * @param name The name of the event.
745 * @see Efl_Event_Description
746 */
747 #define EFL_EVENT_DESCRIPTION(name) { name, EINA_FALSE, EINA_FALSE, EINA_FALSE }
748
749 /**
750 * @def EFL_EVENT_DESCRIPTION_HOT(name)
751 * A helper macro to help populate #Efl_Event_Description and make
752 * the event impossible to freeze.
753 * @param name The name of the event.
754 * @see Efl_Event_Description
755 * @see EFL_EVENT_DESCRIPTION
756 */
757 #define EFL_EVENT_DESCRIPTION_HOT(name) { name, EINA_TRUE, EINA_FALSE, EINA_FALSE }
758
759 /**
760 * @def EFL_EVENT_DESCRIPTION(name)
761 * A helper macro to help populating #Efl_Event_Description
762 * @param name The name of the event.
763 * @see Efl_Event_Description
764 */
765 #define EFL_EVENT_DESCRIPTION_RESTART(name) { name, EINA_FALSE, EINA_FALSE, EINA_TRUE }
766
767 /**
768 * @def EFL_EVENT_DESCRIPTION_HOT(name)
769 * A helper macro to help populating #Efl_Event_Description and make
770 * the event impossible to freeze.
771 * @param name The name of the event.
772 * @see Efl_Event_Description
773 * @see EFL_EVENT_DESCRIPTION
774 */
775 #define EFL_EVENT_DESCRIPTION_HOT_RESTART(name) { name, EINA_TRUE, EINA_FALSE, EINA_TRUE }
776
777
778
779 /**
780 * @}
781 */
782
783 /**
784 * @addtogroup Efl_Class Efl Class
785 * @{
786 */
787
788 /**
789 * @def EFL_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...)
790 * A convenient macro to be used for creating the class_get function. This
791 * macro is fairly simple and makes for better code.
792 * @param class_get_func_name the name of the wanted class_get function name.
793 * @param class_desc the class description.
794 * @param parent_class The parent class for the function. See efl_class_new() for more information.
795 * @param ... List of extensions. See efl_class_new() for more information.
796 *
797 * You must use this macro if you want thread safety in class creation.
798 */
799 #define EFL_DEFINE_CLASS(class_get_func_name, class_desc, parent_class, ...) \
800 const Efl_Class * \
801 class_get_func_name(void) \
802 { \
803 const Efl_Class *_tmp_parent_class; \
804 static const Efl_Class * volatile _my_class = NULL; \
805 static unsigned int _my_init_generation = 1; \
806 if (EINA_UNLIKELY(_efl_object_init_generation != _my_init_generation)) \
807 { \
808 _my_class = NULL; /* It's freed in efl_object_shutdown(). */ \
809 } \
810 if (EINA_LIKELY(!!_my_class)) return _my_class; \
811 \
812 eina_lock_take(&_efl_class_creation_lock); \
813 if (!!_my_class) \
814 { \
815 eina_lock_release(&_efl_class_creation_lock); \
816 return _my_class; \
817 } \
818 _tmp_parent_class = parent_class; \
819 _my_class = efl_class_new(class_desc, _tmp_parent_class, __VA_ARGS__); \
820 _my_init_generation = _efl_object_init_generation; \
821 eina_lock_release(&_efl_class_creation_lock); \
822 \
823 return _my_class; \
824 }
825
826
827 /**
828 * An enum representing the possible types of an Eo class.
829 */
830 enum _Efl_Class_Type
831 {
832 EFL_CLASS_TYPE_REGULAR = 0, /**< Regular class. */
833 EFL_CLASS_TYPE_REGULAR_NO_INSTANT, /**< Regular non instant-able class. */
834 EFL_CLASS_TYPE_INTERFACE, /**< Interface */
835 EFL_CLASS_TYPE_MIXIN, /**< Mixin */
836 EFL_CLASS_TYPE_INVALID
837 };
838
839 /**
840 * @typedef Efl_Class_Type
841 * A convenience typedef for #_Efl_Class_Type.
842 */
843 typedef enum _Efl_Class_Type Efl_Class_Type;
844
845 /**
846 * @def EO_VERSION
847 * The current version of EO.
848 */
849 #define EO_VERSION 2
850
851 typedef struct _Efl_Op_Description
852 {
853 void *api_func; /**< The EAPI function offering this op. (The name of the func on windows) */
854 void *func; /**< The static function to call for the op. */
855 } Efl_Op_Description;
856
857 /**
858 * @struct _Efl_Object_Ops
859 *
860 * This structure holds the ops and the size of the ops.
861 */
862 typedef struct _Efl_Object_Ops
863 {
864 const Efl_Op_Description *descs; /**< The op descriptions array of size count. */
865 size_t count; /**< Number of op descriptions. */
866 } Efl_Object_Ops;
867
868 /**
869 * @struct _Efl_Class_Description
870 * This structure holds the class description.
871 * This description should be passed to efl_class_new.
872 */
873 struct _Efl_Class_Description
874 {
875 unsigned int version; /**< The current version of eo, use #EO_VERSION */
876 const char *name; /**< The name of the class. */
877 Efl_Class_Type type; /**< The type of the class. */
878 size_t data_size; /**< The size of data (private + protected + public) this class needs per object. */
879 Eina_Bool (*class_initializer)(Efl_Class *klass); /**< The initializer for the class */
880 void (*class_constructor)(Efl_Class *klass); /**< The constructor of the class. */
881 void (*class_destructor)(Efl_Class *klass); /**< The destructor of the class. */
882 };
883 /**
884 * Setter type which is used to set an #Eina_Value, this function should access one particular property field
885 */
886 typedef Eina_Error (*Efl_Object_Property_Reflection_Setter)(Eo *obj, Eina_Value value);
887
888 /**
889 * Getter type which is used to get an #Eina_Value, this function should access one particular property field
890 */
891 typedef Eina_Value (*Efl_Object_Property_Reflection_Getter)(const Eo *obj);
892
893 /**
894 * @struct _Efl_Object_Property_Reflection
895 *
896 * This structure holds one line of the reflection table.
897 * The two fields get and set might be NULL,
898 * the property_name is a normal c string containing the name of the property
899 * that the get and set function changes.
900 */
901 typedef struct _Efl_Object_Property_Reflection{
902 const char *property_name; /**< The name of the property */
903 Efl_Object_Property_Reflection_Setter set; /**< The function used to set a generic #Eina_Value on this property of the object. */
904 Efl_Object_Property_Reflection_Getter get; /**< The function used to retrieve a generic #Eina_Value from this property of the object. */
905 } Efl_Object_Property_Reflection;
906
907 /**
908 * @struct _Efl_Object_Property_Reflection_Ops
909 *
910 * This structure holds the reflection table and the size of this table.
911 */
912 typedef struct _Efl_Object_Property_Reflection_Ops
913 {
914 const Efl_Object_Property_Reflection *table; /**< The reflection table. */
915 size_t count; /**< Number of table lines descriptions. */
916 } Efl_Object_Property_Reflection_Ops;
917
918 /**
919 * @typedef Efl_Class_Description
920 * A convenience typedef for #_Efl_Class_Description
921 */
922 typedef struct _Efl_Class_Description Efl_Class_Description;
923
924 /**
925 * @brief Create a new class.
926 * @param desc the class description to create the class with.
927 * @param parent the class to inherit from.
928 * @param ... A NULL terminated list of extensions (interfaces, mixins and the classes of any composite objects).
929 * @return The new class' handle on success or NULL otherwise.
930 *
931 * @note There are two types of extensions, mixins and none-mixins.
932 * Mixins are inheriting both the API AND the implementation.
933 * Non-mixins only inherit the API, so a class which inherits a non-mixin as an extension must implement the api.
934 *
935 * Use #EFL_DEFINE_CLASS. This will provide thread safety and other
936 * features easily.
937 *
938 * @see #EFL_DEFINE_CLASS
939 */
940 EAPI const Efl_Class *efl_class_new(const Efl_Class_Description *desc, const Efl_Class *parent, ...);
941
942 /**
943 * @brief Set the functions of a class
944 * @param klass_id the class whose functions we are setting.
945 * @param object_ops The function structure we are setting for object functions
946 * @param class_ops The function structure we are setting for class functions
947 * @param reflection_table The reflection table to use within eo
948 * @return True on success, False otherwise.
949 *
950 * This should only be called from within the initializer function.
951 * The reflection_table contains a getter and setter per property name. Which are called when either
952 * efl_property_reflection_set() or efl_property_reflection_get() is called.
953 * @see #EFL_DEFINE_CLASS
954 */
955 EAPI Eina_Bool efl_class_functions_set(const Efl_Class *klass_id, const Efl_Object_Ops *object_ops, const Efl_Object_Property_Reflection_Ops *reflection_table);
956
957 /**
958 * @brief Override Eo functions of this object.
959 * @param ops The op description to override with.
960 * @return true on success, false otherwise.
961 *
962 * This lets you override all of the Eo functions of this object (this
963 * one included) and replace them with ad-hoc implementation.
964 * The contents of the array are copied so they can reside
965 * on the stack for instance.
966 *
967 * You are only allowed to override functions that are defined in the
968 * class or any of its interfaces (that is, efl_isa returning true).
969 *
970 * If @p ops is #NULL, this will revert the @p obj to its original class
971 * without any function overrides.
972 *
973 * It is not possible to override a function table of an object when it's
974 * already been overridden. Call efl_object_override(obj, NULL) first if you really
975 * need to do that.
976 *
977 * @see EFL_OPS_DEFINE
978 */
979 EAPI Eina_Bool efl_object_override(Eo *obj, const Efl_Object_Ops *ops);
980
981 /**
982 * @brief Define an array of override functions for @ref efl_object_override
983 * @param ops A name for the Efl_Object_Ops local variable to define
984 * @param ... A comma separated list of Efl_Object_Op overrides, using
985 * #EFL_OBJECT_OP_FUNC or #EFL_OBJECT_OP_CLASS_FUNC
986 *
987 * This can be used as follows:
988 * @code
989 * EFL_OPS_DEFINE(ops, EFL_OBJECT_OP_FUNC(public_func, _my_func));
990 * efl_object_override(obj, &ops);
991 * @endcode
992 *
993 * @see efl_object_override
994 */
995 #define EFL_OPS_DEFINE(ops, ...) \
996 const Efl_Op_Description _##ops##_descs[] = { __VA_ARGS__ }; \
997 const Efl_Object_Ops ops = { _##ops##_descs, EINA_C_ARRAY_LENGTH(_##ops##_descs) }
998
999 /**
1000 * @brief Check if an object "is a" klass.
1001 * @param obj The object to check
1002 * @param klass The klass to check against.
1003 * @return @c EINA_TRUE if obj implements klass or is an Efl_Class which inherits
1004 * from/implements klass, @c EINA_FALSE otherwise.
1005 *
1006 * Notice: This function does not support composite objects.
1007 * Note: that an Efl_Class is also an Efl_Object, so if you pass an Efl_Class
1008 * as obj, it will check if that class contain klass.
1009 */
1010 EAPI Eina_Bool efl_isa(const Eo *obj, const Efl_Class *klass);
1011
1012 /**
1013 * @brief Gets the name of the passed class.
1014 * @param[in] klass The class (or object) to work on.
1015 * @return The class' name.
1016 *
1017 * @see efl_class_get()
1018 */
1019 EAPI const char *efl_class_name_get(const Efl_Class *klass);
1020
1021 /**
1022 * @brief Gets the amount of memory this class object would use.
1023 * @param[in] klass The class (or object) to work on.
1024 * @return The amount of memory in Bytes.
1025 *
1026 * @see efl_class_get()
1027 */
1028 EAPI size_t efl_class_memory_size_get(const Efl_Class *klass);
1029
1030 /**
1031 * @brief Gets a debug name for this object
1032 * @param obj_id The object (or class)
1033 * @return A name to use in logs and for other debugging purposes
1034 *
1035 * Note that subclasses can override Efl.Object "debug_name_override" to
1036 * provide more meaningful debug strings. The standard format includes the
1037 * class name, the object ID (this @p obj_id), the reference count and
1038 * optionally the object name (as defined by Efl.Object.name).
1039 *
1040 * This might return a temporary string, as created by eina_slstr, which means
1041 * that a main loop should probably be running.
1042 *
1043 * @since 1.21
1044 */
1045 EAPI const char *efl_debug_name_get(const Eo *obj_id);
1046
1047 /**
1048 * @}
1049 */
1050
1051 /**
1052 * @brief Init the eo subsystem
1053 * @return @c EINA_TRUE if eo is init, @c EINA_FALSE otherwise.
1054 *
1055 * @see eo_shutdown()
1056 */
1057 EAPI Eina_Bool efl_object_init(void);
1058
1059 /**
1060 * @brief Shutdown the eo subsystem
1061 * @return @c EINA_TRUE if eo is init, @c EINA_FALSE otherwise.
1062 *
1063 * @see efl_object_init()
1064 */
1065 EAPI Eina_Bool efl_object_shutdown(void);
1066
1067 #ifdef EFL_BETA_API_SUPPORT
1068
1069 /**
1070 * The virtual allocation domain where an object lives
1071 *
1072 * You cannot mix objects between domains in the object tree or as direct
1073 * or indirect references unless you explicitly handle it and ensure the
1074 * other domain is adopted into your local thread space.
1075 */
1076 typedef enum
1077 {
1078 EFL_ID_DOMAIN_INVALID = -1, /**< Invalid */
1079 EFL_ID_DOMAIN_MAIN = 0, /**< The main loop domain where eo_init() is called */
1080 EFL_ID_DOMAIN_SHARED = 1, /**< A special shared domain visible to all threads but with extra locking and unlocking costs to access */
1081 EFL_ID_DOMAIN_THREAD /**< The normal domain for threads so they can adopt the main loop domain at times */
1082 /* One more slot for future expansion here - maybe fine-grain locked objs */
1083 } Efl_Id_Domain;
1084
1085 /**
1086 * @typedef Efl_Domain_Data
1087 * An opaque handle for private domain data
1088 */
1089 typedef struct _Efl_Domain_Data Efl_Domain_Data;
1090
1091 /**
1092 * @brief Get the native domain for the current thread
1093 *
1094 * @return The native domain
1095 *
1096 * This will return the native eo object allocation domain for the current
1097 * thread. This can only be changed with efl_domain_switch() and can
1098 * only be called before any objects are created/allocated on the thread
1099 * where it's called. Calling it after this point will result in
1100 * undefined behavior, so be sure to call this immediaetly after a thread
1101 * begins to execute. You must not change the domain of the main thread.
1102 *
1103 * @see efl_domain_switch()
1104 * @see efl_domain_current_get()
1105 * @see efl_domain_current_set()
1106 * @see efl_domain_current_push()
1107 * @see efl_domain_current_pop()
1108 * @see efl_domain_data_get()
1109 * @see efl_domain_data_adopt()
1110 * @see efl_domain_data_return()
1111 * @see efl_compatible()
1112 */
1113 EAPI Efl_Id_Domain efl_domain_get(void);
1114
1115 /**
1116 * @brief Switch the native domain for the current thread.
1117 * @param domain The domain to switch to
1118 * @return EINA_TRUE if the switch succeeds and EINA_FALSE if it fails.
1119 *
1120 * Permanently switch the native domain for new objects for the calling
1121 * thread. All objects created on this thread UNLESS it has switched to a
1122 * new domain temporarily with efl_domain_current_set(),
1123 * efl_domain_current_push() or efl_domain_current_pop(),
1124 * efl_domain_data_adopt() and efl_domain_data_return().
1125 *
1126 * @see efl_domain_get()
1127 */
1128 EAPI Eina_Bool efl_domain_switch(Efl_Id_Domain domain);
1129
1130 /**
1131 * @brief Get the current domain used for allocating new objects
1132 * @return The current domain
1133 *
1134 * Get the currently used domain that is at the top of the domain stack.
1135 * There is actually a stack of domans to use. You can alter this via
1136 * efl_domain_current_push() and efl_domain_current_pop(). This only gets
1137 * the domain for the current thread.
1138 *
1139 * @see efl_domain_get()
1140 */
1141 EAPI Efl_Id_Domain efl_domain_current_get(void);
1142
1143 /**
1144 * @brief Set the current domain used for allocating new objects.
1145 * @return EINA_TRUE if it succeeds and EINA_FALSE on failure.
1146 *
1147 * Temporarily switch the current domain being used for allocation. There
1148 * is actually a stack of domans to use. You can alter this via
1149 * efl_domain_current_push() and efl_domain_current_pop(). The current
1150 * domain is the one on the top of the stack, so this entry is altered
1151 * without pushing or popping. This only applies to the calling thread.
1152 *
1153 * @see efl_domain_get()
1154 */
1155 EAPI Eina_Bool efl_domain_current_set(Efl_Id_Domain domain);
1156
1157 /**
1158 * @brief Push a new domain onto the domain stack.
1159 * @param domain The domain to push.
1160 * @return EINA_TRUE if it succeeds and EINA_FALSE on failure.
1161 *
1162 * This pushes a domain on the domain stack that can be popped later with
1163 * efl_domain_current_pop(). If the stack is full this may fail and return
1164 * EINA_FALSE. This applies only to the calling thread.
1165 *
1166 * @see efl_domain_get()
1167 */
1168 EAPI Eina_Bool efl_domain_current_push(Efl_Id_Domain domain);
1169
1170 /**
1171 * @brief Pop a previously pushed domain from the domain stack
1172 *
1173 * This pops the top domain off the domain stack for the calling thread
1174 * that was pushed with efl_domain_current_push().
1175 *
1176 * @see efl_domain_get()
1177 */
1178 EAPI void efl_domain_current_pop(void);
1179
1180 /**
1181 * @brief Get an opaque handle to the local native domain eoid data
1182 * @return A handle to the local native domain data or NULl on failure
1183 *
1184 * This gets a handle to the domain data for the current thread, intended
1185 * to be used by another thread to adopt with efl_domain_data_adopt().
1186 * Once you use efl_domain_data_adopt(), the thread which called
1187 * efl_domain_data_get() should suspend and not execute anything
1188 * related to eo or efl objects until the thread that adopted the data
1189 * calls efl_domain_data_return() to return the data to its owner and
1190 * stop making it available to that thread.
1191 *
1192 * @see efl_domain_get()
1193 */
1194 EAPI Efl_Domain_Data *efl_domain_data_get(void);
1195
1196 /**
1197 * @brief Adopt a single extra domain to be the current domain
1198 * @param datas_in The domain data to adopt
1199 * @return The domain that was adopted or EFL_ID_DOMAIN_INVALID on failure
1200 *
1201 * This will adopt the given domain data pointed to by @p data_in
1202 * as an extra domain locally. The adopted domain must have a domain ID
1203 * that is not the same as the current thread domain or local domain. You
1204 * may not adopt a domain that clashes with the current domain. If you
1205 * set, push or pop domains in such a way that these are the same then
1206 * undefined behaviour will occur.
1207 *
1208 * This will also push the adopted domain as the current domain so that
1209 * all newly created objects (unless their parent is of a differing domain)
1210 * will be part of this adopted domain. You can still access objects from
1211 * your local domain as well, but be aware that creation will require
1212 * some switch of domain by push, pop or set. Return the domain with
1213 * efl_domain_data_return() when done.
1214 *
1215 * @see efl_domain_get()
1216 */
1217 EAPI Efl_Id_Domain efl_domain_data_adopt(Efl_Domain_Data *data_in);
1218
1219 /**
1220 * @brief Return a domain to its original owning thread
1221 * @param domain The domain to return
1222 * @return EINA_TRUE on success EINA_FALSE on failure
1223 *
1224 * This returns the domain specified by @p domain to the thread it came
1225 * from, allowing said thread to continue execution afterwards. This
1226 * will implicitly pop the current domain from the stack, assuming that
1227 * the current domain is the same one pushed implicitly by
1228 * efl_domain_data_adopt(). You cannot return your own native local
1229 * domain, only the one that was adopted by efl_domain_data_adopt().
1230 *
1231 * @see efl_domain_get()
1232 */
1233 EAPI Eina_Bool efl_domain_data_return(Efl_Id_Domain domain);
1234
1235 /**
1236 * @brief Check if 2 objects are compatible
1237 * @param obj The basic object
1238 * @param obj_target The alternate object that may be referenced by @p obj
1239 * @return EINA_TRUE if compatible, EINA_FALSE if not
1240 *
1241 * This checks to see if 2 objects are compatible : whether they are parent or
1242 * children of each other, could reference each other etc. You only
1243 * need to call this if you have objects from multiple domains (an
1244 * adopted domain with efl_domain_data_adopt() or the shared domain
1245 * EFL_ID_DOMAIN_SHARED where objects may be accessed by any thread).
1246 *
1247 * @see efl_domain_get()
1248 */
1249 EAPI Eina_Bool efl_compatible(const Eo *obj, const Eo *obj_target);
1250
1251 #endif
1252
1253 // to fetch internal function and object data at once
1254 typedef struct _Efl_Object_Op_Call_Data
1255 {
1256 Eo *eo_id;
1257 _Eo_Object *obj;
1258 void *func;
1259 void *data;
1260 void *extn1; // for future use to avoid ABI issues
1261 void *extn2; // for future use to avoid ABI issues
1262 void *extn3; // for future use to avoid ABI issues
1263 void *extn4; // for future use to avoid ABI issues
1264 } Efl_Object_Op_Call_Data;
1265
1266 // to pass the internal function call to EFL_FUNC_BODY (as Func parameter)
1267 #define EFL_FUNC_CALL(...) __VA_ARGS__
1268
1269 #ifndef _WIN32
1270 # define EFL_FUNC_COMMON_OP_FUNC(Name) ((const void *) Name)
1271 #else
1272 # define EFL_FUNC_COMMON_OP_FUNC(Name) ((const void *) #Name)
1273 #endif
1274
1275 #ifdef _MSC_VER
1276 # define EFL_FUNC_TLS __declspec(thread)
1277 #else
1278 # define EFL_FUNC_TLS __thread
1279 #endif
1280
1281
1282 // cache OP id, get real fct and object data then do the call
1283 #define EFL_FUNC_COMMON_OP(Obj, Name, DefRet) \
1284 static Efl_Object_Op ___op = 0; \
1285 static unsigned int ___generation = 0; \
1286 Efl_Object_Op_Call_Data ___call; \
1287 _Eo_##Name##_func _func_; \
1288 if (EINA_UNLIKELY((___op == EFL_NOOP) || \
1289 (___generation != _efl_object_init_generation))) \
1290 goto __##Name##_op_create; /* yes a goto - see below */ \
1291 __##Name##_op_create_done: EINA_HOT; \
1292 if (EINA_UNLIKELY(!_efl_object_call_resolve( \
1293 (Eo *) Obj, #Name, &___call, ___op, __FILE__, __LINE__))) \
1294 goto __##Name##_failed; \
1295 _func_ = (_Eo_##Name##_func) ___call.func;
1296
1297 // This looks ugly with gotos BUT it moves rare "init" handling code
1298 // out of the hot path and thus l1 instruction cach prefetch etc. so it
1299 // should provide a micro-speedup. This has been shown to have
1300 // a measurable effect on very hot code paths as l1 instgruction cache
1301 // does matter. Fetching a cacheline of code may also fetch a lot of rarely
1302 // used instructions that are skipped. If this happens, moving those away out
1303 // of the cacheline that was already fetched should yield better cache
1304 // hits.
1305 #define EFL_FUNC_COMMON_OP_END(Obj, Name, DefRet, ErrorCase) \
1306 __##Name##_op_create: EINA_COLD; \
1307 ___op = _efl_object_op_api_id_get(EFL_FUNC_COMMON_OP_FUNC(Name), Obj, #Name, __FILE__, __LINE__); \
1308 ___generation = _efl_object_init_generation; \
1309 if (EINA_UNLIKELY(___op == EFL_NOOP)) goto __##Name##_failed; \
1310 goto __##Name##_op_create_done; \
1311 __##Name##_failed: EINA_COLD; \
1312 ErrorCase \
1313 return DefRet;
1314 #define _EFL_OBJECT_API_BEFORE_HOOK
1315 #define _EFL_OBJECT_API_AFTER_HOOK
1316 #define _EFL_OBJECT_API_CALL_HOOK(x) x
1317
1318 // to define an EAPI function
1319 #define _EFL_OBJECT_FUNC_BODY(Name, ObjType, Ret, DefRet, ErrorCase) \
1320 Ret \
1321 Name(ObjType obj) \
1322 { \
1323 typedef Ret (*_Eo_##Name##_func)(Eo *, void *obj_data); \
1324 Ret _r; \
1325 EFL_FUNC_COMMON_OP(obj, Name, DefRet); \
1326 _EFL_OBJECT_API_BEFORE_HOOK \
1327 _r = _EFL_OBJECT_API_CALL_HOOK(_func_(___call.eo_id, ___call.data)); \
1328 _efl_object_call_end(&___call); \
1329 _EFL_OBJECT_API_AFTER_HOOK \
1330 return _r; \
1331 EFL_FUNC_COMMON_OP_END(obj, Name, DefRet, ErrorCase); \
1332 }
1333
1334 #define _EFL_OBJECT_VOID_FUNC_BODY(Name, ObjType, ErrorCase) \
1335 void \
1336 Name(ObjType obj) \
1337 { \
1338 typedef void (*_Eo_##Name##_func)(Eo *, void *obj_data); \
1339 EFL_FUNC_COMMON_OP(obj, Name, ); \
1340 _EFL_OBJECT_API_BEFORE_HOOK \
1341 _EFL_OBJECT_API_CALL_HOOK(_func_(___call.eo_id, ___call.data)); \
1342 _efl_object_call_end(&___call); \
1343 _EFL_OBJECT_API_AFTER_HOOK \
1344 return; \
1345 EFL_FUNC_COMMON_OP_END(obj, Name, , ErrorCase); \
1346 }
1347
1348 #define _EFL_OBJECT_FUNC_BODYV(Name, ObjType, Ret, DefRet, ErrorCase, Arguments, ...) \
1349 Ret \
1350 Name(ObjType obj, __VA_ARGS__) \
1351 { \
1352 typedef Ret (*_Eo_##Name##_func)(Eo *, void *obj_data, __VA_ARGS__); \
1353 Ret _r; \
1354 EFL_FUNC_COMMON_OP(obj, Name, DefRet); \
1355 _EFL_OBJECT_API_BEFORE_HOOK \
1356 _r = _EFL_OBJECT_API_CALL_HOOK(_func_(___call.eo_id, ___call.data, Arguments)); \
1357 _efl_object_call_end(&___call); \
1358 _EFL_OBJECT_API_AFTER_HOOK \
1359 return _r; \
1360 EFL_FUNC_COMMON_OP_END(obj, Name, DefRet, ErrorCase); \
1361 }
1362
1363 #define _EFL_OBJECT_VOID_FUNC_BODYV(Name, ObjType, ErrorCase, Arguments, ...) \
1364 void \
1365 Name(ObjType obj, __VA_ARGS__) \
1366 { \
1367 typedef void (*_Eo_##Name##_func)(Eo *, void *obj_data, __VA_ARGS__); \
1368 EFL_FUNC_COMMON_OP(obj, Name, ); \
1369 _EFL_OBJECT_API_BEFORE_HOOK \
1370 _EFL_OBJECT_API_CALL_HOOK(_func_(___call.eo_id, ___call.data, Arguments)); \
1371 _efl_object_call_end(&___call); \
1372 _EFL_OBJECT_API_AFTER_HOOK \
1373 return; \
1374 EFL_FUNC_COMMON_OP_END(obj, Name, , ErrorCase); \
1375 }
1376
1377 #define EFL_FUNC_BODY(Name, Ret, DefRet) _EFL_OBJECT_FUNC_BODY(Name, Eo *, Ret, DefRet, )
1378 #define EFL_VOID_FUNC_BODY(Name) _EFL_OBJECT_VOID_FUNC_BODY(Name, Eo *, )
1379 #define EFL_FUNC_BODYV(Name, Ret, DefRet, Arguments, ...) _EFL_OBJECT_FUNC_BODYV(Name, Eo *, Ret, DefRet, , EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1380 #define EFL_VOID_FUNC_BODYV(Name, Arguments, ...) _EFL_OBJECT_VOID_FUNC_BODYV(Name, Eo *, , EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1381
1382 #define EFL_FUNC_BODY_CONST(Name, Ret, DefRet) _EFL_OBJECT_FUNC_BODY(Name, const Eo *, Ret, DefRet, )
1383 #define EFL_VOID_FUNC_BODY_CONST(Name) _EFL_OBJECT_VOID_FUNC_BODY(Name, const Eo *, )
1384 #define EFL_FUNC_BODYV_CONST(Name, Ret, DefRet, Arguments, ...) _EFL_OBJECT_FUNC_BODYV(Name, const Eo *, Ret, DefRet, , EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1385 #define EFL_VOID_FUNC_BODYV_CONST(Name, Arguments, ...) _EFL_OBJECT_VOID_FUNC_BODYV(Name, const Eo *, , EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1386
1387 // The following macros are also taking a FallbackCall the call you specify there will be called once the call cannot be redirected to a object,
1388 // which means eo will be the deepest scope this call will ever get.
1389
1390 #define EFL_FUNC_BODY_FALLBACK(Name, Ret, DefRet, FallbackCall) _EFL_OBJECT_FUNC_BODY(Name, Eo *, Ret, DefRet, FallbackCall)
1391 #define EFL_VOID_FUNC_BODY_FALLBACK(Name, FallbackCall) _EFL_OBJECT_VOID_FUNC_BODY(Name, Eo *, FallbackCall)
1392 #define EFL_FUNC_BODYV_FALLBACK(Name, Ret, DefRet, FallbackCall, Arguments, ...) _EFL_OBJECT_FUNC_BODYV(Name, Eo *, Ret, DefRet, FallbackCall, EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1393 #define EFL_VOID_FUNC_BODYV_FALLBACK(Name, FallbackCall, Arguments, ...) _EFL_OBJECT_VOID_FUNC_BODYV(Name, Eo *, FallbackCall, EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1394
1395 #define EFL_FUNC_BODY_CONST_FALLBACK(Name, Ret, DefRet, FallbackCall) _EFL_OBJECT_FUNC_BODY(Name, const Eo *, Ret, DefRet, FallbackCall)
1396 #define EFL_VOID_FUNC_BODY_CONST_FALLBACK(Name, FallbackCall) _EFL_OBJECT_VOID_FUNC_BODY(Name, const Eo *, FallbackCall)
1397 #define EFL_FUNC_BODYV_CONST_FALLBACK(Name, Ret, DefRet, FallbackCall, Arguments, ...) _EFL_OBJECT_FUNC_BODYV(Name, const Eo *, Ret, DefRet, FallbackCall, EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1398 #define EFL_VOID_FUNC_BODYV_CONST_FALLBACK(Name, FallbackCall, Arguments, ...) _EFL_OBJECT_VOID_FUNC_BODYV(Name, const Eo *, FallbackCall, EFL_FUNC_CALL(Arguments), __VA_ARGS__)
1399
1400 #ifndef _WIN32
1401 # define _EFL_OBJECT_OP_API_ENTRY(a) (void*)a
1402 #else
1403 # define _EFL_OBJECT_OP_API_ENTRY(a) #a
1404 #endif
1405
1406 #define EFL_OBJECT_OP_FUNC(_api, _private) { _EFL_OBJECT_OP_API_ENTRY(_api), (void*)_private }
1407
1408 // returns the OP id corresponding to the given api_func
1409 EAPI Efl_Object_Op _efl_object_api_op_id_get(const void *api_func) EINA_DEPRECATED;
1410 EAPI Efl_Object_Op _efl_object_op_api_id_get(const void *api_func, const Eo *obj, const char *api_func_name, const char *file, int line) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT;
1411
1412 // gets the real function pointer and the object data
1413 EAPI Eina_Bool _efl_object_call_resolve(Eo *obj, const char *func_name, Efl_Object_Op_Call_Data *call, Efl_Object_Op op, const char *file, int line);
1414
1415 // end of the eo call barrier, unref the obj
1416 EAPI void _efl_object_call_end(Efl_Object_Op_Call_Data *call);
1417
1418 // end of the efl_add. Calls finalize among others
1419 EAPI Eo * _efl_add_end(Eo *obj, Eina_Bool is_ref, Eina_Bool is_fallback);
1420
1421 /*****************************************************************************/
1422
1423 /**
1424 * @brief Prepare a call to the parent class implementation of a function.
1425 *
1426 * @param obj The object to call (can be a class).
1427 * @param cur_klass The current class.
1428 * @return An EO handle which must be used as part of an EO function call.
1429 *
1430 * @warning The returned value must always be used as the first argument (the
1431 * object) of a method or property function call, and should never be handled
1432 * in any other way. Do not call any function from this file on the returned
1433 * value (eg. efl_ref, etc...).
1434 *
1435 * Usage:
1436 * @code
1437 * // Inside the implementation code for MY_CLASS
1438 * my_property_set(efl_super(obj, MY_CLASS), value);
1439 * @endcode
1440 *
1441 * A common usage pattern is to forward function calls to the parent function:
1442 * @code
1443 * EOLIAN static void
1444 * _my_class_my_property_set(Eo *obj, My_Class_Data *pd, int value)
1445 * {
1446 * // Do some processing on this class data, or on the value
1447 * if (value < 0) value = 0;
1448 * pd->last_value = value;
1449 * // Pass the call to the parent class
1450 * my_property_set(efl_super(obj, MY_CLASS), value);
1451 * // Do some more processing
1452 * }
1453 * @endcode
1454 *
1455 * @p cur_klass must be a valid class in the inheritance hierarchy of @p obj's
1456 * class. Invalid values will lead to undefined behaviour.
1457 *
1458 * @see efl_cast
1459 */
1460 EAPI Eo *efl_super(const Eo *obj, const Efl_Class *cur_klass);
1461
1462 /**
1463 * @brief Prepare a call to cast to a parent class implementation of a function.
1464 *
1465 * @param obj The object to call (can be a class).
1466 * @param cur_klass The class to cast into.
1467 * @return An EO handle that must be used as part of an EO function call.
1468 *
1469 * @warning The returned value must always be used as the first argument (the
1470 * object) of a method or property function call and should never be handled
1471 * in any other way. Do not call any function from this file on the returned
1472 * value (eg. efl_ref, etc...).
1473 *
1474 * Usage:
1475 * @code
1476 * // Inside the implementation code for MY_CLASS
1477 * my_property_set(efl_cast(obj, SOME_OTHER_CLASS), value);
1478 * @endcode
1479 *
1480 * In the above example, @p obj is assumed to inherit from @c SOME_OTHER_CLASS
1481 * as either a mixin or direct class inheritance. If @c SOME_OTHER_CLASS
1482 * implements @c my_property.set then that implementation shall be called,
1483 * otherwise the call will be propagated to the parent implementation (if any).
1484 *
1485 * @p cur_klass must be a valid class in the inheritance hierarchy of @p obj's
1486 * class. Invalid values will lead to undefined behaviour.
1487 *
1488 * @see efl_cast
1489 *
1490 * @since 1.20
1491 */
1492 EAPI Eo *efl_cast(const Eo *obj, const Efl_Class *cur_klass);
1493
1494 /*****************************************************************************/
1495
1496 /**
1497 * @brief Gets the class of the object.
1498 * @param obj The object to work on
1499 * @return The object's class.
1500 *
1501 * @see efl_class_name_get()
1502 */
1503 EAPI const Efl_Class *efl_class_get(const Eo *obj);
1504
1505 EAPI Eo *_efl_added_get(void);
1506
1507 /* Check if GCC compatible (both GCC and clang define this) */
1508 #if defined(__GNUC__) && !defined(_EO_ADD_FALLBACK_FORCE)
1509
1510 # define efl_added __efl_added
1511
1512 # define _efl_add_common(klass, parent, is_ref, ...) \
1513 ({ \
1514 Eo * const __efl_added = _efl_add_internal_start(__FILE__, __LINE__, klass, parent, is_ref, EINA_FALSE); \
1515 (void) ((void)0, ##__VA_ARGS__); \
1516 (Eo *) _efl_add_end(efl_added, is_ref, EINA_FALSE); \
1517 })
1518
1519 #else
1520
1521 # define efl_added _efl_added_get()
1522
1523 # define _efl_add_common(klass, parent, is_ref, ...) \
1524 ( \
1525 _efl_add_internal_start(__FILE__, __LINE__, klass, parent, is_ref, EINA_TRUE), \
1526 ##__VA_ARGS__, \
1527 (Eo *) _efl_add_end(efl_added, is_ref, EINA_TRUE) \
1528 )
1529
1530 #endif
1531
1532 /**
1533 * @def efl_add
1534 * @brief Create a new object and add it to an existing parent object.
1535 *
1536 * The object returned by this function will always have 1 ref
1537 * (reference count) which belongs to its parent. Therefore, it is not safe
1538 * to use the returned object outside the constructor methods passed as
1539 * parameters. If you need to further manipulate the object, use #efl_add_ref
1540 * and remember to #efl_unref the object when done.
1541 *
1542 * If the object is created using this function, then it will
1543 * automatically be deleted when the parent object is.
1544 * There is no need to call efl_unref on the child. This is convenient
1545 * in C.
1546 *
1547 * If the object's class has a constructor, it is called.
1548 *
1549 * @param klass The class of the object to create.
1550 * @param parent The parent to set to the object (MUST not be @c NULL)
1551 * @param ... The ops to run.
1552 * @return An handle to the new object on success, NULL otherwise.
1553 */
1554 #define efl_add(klass, parent, ...) _efl_add_common(klass, parent, EINA_FALSE, ##__VA_ARGS__)
1555
1556 /**
1557 * @def efl_add_ref
1558 * @brief Create a new object, add it to an existing parent object and return
1559 * an extra reference for further manipulation.
1560 *
1561 * The object returned by this function has 1 ref which belongs to the caller.
1562 * If a parent object is provided (@c parent is not @c NULL) then the object
1563 * has an additional reference for the parent. Note that if a child object is
1564 * created in this way then it won't get automatically deleted with the parent.
1565 * You need to manually remove the extra ref by calling #efl_unref.
1566 *
1567 * If the object's class has a constructor, it is called.
1568 *
1569 * @param klass The class of the object to create.
1570 * @param parent The parent to set to the object (can be @c NULL).
1571 * @param ... The ops to run.
1572 * @return An handle to the new object on success, NULL otherwise.
1573 */
1574 #define efl_add_ref(klass, parent, ...) _efl_add_common(klass, parent, EINA_TRUE, ##__VA_ARGS__)
1575
1576 /**
1577 * @def efl_new
1578 * @brief Create a new object
1579 *
1580 * The object returned by this function has 1 ref which belongs to the caller.
1581 * You need to manually remove the ref by calling #efl_unref when you are done
1582 * working with the object. The object will be destroyed when all other refs
1583 * obtained with #efl_ref have been returned with #efl_unref.
1584 *
1585 * If the object's class has a constructor, it is called.
1586 *
1587 * @param klass The class of the object to create.
1588 * @param ... The ops to run.
1589 * @return An handle to the new object on success, NULL otherwise.
1590 */
1591 #define efl_new(klass, ...) efl_add_ref(klass, NULL, ##__VA_ARGS__)
1592
1593 EAPI Eo * _efl_add_internal_start(const char *file, int line, const Efl_Class *klass_id, Eo *parent, Eina_Bool ref, Eina_Bool is_fallback);
1594
1595 /**
1596 * @typedef Efl_Substitute_Ctor_Cb
1597 * Callback to be called instead of the object constructor.
1598 *
1599 * Only intended for binding creators.
1600 *
1601 * @param data Additional data previously supplied by the user
1602 * @param obj_id The object being constructed.
1603 * @return The constructed object in case of success, NULL otherwise.
1604 */
1605 typedef Eo *(*Efl_Substitute_Ctor_Cb)(void *data, Eo *obj_id);
1606
1607 /**
1608 * @brief Just like _efl_add_internal_start() but with additional options
1609 *
1610 * Only intended for binding creators.
1611 *
1612 * @param file File name of the call site, used for debug logs.
1613 * @param line Line number of the call site, used for debug logs.
1614 * @param klass_id Pointer for the class being instantiated.
1615 * @param ref Whether or not the object will have an additional reference if it has a parent.
1616 * @param parent Object parent, can be NULL.
1617 * @param is_fallback Whether or not the fallback @c efl_added behaviour is to be used.
1618 * @param substitute_ctor Optional callback to replace the call for efl_constructor(), if NULL efl_constructor() will be called normally.
1619 * @param sub_ctor_data Additional data to be passed to the @p substitute_ctor callback.
1620 * @return An handle to the new object on success, NULL otherwise.
1621 */
1622 EAPI Eo * _efl_add_internal_start_bindings(const char *file, int line, const Efl_Class *klass_id, Eo *parent, Eina_Bool ref, Eina_Bool is_fallback, Efl_Substitute_Ctor_Cb substitute_ctor, void *sub_ctor_data);
1623
1624 /**
1625 * @brief Unrefs the object and reparents it to NULL.
1626 *
1627 * Because efl_del() unrefs and reparents to NULL, it doesn't really delete the
1628 * object.
1629 *
1630 * This method accepts a const object for convenience, so all objects can be
1631 * passed to it easily.
1632 * @param[in] obj The object.
1633 *
1634 * @ingroup Efl_Object
1635 */
1636 EAPI void efl_del(const Eo *obj);
1637
1638 /**
1639 * @brief Set an override for a class
1640 *
1641 * This can be used to override a class with another class such that when @p klass is added
1642 * with efl_add(), an object of type @p override is returned.
1643 *
1644 * @param[in] klass The class to be overridden
1645 * @param[in] override The class to override with; must inherit from or implement @p klass
1646 * @return Return @c true if the override was successfully set
1647 *
1648 * @ingroup Efl_Object
1649 */
1650 EAPI Eina_Bool efl_class_override_register(const Efl_Class *klass, const Efl_Class *override);
1651
1652 /**
1653 * @brief Unset an override for a class
1654 *
1655 * This is used to unset a previously-set override on a given class. It will only succeed if
1656 * @p override is the currently-set override for @p klass.
1657 *
1658 * @param[in] klass The class to unset the override from
1659 * @param[in] override The class override to be removed
1660 * @return Return @c true if the override was successfully unset
1661 *
1662 * @ingroup Efl_Object
1663 */
1664 EAPI Eina_Bool efl_class_override_unregister(const Efl_Class *klass, const Efl_Class *override);
1665 /**
1666 * @brief Get a pointer to the data of an object for a specific class.
1667 *
1668 * The data reference count is not incremented. The pointer must be used only
1669 * in the scope of the function and its callees.
1670 *
1671 * @param obj the object to work on.
1672 * @param klass the klass associated with the data.
1673 * @return a pointer to the data.
1674 *
1675 * @see efl_data_ref()
1676 * @see efl_data_unref()
1677 * @see efl_data_scope_safe_get()
1678 */
1679 EAPI void *efl_data_scope_get(const Eo *obj, const Efl_Class *klass);
1680
1681 /**
1682 * @brief Safely get a pointer to the data of an object for a specific class.
1683 *
1684 * This call runs a dynamic check and returns NULL if there is no valid data
1685 * to return.
1686 *
1687 * The data reference count is not incremented. The pointer must be used only
1688 * in the scope of the function and its callees. This function will return NULL
1689 * if there is no data for this class, or if this object is not an instance of
1690 * the given class. The function will return NULL if the data size is 0.
1691 * Note that objects of class A inheriting from another class C as an
1692 * interface (like: class A(B, C) {} ) will have no data for class C. This
1693 * means that efl_isa(a, C) will return true but there is no data for C. This
1694 * function's behaviour is similar to efl_data_scope_get() when running in
1695 * debug mode (but this prints less error logs).
1696 *
1697 * @param obj the object to work on.
1698 * @param klass the klass associated with the data.
1699 * @return a pointer to the data or NULL in case of error or $obj was NULL.
1700 *
1701 * @see efl_data_scope_get()
1702 *
1703 * @since 1.20
1704 */
1705 EAPI void *efl_data_scope_safe_get(const Eo *obj, const Efl_Class *klass);
1706
1707 /**
1708 * @def efl_data_xref(obj, klass, ref_obj)
1709 * Use this macro if you want to associate a referencer object.
1710 * Convenience macro around efl_data_xref_internal()
1711 */
1712 #define efl_data_xref(obj, klass, ref_obj) efl_data_xref_internal(__FILE__, __LINE__, obj, klass, ref_obj)
1713
1714 /**
1715 * @def efl_data_ref(obj, klass)
1716 * Use this macro if you don't want to associate a referencer object.
1717 * Convenience macro around efl_data_xref_internal()
1718 */
1719 #define efl_data_ref(obj, klass) efl_data_xref_internal(__FILE__, __LINE__, obj, klass, (const Eo *)obj)
1720
1721 /**
1722 * @brief Get a pointer to the data of an object for a specific class and
1723 * increment the data reference count.
1724 * @param obj the object to work on.
1725 * @param klass the klass associated with the data.
1726 * @param ref_obj the object that references the data.
1727 * @param file the call's filename.
1728 * @param line the call's line number.
1729 * @return a pointer to the data.
1730 *
1731 * @see efl_data_xunref_internal()
1732 */
1733 EAPI void *efl_data_xref_internal(const char *file, int line, const Eo *obj, const Efl_Class *klass, const Eo *ref_obj);
1734
1735 /**
1736 * @def efl_data_xunref(obj, data, ref_obj)
1737 * Use this function if you used efl_data_xref to reference the data.
1738 * Convenience macro around efl_data_xunref_internal().
1739 * @see efl_data_xref()
1740 */
1741 #define efl_data_xunref(obj, data, ref_obj) efl_data_xunref_internal(obj, data, ref_obj)
1742
1743 /**
1744 * @def efl_data_unref(obj, data)
1745 * Use this function if you used efl_data_ref to reference the data.
1746 * Convenience macro around efl_data_unref_internal().
1747 * @see efl_data_ref()
1748 */
1749 #define efl_data_unref(obj, data) efl_data_xunref_internal(obj, data, obj)
1750
1751 /**
1752 * @brief Decrement the object data reference count by 1.
1753 * @param obj the object to work on.
1754 * @param data a pointer to the data to unreference.
1755 * @param file the call's filename.
1756 * @param line the call's line number.
1757 *
1758 * @see efl_data_xref_internal()
1759 */
1760 EAPI void efl_data_xunref_internal(const Eo *obj, void *data, const Eo *ref_obj);
1761
1762 /**
1763 * @brief Increment the object's reference count by 1.
1764 * @param obj the object to work on.
1765 * @return The object passed.
1766 *
1767 * It's very easy to get a refcount leak and start leaking memory because
1768 * of a forgotten unref or an extra ref. Both efl_xref
1769 * and efl_xunref that make debugging easier in these situations.
1770 * These functions should only be used on a small scale i.e at the
1771 * start of some section in which an object may be freed unless you really
1772 * know what you are doing.
1773 *
1774 * @see efl_unref()
1775 * @see efl_ref_count()
1776 */
1777 EAPI Eo *efl_ref(const Eo *obj);
1778
1779 /**
1780 * @brief Decrement the object's reference count by 1 and free it if needed.
1781 * @param obj the object to work on.
1782 *
1783 * @see efl_ref()
1784 * @see efl_ref_count()
1785 */
1786 EAPI void efl_unref(const Eo *obj);
1787
1788 /**
1789 * @brief Return the ref count of the object passed.
1790 * @param obj the object to work on.
1791 * @return the ref count of the object.
1792 *
1793 * @see efl_ref()
1794 * @see efl_unref()
1795 */
1796 EAPI int efl_ref_count(const Eo *obj);
1797
1798 /**
1799 * @brief Set a deletion interceptor function.
1800 * @param obj The object to set the interceptor on.
1801 * @param del_intercept_func The interceptor function to call.
1802 *
1803 * This sets the function @p del_intercept_func to be called when an object
1804 * is about to go from a reference count of 1 to 0, thus triggering actual
1805 * destruction of the object. Instead of going to a reference count of 0 and
1806 * being destroyed, the object will stay alive with a reference count of 1
1807 * and this intercept function will be called instead.
1808 * The interceptor function handles any further deletion of of the object
1809 * from here.
1810 *
1811 * Note that by default objects have no interceptor function set and thus
1812 * will be destroyed as normal. To return an object to this state, simply
1813 * set the @p del_intercept_func to NULL which is the default.
1814 *
1815 * A good use for this feature is to ensure an object is destroyed by its
1816 * owning main loop and not in a foreign loop. This makes it possible to
1817 * safely unrefor delete objects from any loop as an interceptor can be set
1818 * on an object that will abort destruction and instead queue the object
1819 * on its owning loop to be destroyed at some time in the future and now
1820 * set the intercept function to NULL so it is not called again on the next
1821 * "real deletion".
1822 *
1823 * @see efl_del_intercept_get()
1824 * @see efl_unref()
1825 * @see efl_del()
1826 */
1827 EAPI void efl_del_intercept_set(Eo *obj, Efl_Del_Intercept del_intercept_func);
1828
1829 /**
1830 * @brief Get the deletion interceptor function
1831 * @param obj The object to get the interceptor of
1832 * @return The intercept function or NULL if none is set.
1833 *
1834 * This returns the interceptor function set by efl_del_intercept_set(). Note
1835 * that objects by default have no interceptor (NULL) set but certain
1836 * classes may set one up in a constructor. Make sure that
1837 * the interceptor function knows if this has happened.
1838 * If you want to override the interceptor be sure to call it after your
1839 * own interceptor function has finished. It's generally be a bad idea
1840 * to override these functions however.
1841 *
1842 * @see efl_del_intercept_set()
1843 */
1844 EAPI Efl_Del_Intercept efl_del_intercept_get(const Eo *obj);
1845
1846 /**
1847 * @brief Clears the object so it can be reused (for example in a cache).
1848 * @param obj The object to mark for reusal.
1849 *
1850 * This assumes the destructor has been called on the object so it
1851 * should probably only be used from the del intercept.
1852 *
1853 * @see efl_del_intercept_set()
1854 */
1855 EAPI void efl_reuse(const Eo *obj);
1856
1857 /**
1858 * @def efl_xref(obj, ref_obj)
1859 * Convenience macro around efl_xref_internal()
1860 * @see efl_xref()
1861 */
1862 #define efl_xref(obj, ref_obj) efl_xref_internal(__FILE__, __LINE__, obj, ref_obj)
1863
1864 /**
1865 * @brief Increment the object's reference count by 1 (and associate the ref with ref_obj).
1866 * @param obj the object to work on.
1867 * @param ref_obj the object that references obj.
1868 * @param file the call's filename.
1869 * @param line the call's line number.
1870 * @return The object passed (obj)
1871 *
1872 * Do not use this function, use #efl_xref instead.
1873 * A compile flag may make it and eobj_xunref() behave the same as eobj_ref()
1874 * and eobj_unref() respectively. This should be used wherever possible.
1875 *
1876 * @see efl_xunref()
1877 */
1878 EAPI Eo *efl_xref_internal(const char *file, int line, Eo *obj, const Eo *ref_obj);
1879
1880 /**
1881 * @brief Decrement the object's reference count by 1 and free it if needed. Will free the ref associated with ref_obj).
1882 * @param obj the object to work on.
1883 * @param ref_obj the object that references obj.
1884 *
1885 * This function only enforces the checks for object association. Don't rely
1886 * on it. If such enforces are compiled out this function behaves the same as
1887 * efl_unref().
1888 *
1889 * @see efl_xref_internal()
1890 */
1891 EAPI void efl_xunref(Eo *obj, const Eo *ref_obj);
1892
1893 /**
1894 * @brief Add a new weak reference to obj.
1895 *
1896 * This function registers the object handle pointed by wref to obj so when obj
1897 * is deleted, it'll be updated to NULL. The function should be used when you
1898 * want to keep track of an object in a safe way but you don't want to prevent
1899 * it from being freed.
1900 *
1901 * @param[in] wref The weak ref
1902 */
1903 EOAPI void efl_wref_add(Eo *obj, Efl_Object **wref);
1904
1905 /**
1906 * @brief Delete the weak reference passed.
1907 *
1908 * This function will set *wref to NULL after its execution.
1909 *
1910 * @param[in] wref The weak ref
1911 */
1912 EOAPI void efl_wref_del(Eo *obj, Efl_Object **wref);
1913
1914 /**
1915 * @brief Generic data with string key on an object.
1916 *
1917 * The user is in charge of freeing the data.
1918 *
1919 * @param[in] key The key associated with the data
1920 * @param[in] data The data to set
1921 */
1922 EOAPI void efl_key_data_set(Eo *obj, const char * key, const void *data);
1923
1924 /**
1925 * @brief Generic data with string key on an object.
1926 *
1927 * The user is in charge of freeing the data.
1928 *
1929 * @param[in] key The key associated with the data
1930 *
1931 * @return The data to set
1932 */
1933 EOAPI void *efl_key_data_get(const Eo *obj, const char * key);
1934
1935 /**
1936 * @brief Generic object reference with string key to object.
1937 *
1938 * The object will be automatically ref'd when set and unref'd when replaced or
1939 * deleted or when the referring object is deleted. If the referenced object
1940 * is deleted, then the key is deleted automatically.
1941 *
1942 * This is the same key store used by key_data and key_value. Keys are shared
1943 * and can store only one thing.
1944 *
1945 * @param[in] key The key associated with the object ref
1946 * @param[in] objdata The object to set
1947 */
1948 EOAPI void efl_key_ref_set(Eo *obj, const char * key, const Efl_Object *objdata);
1949
1950 /**
1951 * @brief Generic object reference with string key to object.
1952 *
1953 * The object will be automatically ref'd when set and unref'd when replaced or
1954 * deleted or when the referring object is deleted. If the referenced object is
1955 * deleted then the key is deleted automatically.
1956 *
1957 * This is the same key store used by key_data and key_value. Keys are shared
1958 * and can store only one thing.
1959 *
1960 * @param[in] key The key associated with the object ref
1961 *
1962 * @return The object to set
1963 */
1964 EOAPI Efl_Object *efl_key_ref_get(const Eo *obj, const char * key);
1965
1966 /**
1967 * @brief Generic weak object reference with string key to object.
1968 *
1969 * The object key will be removed if the object is removed, but will not take
1970 * or removed references like key_obj.
1971 *
1972 * This is the same key store used by key_data and key_value. Keys are shared
1973 * and can store only one thing.
1974 *
1975 * @param[in] key The key associated with the object ref
1976 * @param[in] objdata The object to set
1977 */
1978 EOAPI void efl_key_wref_set(Eo *obj, const char * key, const Efl_Object *objdata);
1979
1980 /**
1981 * @brief Generic weak object reference with string key to object.
1982 *
1983 * The object key will be removed if the object is removed, but will not take
1984 * or removed references like key_obj.
1985 *
1986 * This is the same key store used by key_data and key_value. Keys are shared
1987 * and can store only one thing
1988 *
1989 * @param[in] key The key associated with the object ref
1990 *
1991 * @return The object to set
1992 */
1993 EOAPI Efl_Object *efl_key_wref_get(const Eo *obj, const char * key);
1994
1995 /**
1996 * @brief Value on with string key on the object.
1997 *
1998 * This stores the value with the given string key on the object and it will be
1999 * freed when replaced or deleted, or when the referring object is deleted.
2000 *
2001 * This is the same key store used by key_data and key_obj. Keys are shared
2002 * and can store only one thing.
2003 *
2004 * @param[in] key The key associated with the value
2005 * @param[in] value The value to set
2006 */
2007 EOAPI void efl_key_value_set(Eo *obj, const char * key, Eina_Value *value);
2008
2009 /**
2010 * @brief Value on with string key on the object.
2011 *
2012 * This stores the value with the given string key on the object and it will be
2013 * freed when replaced or deleted, or when the referring object is deleted.
2014 *
2015 * This is the same key store used by key_data and key_obj. Keys are shared
2016 * and can store only one thing.
2017 *
2018 * @param[in] key The key associated with the value
2019 *
2020 * @return The value to set
2021 */
2022 EOAPI Eina_Value *efl_key_value_get(const Eo *obj, const char * key);
2023
2024 /**
2025 * @brief Enable or disable the manual free feature.
2026 * @param obj the object to work on.
2027 * @param manual_free indicates if the free is manual (EINA_TRUE) or automatic (EINA_FALSE).
2028 *
2029 * The developer is in charge of calling the function efl_manual_free to free the memory
2030 * allocated for this object.
2031 *
2032 * Do not use this unless you really know what you are doing. It's used by Evas
2033 * because evas wants to keep its private data available even after the object
2034 * is deleted. Setting this to true makes Eo destroy the object but doesn't free
2035 * the private data nor the object itself.
2036 *
2037 * @see efl_manual_free()
2038 */
2039 EAPI void efl_manual_free_set(Eo *obj, Eina_Bool manual_free);
2040
2041 /**
2042 * @brief Frees the object.
2043 * @param obj the object to work on.
2044 * This function must be called by the developer if the function
2045 * efl_manual_free_set has been called beforehand with the parameter EINA_TRUE.
2046 * An error will display if this function is called when the manual
2047 * free option is not set to EINA_TRUE or the number of refs is not 0.
2048 * @return EINA_TRUE if successfully freed. EINA_FALSE otherwise.
2049 *
2050 * @see efl_manual_free_set()
2051 */
2052 EAPI Eina_Bool efl_manual_free(Eo *obj);
2053
2054 /**
2055 * @brief Checks if the object was already descructed (only relevant for manual_free objects).
2056 * @param obj the object to check.
2057 * This function checks if the object was already destructed (but not alraedy
2058 * freed). It should only be used with objects that are supposed to be manually
2059 * freed but are not yet free such as those which have been destroyed.
2060 *
2061 * @see efl_manual_free_set()
2062 */
2063 EAPI Eina_Bool efl_destructed_is(const Eo *obj);
2064
2065 /**
2066 * @brief Set the given #Eina_Value to the property with the specified \c property_name.
2067 * @param obj The object to set the property on
2068 * @param property_name The name of the property to modify.
2069 * @param value The value to set, the value passed here will be flushed by the function
2070 *
2071 * @see efl_property_reflection_get() and efl_property_reflection_exist()
2072 */
2073 EAPI Eina_Error efl_property_reflection_set(Eo *obj, const char *property_name, Eina_Value value);
2074
2075 /**
2076 * @brief Retrieve an #Eina_Value containing the current value of the property specified with \c property_name.
2077 * @param obj The object to set the property on
2078 * @param property_name The name of the property to get.
2079 *
2080 * @return The value that got returned by the actual property in form of a generic Eina_Value. The user of this API is owning the returned Value.
2081 *
2082 * @see efl_property_reflection_set() and efl_property_reflection_exist()
2083 */
2084 EAPI Eina_Value efl_property_reflection_get(const Eo *obj, const char *property_name);
2085
2086 /**
2087 * @brief Check if a property exist for reflection.
2088 * @param obj The object to inspect.
2089 * @param property_name The name of the property to check if it exist.
2090 *
2091 * @return EINA_TRUE if the property exist, EINA_FALSE otherwise.
2092 *
2093 * @see efl_property_reflection_set() and efl_property_reflection_get()
2094 */
2095 EAPI Eina_Bool efl_property_reflection_exist(Eo *obj, const char *property_name);
2096
2097 /**
2098 * @addtogroup Efl_Class_Class Eo's Class class.
2099 * @{
2100 */
2101
2102 #include "efl_class.eo.h"
2103
2104 /**
2105 * @brief Get the type of this class.
2106 * @param klass The Efl_Class to get the type from.
2107 *
2108 * @return The type of this class or INVALID if the klass parameter was invalid.
2109 */
2110 EAPI Efl_Class_Type efl_class_type_get(const Efl_Class *klass);
2111
2112 /**
2113 * @}
2114 */
2115
2116 /**
2117 * @addtogroup Efl_Class_Base Eo's Base class.
2118 * @{
2119 */
2120
2121 /**
2122 * @typedef efl_key_data_free_func
2123 * Data free func prototype.
2124 * XXX: DO NOT USE, only here for legacy.
2125 */
2126 typedef void (*efl_key_data_free_func)(void *);
2127
2128 /**
2129 * @def efl_weak_ref
2130 * @brief Reference a pointer to an Eo object
2131 * @param wref the pointer to use for the weak ref
2132 *
2133 * @see efl_weak_unref
2134 * @see efl_wref_add
2135 */
2136 #define efl_weak_ref(wref) \
2137 do { \
2138 if (*wref) efl_wref_add(*wref, wref); \
2139 } while (0)
2140
2141 /**
2142 * @def efl_weak_unref
2143 * @brief Unreference a pointer to an Eo object
2144 * @param wref the pointer to use for the weak unref
2145 *
2146 * @see efl_weak_ref
2147 * @see efl_wref_del
2148 * @see efl_wref_del_safe
2149 */
2150 #define efl_weak_unref(wref) \
2151 do { \
2152 if (*wref) efl_wref_del(*wref, wref); \
2153 } while (0)
2154
2155 /**
2156 * @def efl_wref_del_safe
2157 * @brief Delete the weak reference passed.
2158 * @param wref the weak reference to free.
2159 *
2160 * @see #efl_wref_del
2161 */
2162 #define efl_wref_del_safe(wref) efl_weak_unref(wref)
2163
2164 /**
2165 * @}
2166 */
2167
2168 /**
2169 * @addtogroup Efl_Events Eo's Event Handling
2170 * @{
2171 */
2172
2173 /**
2174 * Helper for sorting callbacks array. Automatically used by
2175 * @ref EFL_CALLBACKS_ARRAY_DEFINE
2176 */
2177 EAPI int efl_callbacks_cmp(const Efl_Callback_Array_Item *a, const Efl_Callback_Array_Item *b);
2178
2179 /**
2180 * Helper for creating global callback arrays.
2181 * Problems occur here in windows where you can't declare a static array with
2182 * external symbols in them. These addresses are only known at runtime.
2183 * This also allows for automatic sorting for better performance.
2184 */
2185 #define EFL_CALLBACKS_ARRAY_DEFINE(Name, ...) \
2186 static Efl_Callback_Array_Item * \
2187 Name(void) \
2188 { \
2189 Efl_Callback_Array_Item tmp[] = { __VA_ARGS__ }; \
2190 static Efl_Callback_Array_Item internal[EINA_C_ARRAY_LENGTH(tmp) + 1] = \
2191 { { 0, 0 } }; \
2192 if (internal[0].desc == NULL) \
2193 { \
2194 memcpy(internal, tmp, sizeof(tmp)); \
2195 qsort(internal, EINA_C_ARRAY_LENGTH(internal) - 1, sizeof (internal[0]), \
2196 (int(*)(const void*,const void*)) efl_callbacks_cmp); \
2197 } \
2198 return internal; \
2199 }
2200
2201 /**
2202 * Helper for creating global scheduler arrays. The callback will be set by scheduler get.
2203 * Problems occur here in windows where you can't declare a static array with
2204 * external symbols in them. These addresses are only known at runtime.
2205 * This also allows for automatic sorting for better performance.
2206 */
2207 #define EFL_SCHEDULER_ARRAY_DEFINE(Name, ...) \
2208 static Efl_Callback_Array_Item * \
2209 Name(void) \
2210 { \
2211 const Efl_Event_Description *tmp[] = { __VA_ARGS__ }; \
2212 static Efl_Callback_Array_Item internal[EINA_C_ARRAY_LENGTH(tmp) + 1] = { { 0, 0 } }; \
2213 \
2214 if (internal[0].desc == NULL) \
2215 { \
2216 unsigned int i; \
2217 \
2218 for (i = 0; i < EINA_C_ARRAY_LENGTH(tmp); i++) \
2219 internal[i].desc = tmp[i]; \
2220 \
2221 qsort(internal, EINA_C_ARRAY_LENGTH(internal) - 1, sizeof (internal[0]), \
2222 (int(*)(const void*,const void*)) efl_callbacks_cmp); \
2223 } \
2224 return internal; \
2225 }
2226
2227 /**
2228 * @def efl_event_callback_add(obj, desc, cb, data)
2229 * Add a callback for an event.
2230 * @param[in] desc An #Efl_Event_Description of the event to listen to.
2231 * @param[in] cb the callback to call.
2232 * @param[in] data additional data to pass to the callback.
2233 *
2234 * Callbacks of the same priority are called in reverse order of creation.
2235 *
2236 * @see efl_event_callback_priority_add()
2237 */
2238 #define efl_event_callback_add(obj, desc, cb, data) \
2239 efl_event_callback_priority_add(obj, desc, \
2240 EFL_CALLBACK_PRIORITY_DEFAULT, cb, data)
2241
2242 /**
2243 * @def efl_event_callback_array_add(obj, desc, cb, data)
2244 * Add an array of callbacks for an event.
2245 *
2246 * @param[in] obj The object.
2247 * @param[in] array an #Efl_Callback_Array_Item of events to listen to.
2248 * @param[in] data additional data to pass to the callback.
2249 *
2250 * Callbacks of the same priority are called in reverse order of creation.
2251 * The array should have been created by @ref EFL_CALLBACKS_ARRAY_DEFINE. If
2252 * this isn't the case, be careful of portability issues and make sure that
2253 * it is properly sorted with @ref efl_callbacks_cmp.
2254 *
2255 * @see efl_event_callback_array_priority_add()
2256 */
2257 #define efl_event_callback_array_add(obj, array, data) \
2258 efl_event_callback_array_priority_add(obj, array, \
2259 EFL_CALLBACK_PRIORITY_DEFAULT, data)
2260
2261
2262 /**
2263 * @def efl_event_callback_forwarder_add(obj, desc, new_obj)
2264 * @brief Add an event callback forwarder for an event and an object.
2265 *
2266 * @param[in] obj The object.
2267 * @param[in] desc An #Efl_Event_Description of the event to forward to.
2268 * @param[in] new_obj The object to emit events from
2269 *
2270 * @ingroup Efl_Object
2271 */
2272 #define efl_event_callback_forwarder_add(obj, desc, new_obj) efl_event_callback_forwarder_priority_add(obj, desc, EFL_CALLBACK_PRIORITY_DEFAULT, new_obj)
2273
2274 /**
2275 * @brief Count the number of event handler registered for a specific event.
2276 *
2277 * @param[in] obj The object.
2278 * @param[in] desc The specific event.
2279 * @return The number of handler registered for this specific events.
2280 *
2281 * @ingroup Efl_Object
2282 */
2283 EOAPI unsigned int efl_event_callback_count(const Eo *obj, const Efl_Event_Description *desc);
2284
2285 /**
2286 * @brief Replace the previous Eo pointer with new content.
2287 *
2288 * @param storage Pointer to the space holding the object to be replaced.
2289 * It can not be @c NULL.
2290 * @param new_obj The new object. It may be @c NULL.
2291 * @return @c true if objects were different and thus replaced, @c false
2292 * if nothing happened, i.e. either the objects were the same or a @c NULL
2293 * pointer was wrongly given as @a storage.
2294 *
2295 * The object pointed by @c *storage must be previously an Eo or
2296 * @c NULL; if it is an Eo then it will be efl_unref(). The @a new_obj
2297 * will be passed to efl_ref() if not @c NULL, and then assigned to @c *storage.
2298 *
2299 * @note The return is NOT a success/error flag, it just signalizes if
2300 * the value has changed.
2301 * @see efl_ref()
2302 * @see efl_unref()
2303 */
2304 static inline Eina_Bool
efl_replace(Eo ** storage,const Eo * new_obj)2305 efl_replace(Eo **storage, const Eo *new_obj)
2306 {
2307 Eo *tmp = NULL;
2308
2309 EINA_SAFETY_ON_NULL_RETURN_VAL(storage, EINA_FALSE);
2310 if (*storage == new_obj) return EINA_FALSE;
2311 if (new_obj) tmp = efl_ref(new_obj);
2312 if (*storage) efl_unref(*storage);
2313 *storage = tmp;
2314 return EINA_TRUE;
2315 }
2316
2317 EOAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_OBJECT;
2318
2319 /**
2320 * @brief Create a new #Eina_Value containing the passed parameter.
2321 * @param obj The object to use
2322 * @return The #Eina_Value
2323 * @see eina_value_object_get(), eina_value_object_init()
2324 * @since 1.21
2325 */
2326 static inline Eina_Value *
eina_value_object_new(Eo * obj)2327 eina_value_object_new(Eo *obj)
2328 {
2329 Eina_Value *v;
2330
2331 v = eina_value_new(EINA_VALUE_TYPE_OBJECT);
2332 if (v) eina_value_set(v, obj);
2333 return v;
2334 }
2335
2336 /**
2337 * @brief Create a new #Eina_Value initialized with the passed parameter
2338 * @param obj The object to use
2339 * @return The #Eina_Value
2340 * @see eina_value_object_new(), eina_value_object_get()
2341 * @since 1.21
2342 */
2343 static inline Eina_Value
eina_value_object_init(Eo * obj)2344 eina_value_object_init(Eo *obj)
2345 {
2346 Eina_Value v = EINA_VALUE_EMPTY;
2347
2348 if (eina_value_setup(&v, EINA_VALUE_TYPE_OBJECT))
2349 eina_value_set(&v, obj);
2350 return v;
2351 }
2352
2353 /**
2354 * @brief Get the object contained in an #Eina_Value
2355 * @param v The #Eina_Value to extract the object from
2356 * @return The object.
2357 * @see eina_value_object_new(), eina_value_object_init()
2358 * @since 1.21
2359 */
2360 static inline Eo *
eina_value_object_get(const Eina_Value * v)2361 eina_value_object_get(const Eina_Value *v)
2362 {
2363 Eo *r = NULL;
2364
2365 if (!v) return NULL;
2366 if (eina_value_type_get(v) != EINA_VALUE_TYPE_OBJECT)
2367 return NULL;
2368
2369 if (!eina_value_pget(v, &r)) return NULL;
2370 return r;
2371 }
2372
2373 #ifdef EFL_BETA_API_SUPPORT
2374 /**
2375 * @brief Get if the object is in its main lifetime.
2376 * @param obj the object to check
2377 * @return true if the object is finalized, but not invalidating nor invalidated.
2378 * @since 1.22
2379 */
2380
2381 static inline Eina_Bool
efl_alive_get(const Eo * obj)2382 efl_alive_get(const Eo *obj)
2383 {
2384 return efl_finalized_get(obj) && !efl_invalidating_get(obj) && !efl_invalidated_get(obj);
2385 }
2386
2387 #endif /* EFL_BETA_API_SUPPORT */
2388
2389 /**
2390 * @brief Event triggered when a callback was added to the object
2391 */
2392 #define EFL_EVENT_CALLBACK_ADD (&(_EFL_EVENT_CALLBACK_ADD))
2393 EAPI extern const Efl_Event_Description _EFL_EVENT_CALLBACK_ADD;
2394
2395 /**
2396 * @brief Event triggered when a callback was removed from the object
2397 */
2398 #define EFL_EVENT_CALLBACK_DEL (&(_EFL_EVENT_CALLBACK_DEL))
2399 EAPI extern const Efl_Event_Description _EFL_EVENT_CALLBACK_DEL;
2400
2401 /**
2402 * @}
2403 */
2404
2405 /**
2406 * @addtogroup Eo_Iterators Eo iterators
2407 * @{
2408 */
2409
2410 /**
2411 * @brief Get an iterator on the Eo classes.
2412 *
2413 * You can use this function to go over the Eo classes.
2414 *
2415 * @return an iterator on success, NULL otherwise
2416 */
2417 EAPI Eina_Iterator *eo_classes_iterator_new(void);
2418
2419 /**
2420 * @brief Get an iterator on the Eo objects
2421 *
2422 * You can use this function to go over the Eo objects.
2423 *
2424 * @return an iterator on success, NULL otherwise
2425 */
2426 EAPI Eina_Iterator *eo_objects_iterator_new(void);
2427
2428 /**
2429 * @brief Check if a object can be owned
2430 *
2431 * This API checks if the passed object has at least one free reference that is not taken by the parent relation.
2432 * If this is not the case, a ERR will be printed.
2433 *
2434 * @return EINA_TRUE if the object is ownable. EINA_FALSE if not.
2435 */
2436 EAPI Eina_Bool efl_ownable_get(const Eo *obj);
2437
2438 /**
2439 * @}
2440 */
2441
2442 /**
2443 * @}
2444 */
2445
2446
2447 #ifdef __cplusplus
2448 }
2449 #endif
2450
2451 #undef EAPI
2452 #define EAPI
2453
2454 #undef EOAPI
2455 #define EOAPI
2456
2457 #endif
2458