Functions dealing with Evas smart objects (instances). More...
Modules | |
| Clipped Smart Object | |
| Clipped smart object is a base to construct other smart objects based on the concept of having an internal clipper that is applied to all children objects. | |
| Box Smart Object | |
| A box is a convenience smart object that packs children inside it in sequence, using a layouting function specified by the user. | |
| Table Smart Object. | |
| Convenience smart object that packs children using a tabular layout using children size hints to define their size and alignment inside their cell space. | |
| Grid Smart Object. | |
| Convenience smart object that packs children under a regular grid layout, using their virtual grid location and size to determine children's positions inside the grid object's area. | |
Functions | |
| EVAS_API void | evas_smart_legacy_type_register (const char *type, const Efl_Class *klass) |
| Registers an object type and its associated class. More... | |
| EVAS_API void | evas_smart_objects_calculate (Eo *obj) |
Call user-provided calculate smart functions and unset the flag signalling that the object needs to get recalculated to all smart objects in the canvas. | |
| EVAS_API Eina_Bool | evas_smart_objects_calculating_get (const Eo *obj) |
| Get if the canvas is currently calculating smart objects. More... | |
| EVAS_API Evas_Object * | evas_object_smart_add (Evas *e, Evas_Smart *s) |
Instantiates a new smart object described by s. More... | |
| EVAS_API void | evas_object_smart_member_add (Evas_Object *obj, Evas_Object *smart_obj) |
| Set an Evas object as a member of a given smart object. More... | |
| EVAS_API void | evas_object_smart_member_del (Evas_Object *obj) |
| Removes a member object from a given smart object. More... | |
| EVAS_API void | evas_object_smart_callback_add (Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) |
Add (register) a callback function to the smart event specified by event on the smart object obj. More... | |
| EVAS_API void | evas_object_smart_callback_priority_add (Evas_Object *obj, const char *event, Evas_Callback_Priority priority, Evas_Smart_Cb func, const void *data) |
Add (register) a callback function to the smart event specified by event on the smart object obj. More... | |
| EVAS_API void * | evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) |
Delete (unregister) a callback function from the smart event specified by event on the smart object obj. More... | |
| EVAS_API void * | evas_object_smart_callback_del_full (Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) |
Delete (unregister) a callback function from the smart event specified by event on the smart object obj. More... | |
| EVAS_API void | evas_object_smart_callback_call (Evas_Object *obj, const char *event, void *event_info) |
Call a given smart callback on the smart object obj. More... | |
| EVAS_API const void * | evas_object_smart_interface_get (const Evas_Object *obj, const char *name) |
| Retrieve an Evas smart object's interface, by name string pointer. More... | |
| EVAS_API void * | evas_object_smart_interface_data_get (const Evas_Object *obj, const Evas_Smart_Interface *iface) |
| Retrieve an Evas smart object interface's private data. More... | |
| EVAS_API Eina_Bool | evas_object_smart_type_check (const Evas_Object *obj, const char *type) |
| Checks whether a given smart object or any of its smart object parents is of a given smart class. More... | |
| EVAS_API Eina_Bool | evas_object_smart_type_check_ptr (const Evas_Object *obj, const char *type) |
| Checks whether a given smart object or any of its smart object parents is of a given smart class, using pointer comparison. More... | |
| EVAS_API Eina_Bool | evas_object_smart_callbacks_descriptions_set (Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) |
| Set an smart object instance's smart callbacks descriptions. More... | |
| EVAS_API void | evas_object_smart_callbacks_descriptions_get (const Evas_Object *obj, const Evas_Smart_Cb_Description ***class_descriptions, unsigned int *class_count, const Evas_Smart_Cb_Description ***instance_descriptions, unsigned int *instance_count) |
| Retrieve an smart object's know smart callback descriptions (both instance and class ones). More... | |
| EVAS_API void | evas_object_smart_callback_description_find (const Evas_Object *obj, const char *name, const Evas_Smart_Cb_Description **class_description, const Evas_Smart_Cb_Description **instance_description) |
Find callback description for callback called name or null if not found. More... | |
| EVAS_API Evas_Smart * | evas_object_smart_smart_get (const Evas_Object *obj) |
Get the Evas_Smart from which obj smart object was created. More... | |
| EVAS_API void | evas_object_smart_data_set (Evas_Object *obj, void *data) |
| Store a pointer to user data for a given smart object. More... | |
| EVAS_API void * | evas_object_smart_data_get (const Evas_Object *obj) |
| Retrieves the pointer to user data for a given smart object. More... | |
| EVAS_API Evas_Object * | evas_object_smart_clipped_clipper_get (const Evas_Object *obj) |
| Get the clipper object for the given clipped smart object. More... | |
| EVAS_API Eina_List * | evas_object_smart_members_get (const Evas_Object *obj) |
| Retrieves the list of the member objects of a given Evas smart object. More... | |
| EVAS_API void | evas_object_smart_need_recalculate_set (Evas_Object *obj, Eina_Bool value) |
| Set or unset the flag signalling that a given smart object needs to get recalculated. More... | |
| EVAS_API Eina_Bool | evas_object_smart_need_recalculate_get (const Evas_Object *obj) |
| Get the value of the flag signalling that a given smart object needs to get recalculated. More... | |
| EVAS_API Eina_Iterator * | evas_object_smart_iterator_new (const Evas_Object *obj) |
| Retrieves an iterator of the member objects of a given Evas smart object. More... | |
| EVAS_API void | evas_object_smart_calculate (Evas_Object *obj) |
| Call the calculate() smart function immediately on a given smart object. More... | |
| EVAS_API void | evas_object_smart_changed (Evas_Object *obj) |
| Mark smart object as changed, dirty. More... | |
| EVAS_API void | evas_object_smart_move_children_relative (Evas_Object *obj, Evas_Coord dx, Evas_Coord dy) |
| Moves all children objects of a given smart object relative to a given offset. More... | |
Functions dealing with Evas smart objects (instances).
Smart objects are groupings of primitive Evas objects that behave as a cohesive group. For instance, a file manager icon may be a smart object composed of an image object, a text label and two rectangles that appear behind the image and text when the icon is selected. As a smart object, the normal Evas object API could be used on the icon object.
Besides that, generally smart objects implement a specific API, so that users interact with its own custom features. The API takes form of explicit exported functions one may call and smart callbacks.
Smart objects can elect events (smart events, from now on) occurring inside of them to be reported back to their users via callback functions (smart callbacks). This way, you can extend Evas' own object events. They are defined by an event string that identifies them uniquely. There's also a function prototype definition for the callback functions: Evas_Smart_Cb.
When defining an Evas_Smart_Class, smart object implementors are strongly encouraged to properly set the Evas_Smart_Class::callbacks callbacks description array, so that the users of the smart object can have introspection on its events API at run time.
See some examples of this group of functions.
| EVAS_API void evas_smart_legacy_type_register | ( | const char * | type, |
| const Efl_Class * | klass | ||
| ) |
Registers an object type and its associated class.
LEGACY MECHANISM SUPPORT.
This function is invoked in the class constructor of smart classes. It will add the type and the class into a hash table that will then be used to check the type of an object. This function has been implemented to support legacy mechanism that checks objects types by name. USE IT ONLY FOR LEGACY SUPPORT. Otherwise, it is HIGHLY recommended to use efl_isa.
| type | The type (name string) to add. |
| klass | The class to associate to the type. |
References eina_hash_set().
| EVAS_API Eina_Bool evas_smart_objects_calculating_get | ( | const Eo * | obj | ) |
Get if the canvas is currently calculating smart objects.
| [in] | obj | The object. |
true if currently calculating smart objects. References EINA_FALSE.
| EVAS_API Evas_Object * evas_object_smart_add | ( | Evas * | e, |
| Evas_Smart * | s | ||
| ) |
Instantiates a new smart object described by s.
| e | the canvas on which to add the object |
| s | the Evas_Smart describing the smart object |
This is the function one should use when defining the public function adding an instance of the new smart object to a given canvas. It will take care of setting all of its internals to work as they should, if the user set things properly, as seem on the EVAS_SMART_SUBCLASS_NEW, for example.
References EINA_SAFETY_ON_FALSE_RETURN_VAL, and EVAS_CANVAS_CLASS.
| EVAS_API void evas_object_smart_member_add | ( | Evas_Object * | obj, |
| Evas_Object * | smart_obj | ||
| ) |
Set an Evas object as a member of a given smart object.
| obj | The member object |
| smart_obj | The smart object |
Members will automatically be stacked and layered together with the smart object. The various stacking functions will operate on members relative to the other members instead of the entire canvas, since they now live on an exclusive layer (see evas_object_stack_above(), for more details).
Any smart_obj object's specific implementation of the member_add() smart function will take place too, naturally.
| EVAS_API void evas_object_smart_member_del | ( | Evas_Object * | obj | ) |
Removes a member object from a given smart object.
| obj | the member object |
This removes a member object from a smart object, if it was added to any. The object will still be on the canvas, but no longer associated with whichever smart object it was associated with.
| EVAS_API void evas_object_smart_callback_add | ( | Evas_Object * | obj, |
| const char * | event, | ||
| Evas_Smart_Cb | func, | ||
| const void * | data | ||
| ) |
Add (register) a callback function to the smart event specified by event on the smart object obj.
| obj | a smart object |
| event | the event's name string |
| func | the callback function |
| data | user data to be passed to the callback function |
Smart callbacks look very similar to Evas callbacks, but are implemented as smart object's custom ones.
This function adds a function callback to an smart object when the event named event occurs in it. The function is func.
In the event of a memory allocation error during addition of the callback to the object, evas_alloc_error() should be used to determine the nature of the error, if any, and the program should sensibly try and recover.
A smart callback function must have the Evas_Smart_Cb prototype definition. The first parameter (data) in this definition will have the same value passed to evas_object_smart_callback_add() as the data parameter, at runtime. The second parameter obj is a handle to the object on which the event occurred. The third parameter, event_info, is a pointer to data which is totally dependent on the smart object's implementation and semantic for the given event.
There is an infrastructure for introspection on smart objects' events (see evas_smart_callbacks_descriptions_get()), but no internal smart objects on Evas implement them yet.
References EVAS_CALLBACK_PRIORITY_DEFAULT, and evas_object_smart_callback_priority_add().
| EVAS_API void evas_object_smart_callback_priority_add | ( | Evas_Object * | obj, |
| const char * | event, | ||
| Evas_Callback_Priority | priority, | ||
| Evas_Smart_Cb | func, | ||
| const void * | data | ||
| ) |
Add (register) a callback function to the smart event specified by event on the smart object obj.
Except for the priority field, it's exactly the same as evas_object_smart_callback_add
| obj | a smart object |
| event | the event's name string |
| priority | The priority of the callback, lower values called first. |
| func | the callback function |
| data | user data to be passed to the callback function |
References eina_inlist_append(), and EINA_INLIST_GET.
Referenced by evas_object_smart_callback_add().
| EVAS_API void * evas_object_smart_callback_del | ( | Evas_Object * | obj, |
| const char * | event, | ||
| Evas_Smart_Cb | func | ||
| ) |
Delete (unregister) a callback function from the smart event specified by event on the smart object obj.
| obj | a smart object |
| event | the event's name string |
| func | the callback function |
This function removes the first added smart callback on the object obj matching the event name event and the registered function pointer func. If the removal is successful it will also return the data pointer that was passed to evas_object_smart_callback_add() (that will be the same as the parameter) when the callback(s) was(were) added to the canvas. If not successful NULL will be returned.
References EINA_INLIST_FOREACH, EINA_INLIST_GET, and eina_inlist_remove().
| EVAS_API void * evas_object_smart_callback_del_full | ( | Evas_Object * | obj, |
| const char * | event, | ||
| Evas_Smart_Cb | func, | ||
| const void * | data | ||
| ) |
Delete (unregister) a callback function from the smart event specified by event on the smart object obj.
| obj | a smart object |
| event | the event's name string |
| func | the callback function |
| data | the data pointer that was passed to the callback |
This function removes the first added smart callback on the object obj matching the event name event, the registered function pointer func and the callback data pointer data. If the removal is successful it will also return the data pointer that was passed to evas_object_smart_callback_add() (that will be the same as the parameter) when the callback(s) was(were) added to the canvas. If not successful NULL will be returned. A common use would be to remove an exact match of a callback
type and func, use evas_object_smart_callback_del(). References EINA_INLIST_FOREACH, EINA_INLIST_GET, and eina_inlist_remove().
| EVAS_API void evas_object_smart_callback_call | ( | Evas_Object * | obj, |
| const char * | event, | ||
| void * | event_info | ||
| ) |
Call a given smart callback on the smart object obj.
| obj | the smart object |
| event | the event's name string |
| event_info | pointer to an event specific struct or information to pass to the callback functions registered on this smart event |
This should be called internally, from the smart object's own code, when some specific event has occurred and the implementor wants is to pertain to the object's events API (see Smart events and callbacks). The documentation for the smart object should include a list of possible events and what type of event_info to expect for each of them. Also, when defining an Evas_Smart_Class, smart object implementors are strongly encouraged to properly set the Evas_Smart_Class::callbacks callbacks description array, so that the users of the smart object can have introspection on its events API at run time.
Referenced by emotion_object_last_position_load(), and emotion_object_last_position_save().
| EVAS_API const void * evas_object_smart_interface_get | ( | const Evas_Object * | obj, |
| const char * | name | ||
| ) |
Retrieve an Evas smart object's interface, by name string pointer.
| obj | An Evas smart object. |
| name | Name string of the desired interface, which must be the same pointer used at the interface's declarion, when creating the smart object obj. |
NULL otherwise. References evas_object_smart_smart_get(), and _Evas_Smart_Interface::name.
| EVAS_API void * evas_object_smart_interface_data_get | ( | const Evas_Object * | obj, |
| const Evas_Smart_Interface * | iface | ||
| ) |
Retrieve an Evas smart object interface's private data.
| obj | An Evas smart object. |
| iface | The given object's interface handle. |
NULL otherwise. References evas_object_smart_smart_get().
| EVAS_API Eina_Bool evas_object_smart_type_check | ( | const Evas_Object * | obj, |
| const char * | type | ||
| ) |
Checks whether a given smart object or any of its smart object parents is of a given smart class.
If obj is not a smart object, this call will fail immediately.
The checks use smart classes names and string comparison. There is a version of this same check using pointer comparison, since a smart class' name is a single string in Evas.
See also evas_object_smart_type_check_ptr.
| [in] | type | The name (type) of the smart class to check for. |
References EINA_FALSE, eina_hash_find(), EINA_TRUE, _Evas_Smart_Class::name, and _Evas_Smart_Class::parent.
| EVAS_API Eina_Bool evas_object_smart_type_check_ptr | ( | const Evas_Object * | obj, |
| const char * | type | ||
| ) |
Checks whether a given smart object or any of its smart object parents is of a given smart class, using pointer comparison.
| [in] | type | The type (name string) to check for. Must be the name. |
true if obj or any of its parents is of type type, false otherwise. References EINA_FALSE, eina_hash_find(), EINA_TRUE, _Evas_Smart_Class::name, and _Evas_Smart_Class::parent.
Referenced by elm_win_win32_window_get(), elm_win_window_id_get(), and elm_win_wl_window_get().
| EVAS_API Eina_Bool evas_object_smart_callbacks_descriptions_set | ( | Evas_Object * | obj, |
| const Evas_Smart_Cb_Description * | descriptions | ||
| ) |
Set an smart object instance's smart callbacks descriptions.
These descriptions are hints to be used by introspection and are not enforced in any way.
It will not be checked if instance callbacks descriptions have the same name as respective possibly registered in the smart object class. Both are kept in different arrays and users of evas_object_smart_callbacks_descriptions_get() should handle this case as they wish.
descriptions must be null terminated, and because a null name makes little sense, too, Evas_Smart_Cb_Description.name must not be null.| [in] | descriptions | null terminated array with Evas_Smart_Cb_Description descriptions. Array elements won't be modified at run time, but references to them and their contents will be made, so this array should be kept alive during the whole object's lifetime. |
true on success, false on failure. References EINA_FALSE, EINA_TRUE, and _Evas_Smart_Cb_Description::name.
| EVAS_API void evas_object_smart_callbacks_descriptions_get | ( | const Evas_Object * | obj, |
| const Evas_Smart_Cb_Description *** | class_descriptions, | ||
| unsigned int * | class_count, | ||
| const Evas_Smart_Cb_Description *** | instance_descriptions, | ||
| unsigned int * | instance_count | ||
| ) |
Retrieve an smart object's know smart callback descriptions (both instance and class ones).
This call searches for registered callback descriptions for both instance and class of the given smart object. These arrays will be sorted by Evas_Smart_Cb_Description.name and also null terminated, so both class_count and instance_count can be ignored, if the caller wishes so. The terminator null is not counted in these values.
null pointers on the descriptions/counters you're not interested in: they'll be ignored by the function.evas_smart_callbacks_descriptions_get().
| [out] | class_descriptions | Where to store class callbacks descriptions array, if any is known. If no descriptions are known, null is returned. |
| [out] | class_count | Returns how many class callbacks descriptions are known. |
| [out] | instance_descriptions | Where to store instance callbacks descriptions array, if any is known. If no descriptions are known, null is returned. |
| [out] | instance_count | Returns how many instance callbacks descriptions are known. |
| EVAS_API void evas_object_smart_callback_description_find | ( | const Evas_Object * | obj, |
| const char * | name, | ||
| const Evas_Smart_Cb_Description ** | class_description, | ||
| const Evas_Smart_Cb_Description ** | instance_description | ||
| ) |
Find callback description for callback called name or null if not found.
If parameter is null, no search will be done on instance descriptions.
| [in] | name | name of desired callback, must not be null. The search have a special case for name being the same pointer as registered with Evas_Smart_Cb_Description, one can use it to avoid excessive use of strcmp(). |
| [out] | class_description | pointer to return class description or null if not found. If parameter is null, no search will be done on class descriptions. |
| [out] | instance_description | pointer to return instance description. |
| EVAS_API Evas_Smart * evas_object_smart_smart_get | ( | const Evas_Object * | obj | ) |
Get the Evas_Smart from which obj smart object was created.
null, on errors. Referenced by evas_object_smart_interface_data_get(), and evas_object_smart_interface_get().
| EVAS_API void evas_object_smart_data_set | ( | Evas_Object * | obj, |
| void * | data | ||
| ) |
Store a pointer to user data for a given smart object.
This data is stored independently of the one set by evas_object_data_set(), naturally.
See also evas_object_smart_data_get.
| [in] | obj | The object |
| [in] | data | A pointer to user data. |
References EINA_TRUE.
| EVAS_API void * evas_object_smart_data_get | ( | const Evas_Object * | obj | ) |
Retrieves the pointer to user data for a given smart object.
This data is stored independently of the one set by evas_object_data_set(), naturally.
See also evas_object_smart_data_set.
| [in] | obj | The object |
| EVAS_API Evas_Object * evas_object_smart_clipped_clipper_get | ( | const Evas_Object * | obj | ) |
Get the clipper object for the given clipped smart object.
Use this function if you want to change any of this clipper's properties, like colors.
| EVAS_API Eina_List * evas_object_smart_members_get | ( | const Evas_Object * | obj | ) |
Retrieves the list of the member objects of a given Evas smart object.
The returned list should be freed with eina_list_free() when you no longer need it.
This function will return null when a non-smart object is passed.
See also evas_object_smart_member_add, evas_object_smart_member_del and evas_object_smart_iterator_new.
obj.References eina_list_append(), and _Eina_Inlist::next.
| EVAS_API void evas_object_smart_need_recalculate_set | ( | Evas_Object * | obj, |
| Eina_Bool | value | ||
| ) |
Set or unset the flag signalling that a given smart object needs to get recalculated.
If this flag is set, then the calculate() smart function of obj will be called, if one is provided, during rendering phase of Evas (see evas_render()), after which this flag will be automatically unset.
If that smart function is not provided for the given object, this flag will be left unchanged.
true as parameter.See also evas_object_smart_need_recalculate_get, evas_object_smart_calculate and evas_smart_objects_calculate().
| [in] | value | whether one wants to set ($true) or to unset ($false) the flag. |
Set or unset the flag signalling that a given smart object needs to get recalculated.
If this flag is set, then the evas_object_smart_calculate function will be called, during rendering phase of the canvas. After that, this flag will be automatically unset.
true.See also evas_object_smart_calculate.
| [in] | obj | The object. |
| [in] | value | true if the group layout needs to be recalculated, false otherwise |
| EVAS_API Eina_Bool evas_object_smart_need_recalculate_get | ( | const Evas_Object * | obj | ) |
Get the value of the flag signalling that a given smart object needs to get recalculated.
calculate() smart function is called, if one is provided. If it's not provided, then the flag will be left unchanged after the rendering phase.See also evas_object_smart_need_recalculate_set, for more details.
Get the value of the flag signalling that a given smart object needs to get recalculated.
If this flag is set, then the evas_object_smart_calculate function will be called, during rendering phase of the canvas. After that, this flag will be automatically unset.
true.See also evas_object_smart_calculate.
| [in] | obj | The object. |
true if the group layout needs to be recalculated, false otherwise | EVAS_API Eina_Iterator * evas_object_smart_iterator_new | ( | const Evas_Object * | obj | ) |
Retrieves an iterator of the member objects of a given Evas smart object.
See also evas_object_smart_member_add and evas_object_smart_member_del
obj.Retrieves an iterator of the member objects of a given Evas smart object.
This returns the list of "smart" children. This might be different from both the Efl_Object children list as well as the Efl_Container content list.
| [in] | obj | The object. |
| EVAS_API void evas_object_smart_calculate | ( | Evas_Object * | obj | ) |
Call the calculate() smart function immediately on a given smart object.
This will force immediate calculations (see Evas_Smart_Class) needed for renderization of this object and, besides, unset the flag on it telling it needs recalculation for the next rendering phase.
See also evas_object_smart_need_recalculate_set
Call the calculate() smart function immediately on a given smart object.
This will also reset the flag evas_object_smart_need_recalculate_get.
| [in] | obj | The object. |
| EVAS_API void evas_object_smart_changed | ( | Evas_Object * | obj | ) |
Mark smart object as changed, dirty.
This will flag the given object as needing recalculation, forcefully. As an effect, on the next rendering cycle its calculate() (see Evas_Smart_Class) smart function will be called.
See also evas_object_smart_need_recalculate_set and evas_object_smart_calculate.
Mark smart object as changed, dirty.
This also forcefully marks the given object as needing recalculation. As an effect, on the next rendering cycle its evas_object_smart_calculate method will be called.
| [in] | obj | The object. |
Referenced by elm_slider_indicator_show_set().
| EVAS_API void evas_object_smart_move_children_relative | ( | Evas_Object * | obj, |
| Evas_Coord | dx, | ||
| Evas_Coord | dy | ||
| ) |
Moves all children objects of a given smart object relative to a given offset.
This will make each of obj object's children to move, from where they before, with those delta values (offsets) on both directions.
move functions.move smart function definition.| [in] | dx | Horizontal offset (delta). |
| [in] | dy | Vertical offset (delta). |