If the parameter (@p focus) is
* set, the passed object will be set as the currently focused object.
* It will receive all keyboard events that are not exclusive key
* grabs on other objects.
*
* @see evas_object_focus_get
* @see evas_focus_get
* @see evas_object_key_grab
* @see evas_object_key_ungrab
*/
EAPI void evas_object_focus_set (Evas_Object *obj, Eina_Bool focus) EINA_ARG_NONNULL(1);
/**
* Test if the object has focus.
*
* @param obj The object to be tested.
*
* If the passed object is the currently focused object 1 is returned,
* 0 otherwise.
*
* @see evas_object_focus_set
* @see evas_focus_get
* @see evas_object_key_grab
* @see evas_object_key_ungrab
*
* @return 1 if the object has the focus, 0 otherwise.
*/
EAPI Eina_Bool evas_object_focus_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the layer of the evas that the given object will be part of.
*
* It is not possible to change the layer of a smart object's child.
*
* @param obj The given evas object.
* @param l The number of the layer to place the object on.
* Between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
*/
EAPI void evas_object_layer_set (Evas_Object *obj, short l) EINA_ARG_NONNULL(1);
/**
* Retrieves the layer of the evas that the given object is part of.
*
* Be careful, it doesn't make sense to change the layer of smart object's
* child. So the returned value could be wrong in some case. Don't rely on
* it's accuracy.
*
* @param obj The given evas object.
* @return Number of the layer.
*/
EAPI short evas_object_layer_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the name of the given evas object to the given name.
* @param obj The given object.
* @param name The given name.
*/
EAPI void evas_object_name_set (Evas_Object *obj, const char *name) EINA_ARG_NONNULL(1);
/**
* Retrieves the name of the given evas object.
* @param obj The given object.
* @return The name of the object. @c NULL if no name has been given
* to the object.
*/
EAPI const char *evas_object_name_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Increments object reference count to defer deletion
*
* This increments the reference count of an object, which if greater than
* 0 will defer deletion by evas_object_del() until all references are
* released back to 0. References cannot go below 0 and unreferencing more
* times that referencing will result in the reference count being limited
* to 0. References are limited to 2^32 - 1 for an object. Referencing it more
* than this will result in it being limited to this value.
*
* @param obj The given evas object to reference
* @ingroup Evas_Object_Group_Basic
* @since 1.1.0
*/
EAPI void evas_object_ref (Evas_Object *obj);
/**
* Decrements object reference count to defer deletion
*
* This decrements the reference count of an object. If the object has had
* evas_object_del() called on it while references were more than 0, it will
* be deleted at the time this function is called as it normally would have
* been. See evas_object_ref() for more information.
*
* @param obj The given evas object to unreference
* @ingroup Evas_Object_Group_Basic
* @since 1.1.0
*/
EAPI void evas_object_unref (Evas_Object *obj);
/**
* Deletes the given evas object and frees its memory.
*
* The object's 'free' callback is called when this function is called.
* If the object currently has the focus, its 'focus out' callback is
* also called.
*
* @param obj The given evas object.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_del (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Moves the given evas object to the given location.
* @param obj The given evas object.
* @param x X position to move the object to, in canvas units.
* @param y Y position to move the object to, in canvas units.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_move (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
/**
* Changes the size of the given evas object.
* @param obj The given evas object.
* @param w The new width of the evas object.
* @param h The new height of the evas object.
*
* @note Be aware that resizing an object changes its drawing area,
* but that does imply the object is rescaled! For instance,
* images are filled inside their drawing area using the
* specifications of evas_object_image_fill_set(), thus to scale
* the image to match exactly your drawing area, you need to
* change the evas_object_image_fill_set() as well. Consider the
* following example:
* @code
* // rescale image to fill exactly its area without tiling:
* evas_object_resize(img, w, h);
* evas_object_image_fill_set(img, 0, 0, w, h);
* @endcode
* This is more evident in images, but text, textblock, lines
* and polygons will behave similarly. Check their specific APIs
* to know how to achieve your desired behavior.
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_resize (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the position and rectangular size of the given evas object.
*
* Note that if any of @p x, @p y, @p w or @p h are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param x Pointer to an integer in which to store the X coordinate of
* the object.
* @param y Pointer to an integer in which to store the Y coordinate of
* the object.
* @param w Pointer to an integer in which to store the width of the
* object.
* @param h Pointer to an integer in which to store the height of the
* object.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_geometry_get (const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Makes the given evas object visible.
* @param obj The given evas object.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_show (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Makes the given evas object invisible.
* @param obj The given evas object.
*
* @note the hidden objects will not be checked for changes and will
* not catch events. That is, they are much ligher than an
* object that is invisible due indirect effects, such as
* clipped or out-of-viewport.
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_hide (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Retrieves whether or not the given evas object is visible.
* @param obj The given evas object.
* @return @c 1 if the object is visible. @c 0 otherwise.
* @ingroup Evas_Object_Group_Basic
*/
EAPI Eina_Bool evas_object_visible_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the general colour of the given evas object to the given colour.
* @param obj The given evas object.
* @param r The red component of the given colour.
* @param g The green component of the given colour.
* @param b The blue component of the given colour.
* @param a The alpha component of the given colour.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
/**
* Retrieves the general colour of the given evas object.
*
* Note that if any of @p r, @p g, @p b or @p a are @c NULL, then the
* @c NULL parameters are ignored.
*
* @param obj The given evas object.
* @param r Pointer to an integer in which to store the red component of
* the colour.
* @param g Pointer to an integer in which to store the green component of
* the colour.
* @param b Pointer to an integer in which to store the blue component of
* the colour.
* @param a Pointer to an integer in which to store the alpha component of
* the colour.
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
/**
* Retrieves the evas that the given evas object is on.
* @param obj The given evas object.
* @return The evas that the object is on.
* @ingroup Evas_Object_Group_Basic
*/
EAPI Evas *evas_object_evas_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the object type of the given evas object.
* @param obj The given object.
* @return The type of the object.
*/
EAPI const char *evas_object_type_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Raise @p obj to the top of its layer.
*
* @param obj the object to raise
*/
EAPI void evas_object_raise (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Lower @p obj to the bottom of its layer.
*
* @param obj the object to lower
*/
EAPI void evas_object_lower (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Stack @p obj immediately above @p above
*
* If @p obj is a member of a smart object, then @p above must also be
* a member of the same smart object.
*
* Similarly, if @p obj is not a member of smart object, @p above may
* not either.
*
* @param obj the object to stack
* @param above the object above which to stack
*/
EAPI void evas_object_stack_above (Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(1, 2);
/**
* Stack @p obj immediately below @p below
*
* If @p obj is a member of a smart object, then @p below must also be
* a member of the same smart object.
*
* Similarly, if @p obj is not a member of smart object, @p below may
* not either.
*
* @param obj the object to stack
* @param below the object below which to stack
*/
EAPI void evas_object_stack_below (Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(1, 2);
/**
* Get the evas object above @p obj
*
* @param obj an Evas_Object
* @return the Evas_Object directly above
*/
EAPI Evas_Object *evas_object_above_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Get the evas object below @p obj
*
* @param obj an Evas_Object
* @return the Evas_Object directly below
*/
EAPI Evas_Object *evas_object_below_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @defgroup Evas_Object_Group_Events Object Events
*
* Objects generates events when they are moved, resized, when their
* visibility change, when they are deleted and so on. These methods
* will allow one to handle such events.
*
* The events can be those from keyboard and mouse, if the object
* accepts these events.
*
* @ingroup Evas_Object_Group
*/
/**
* @addtogroup Evas_Object_Group_Events
* @{
*/
/**
* Add a callback function to an object
*
* @param obj Object to attach a callback to
* @param type The type of event that will trigger the callback
* @param func The function to be called when the event is triggered
* @param data The data pointer to be passed to @p func
*
* This function adds a function callback to an object when the event
* of type @p type occurs on object @p obj. The function is @p 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.
*
* The function will be passed the pointer @p data when it is
* called. A callback function must look like this:
*
* @code
* void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
* @endcode
*
* The first parameter @p data in this function will be the same value
* passed to evas_object_event_callback_add() as the @p data
* parameter. The second parameter is a convenience for the programmer
* to know what evas canvas the event occurred on. The third parameter
* @p obj is the Object handle on which the event occurred. The foruth
* parameter @p event_info is a pointer to a data structure that may
* or may not be passed to the callback, depending on the event type
* that triggered the callback.
*
* The event type @p type to trigger the function may be one of
* #EVAS_CALLBACK_MOUSE_IN, #EVAS_CALLBACK_MOUSE_OUT,
* #EVAS_CALLBACK_MOUSE_DOWN, #EVAS_CALLBACK_MOUSE_UP,
* #EVAS_CALLBACK_MOUSE_MOVE, #EVAS_CALLBACK_MOUSE_WHEEL,
* #EVAS_CALLBACK_FREE, #EVAS_CALLBACK_KEY_DOWN, #EVAS_CALLBACK_KEY_UP,
* #EVAS_CALLBACK_FOCUS_IN, #EVAS_CALLBACK_FOCUS_OUT,
* #EVAS_CALLBACK_SHOW, #EVAS_CALLBACK_HIDE, #EVAS_CALLBACK_MOVE,
* #EVAS_CALLBACK_RESIZE or #EVAS_CALLBACK_RESTACK.
* This determines the kind of event that will trigger the callback to
* be called. The @p event_info pointer passed to the callback will
* be one of the following, depending on the event triggering it:
*
* #EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In
*
* This event is triggered when the mouse pointer enters the region of
* the object @p obj. This may occur by the mouse pointer being moved
* by evas_event_feed_mouse_move() or
* evas_event_feed_mouse_move_data() calls, or by the object being
* shown, raised, moved, resized, or other objects being moved out of
* the way, hidden, lowered or moved out of the way.
*
* #EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out
*
* This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is, but
* occurs when the mouse pointer exits an object. Note that no out
* events will be reported if the mouse pointer is implicitly grabbed
* to an object (the mouse buttons are down at all and any were
* pressed on that object). An out event will be reported as soon as
* the mouse is no longer grabbed (no mouse buttons are
* depressed). Out events will be reported once all buttons are
* released, if the mouse has left the object.
*
* #EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to
* Evas_Event_Mouse_Down
*
* This event is triggered by a mouse button being depressed while
* over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB
* (default) this causes this object to passively grab the mouse until
* all mouse buttons have been released. That means if this mouse
* button is the first to be pressed, all future mouse events will be
* reported to only this object until no buttons are down. That
* includes mouse move events, in and out events, and further button
* presses. When all buttons are released, event propagation occurs as
* normal.
*
* #EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up
*
* This event is triggered by a mouse button being released while over
* an object or when passively grabbed to an object. If this is the
* last mouse button to be raised on an object then the passive grab
* is released and event processing will continue as normal.
*
* #EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move
*
* This event is triggered by the mouse pointer moving while over an
* object or passively grabbed to an object.
*
* #EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to
* Evas_Event_Mouse_Wheel
*
* This event is triggered by the mouse wheel being rolled while over
* an object or passively grabbed to an object.
*
* #EVAS_CALLBACK_FREE: event_info = NULL
*
* This event is triggered just before Evas is about to free all
* memory used by an object and remove all references to it. This is
* useful for programs to use if they attached data to an object and
* want to free it when the object is deleted. The object is still
* valid when this callback is called, but after this callback
* returns, there is no guarantee on the object's validity.
*
* #EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down
*
* This callback is called when a key is pressed and the focus is on
* the object, or a key has been grabbed to a particular object which
* wants to intercept the key press regardless of what object has the
* focus.
*
* #EVAS_CALLBACK_KEY_UP: event_info = pointer to Evas_Event_Key_Up
*
* This callback is called when a key is released and the focus is on
* the object, or a key has been grabbed to a particular object which
* wants to intercept the key release regardless of what object has
* the focus.
*
* #EVAS_CALLBACK_FOCUS_IN: event_info = NULL
*
* This event is called when an object gains the focus. When the
* callback is called the object has already gained the focus.
*
* #EVAS_CALLBACK_FOCUS_OUT: event_info = NULL
*
* This event is triggered by an object losing the focus. When the
* callback is called the object has already lost the focus.
*
* #EVAS_CALLBACK_SHOW: event_info = NULL
*
* This event is triggered by the object being shown by
* evas_object_show().
*
* #EVAS_CALLBACK_HIDE: event_info = NULL
*
* This event is triggered by an object being hidden by
* evas_object_hide().
*
* #EVAS_CALLBACK_MOVE: event_info = NULL
*
* This event is triggered by an object being
* moved. evas_object_move() can trigger this, as can any
* object-specific manipulations that would mean the object's origin
* could move.
*
* #EVAS_CALLBACK_RESIZE: event_info = NULL
*
* This event is triggered by an object being resized. Resizes can be
* triggered by evas_object_resize() or by any object-specific calls
* that may cause the object to resize.
*
* Example:
* @code
* extern Evas_Object *object;
* extern void *my_data;
* void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
* void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
*
* evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data);
* if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
* {
* fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
* exit(-1);
* }
* evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data);
* if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
* {
* fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
* exit(-1);
* }
* @endcode
*/
EAPI void evas_object_event_callback_add (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
/**
* Delete a callback function from an object
*
* @param obj Object to remove a callback from
* @param type The type of event that was triggering the callback
* @param func The function that was to be called when the event was triggered
* @return The data pointer that was to be passed to the callback
*
* This function removes the most recently added callback from the
* object @p obj which was triggered by the event type @p type and was
* calling the function @p func when triggered. If the removal is
* successful it will also return the data pointer that was passed to
* evas_object_event_callback_add() when the callback was added to the
* object. If not successful NULL will be returned.
*
* Example:
* @code
* extern Evas_Object *object;
* void *my_data;
* void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
*
* my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
* @endcode
*/
EAPI void *evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) EINA_ARG_NONNULL(1, 3);
/**
* Delete a callback function from an object
*
* @param obj Object to remove a callback from
* @param type The type of event that was triggering the callback
* @param func The function that was to be called when the event was triggered
* @param data The data pointer that was to be passed to the callback
* @return The data pointer that was to be passed to the callback
*
* This function removes the most recently added callback from the
* object @p obj which was triggered by the event type @p type and was
* calling the function @p func with data @p data when triggered. If
* the removal is successful it will also return the data pointer that
* was passed to evas_object_event_callback_add() (that will be the
* same as the parameter) when the callback was added to the
* object. If not successful NULL will be returned.
*
* Example:
* @code
* extern Evas_Object *object;
* void *my_data;
* void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);
*
* my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
* @endcode
*/
EAPI void *evas_object_event_callback_del_full(Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
/**
* Set an object's pass events state.
* @param obj the evas object
* @param pass whether to pass events or not
*
* If @p pass is true, this will cause events on @p obj to be ignored.
* They will be triggered on the next lower object (that is not set to
* pass events) instead.
*
* If @p pass is false, events will be processed as normal.
*/
EAPI void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) EINA_ARG_NONNULL(1);
/**
* Determine whether an object is set to pass events.
* @param obj
* @return pass events state
*/
EAPI Eina_Bool evas_object_pass_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set an object's repeat events state.
* @param obj the object
* @param repeat wheter to repeat events or not
*
* If @p repeat is true, this will cause events on @p obj to trigger
* callbacks, but also to be repeated on the next lower object in the
* stack.
*
* If @p repeat is false, events occurring on @p obj will be processed
* normally.
*/
EAPI void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) EINA_ARG_NONNULL(1);
/**
* Determine whether an object is set to repeat events.
* @param obj
* @return repeat events state
*/
EAPI Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set whether events on a smart member object should propagate to its
* parent.
*
* @param obj the smart member object
* @param prop wheter to propagate events or not
*
* This function has no effect if @p obj is not a member of a smart
* object.
*
* If @p prop is true, events occurring on this object will propagate on
* to the smart object of which @p obj is a member.
*
* If @p prop is false, events for which callbacks are set on the member
* object, @p obj, will not be passed on to the parent smart object.
*
* The default value is true.
*/
EAPI void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) EINA_ARG_NONNULL(1);
/**
* Determine whether an object is set to propagate events.
* @param obj
* @return propagate events state
*/
EAPI Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @}
*/
/**
* @defgroup Evas_Object_Group_Map UV Mapping (Rotation, Perspecitve, 3D...)
*
* Evas allows different transformations to be applied to all kinds of
* objects. These are applied by means of UV mapping.
*
* With UV mapping, one maps points in the source object to a 3D space
* positioning at target. This allows rotation, perspective, scale and
* lots of other effects, depending on the map that is used.
*
* Each map point may carry a multiplier color. If properly
* calculated, these can do shading effects on the object, producing
* 3D effects.
*
* As usual, Evas provides both the raw and easy to use methods. The
* raw methods allow developer to create its maps somewhere else,
* maybe load them from some file format. The easy to use methods,
* calculate the points given some high-level parameters, such as
* rotation angle, ambient light and so on.
*
* @note applying mapping will reduce performance, so use with
* care. The impact on performance depends on engine in
* use. Software is quite optimized, but not as fast as OpenGL.
*
* @ingroup Evas_Object_Group
*/
/**
* Enable or disable the map that is set.
*
* This enables the map that is set or disables it. On enable, the object
* geometry will be saved, and the new geometry will change (position and
* size) to reflect the map geometry set. If none is set yet, this may be
* an undefined geometry, unless you have already set the map with
* evas_object_map_set(). It is suggested you first set a map with
* evas_object_map_set() with valid useful coordinates then enable and
* disable the map with evas_object_map_enable_set() as needed.
*
* @param obj object to enable the map on
* @param enabled enabled state
*/
EAPI void evas_object_map_enable_set (Evas_Object *obj, Eina_Bool enabled);
/**
* Get the map enabled state
*
* This returns the currently enabled state of the map on the object indicated.
* The default map enable state is off. You can enable and disable it with
* evas_object_map_enable_set().
*
* @param obj object to get the map enabled state from
* @return the map enabled state
*/
EAPI Eina_Bool evas_object_map_enable_get (const Evas_Object *obj);
/**
* Set the map source object
*
* This sets the object from which the map is taken - can be any object that
* has map enabled on it.
*
* Currently not implemented. for future use.
*
* @param obj object to set the map source of
* @param src the source object from which the map is taken
*/
EAPI void evas_object_map_source_set (Evas_Object *obj, Evas_Object *src);
/**
* Get the map source object
*
* See evas_object_map_source_set()
*
* @param obj object to set the map source of
* @return the object set as the source
*/
EAPI Evas_Object *evas_object_map_source_get (const Evas_Object *obj);
/**
* Set current object transformation map.
*
* This sets the map on a given object. It is copied from the @p map pointer,
* so there is no need to keep the @p map object if you don't need it anymore.
*
* A map is a set of 4 points which have canvas x, y coordinates per point,
* with an optional z point value as a hint for perspective correction, if it
* is available. As well each point has u and v coordinates. These are like
* "texture coordinates" in OpenGL in that they define a point in the source
* image that is mapped to that map vertex/point. The u corresponds to the x
* coordinate of this mapped point and v, the y coordinate. Note that these
* coordinates describe a bounding region to sample. If you have a 200x100
* source image and want to display it at 200x100 with proper pixel
* precision, then do:
*
* @code
* Evas_Map *m = evas_map_new(4);
* evas_map_point_coord_set(m, 0, 0, 0, 0);
* evas_map_point_coord_set(m, 1, 200, 0, 0);
* evas_map_point_coord_set(m, 2, 200, 100, 0);
* evas_map_point_coord_set(m, 3, 0, 100, 0);
* evas_map_point_image_uv_set(m, 0, 0, 0);
* evas_map_point_image_uv_set(m, 1, 200, 0);
* evas_map_point_image_uv_set(m, 2, 200, 100);
* evas_map_point_image_uv_set(m, 3, 0, 100);
* evas_object_map_set(obj, m);
* evas_map_free(m);
* @endcode
*
* Note that the map points a uv coordinates match the image geometry. If
* the @p map parameter is NULL, the stored map will be freed and geometry
* prior to enabling/setting a map will be restored.
*
* @param obj object to change transformation map
* @param map new map to use
*
* @see evas_map_new()
*/
EAPI void evas_object_map_set (Evas_Object *obj, const Evas_Map *map);
/**
* Get current object transformation map.
*
* This returns the current internal map set on the indicated object. It is
* intended for read-only acces and is only valid as long as the object is
* not deleted or the map on the object is not changed. If you wish to modify
* the map and set it back do the following:
*
* @code
* const Evas_Map *m = evas_object_map_get(obj);
* Evas_Map *m2 = evas_map_dup(m);
* evas_map_util_rotate(m2, 30.0, 0, 0);
* evas_object_map_set(obj);
* evas_map_free(m2);
* @endcode
*
* @param obj object to query transformation map.
* @return map reference to map in use. This is an internal data structure, so
* do not modify it.
*
* @see evas_object_map_set()
*/
EAPI const Evas_Map *evas_object_map_get (const Evas_Object *obj);
/**
* Populate source and destination map points to match exactly object.
*
* Usually one initialize map of an object to match it's original
* position and size, then transform these with evas_map_util_*
* functions, such as evas_map_util_rotate() or
* evas_map_util_3d_rotate(). The original set is done by this
* function, avoiding code duplication all around.
*
* @param m map to change all 4 points (must be of size 4).
* @param obj object to use unmapped geometry to populate map coordinates.
* @param z Point Z Coordinate hint (pre-perspective transform). This value
* will be used for all four points.
*
* @see evas_map_util_points_populate_from_object()
* @see evas_map_point_coord_set()
* @see evas_map_point_image_uv_set()
*/
EAPI void evas_map_util_points_populate_from_object_full(Evas_Map *m, const Evas_Object *obj, Evas_Coord z);
/**
* Populate source and destination map points to match exactly object.
*
* Usually one initialize map of an object to match it's original
* position and size, then transform these with evas_map_util_*
* functions, such as evas_map_util_rotate() or
* evas_map_util_3d_rotate(). The original set is done by this
* function, avoiding code duplication all around.
*
* Z Point coordinate is assumed as 0 (zero).
*
* @param m map to change all 4 points (must be of size 4).
* @param obj object to use unmapped geometry to populate map coordinates.
*
* @see evas_map_util_points_populate_from_object_full()
* @see evas_map_util_points_populate_from_geometry()
* @see evas_map_point_coord_set()
* @see evas_map_point_image_uv_set()
*/
EAPI void evas_map_util_points_populate_from_object (Evas_Map *m, const Evas_Object *obj);
/**
* Populate source and destination map points to match given geometry.
*
* Similar to evas_map_util_points_populate_from_object_full(), this
* call takes raw values instead of querying object's unmapped
* geometry. The given width will be used to calculate destination
* points (evas_map_point_coord_set()) and set the image uv
* (evas_map_point_image_uv_set()).
*
* @param m map to change all 4 points (must be of size 4).
* @param x Point X Coordinate
* @param y Point Y Coordinate
* @param w width to use to calculate second and third points.
* @param h height to use to calculate third and fourth points.
* @param z Point Z Coordinate hint (pre-perspective transform). This value
* will be used for all four points.
*
* @see evas_map_util_points_populate_from_object()
* @see evas_map_point_coord_set()
* @see evas_map_point_image_uv_set()
*/
EAPI void evas_map_util_points_populate_from_geometry (Evas_Map *m, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Evas_Coord z);
/**
* Set color of all points to given color.
*
* This call is useful to reuse maps after they had 3d lightning or
* any other colorization applied before.
*
* @param m map to change the color of.
* @param r red (0 - 255)
* @param g green (0 - 255)
* @param b blue (0 - 255)
* @param a alpha (0 - 255)
*
* @see evas_map_point_color_set()
*/
EAPI void evas_map_util_points_color_set (Evas_Map *m, int r, int g, int b, int a);
/**
* Change the map to apply the given rotation.
*
* This rotates the indicated map's coordinates around the center coordinate
* given by @p cx and @p cy as the rotation center. The points will have their
* X and Y coordinates rotated clockwise by @p degrees degress (360.0 is a
* full rotation). Negative values for degrees will rotate counter-clockwise
* by that amount. All coordinates are canvas global coordinates.
*
* @param m map to change.
* @param degrees amount of degrees from 0.0 to 360.0 to rotate.
* @param cx rotation's center horizontal position.
* @param cy rotation's center vertical position.
*
* @see evas_map_point_coord_set()
* @see evas_map_util_zoom()
*/
EAPI void evas_map_util_rotate (Evas_Map *m, double degrees, Evas_Coord cx, Evas_Coord cy);
/**
* Change the map to apply the given zooming.
*
* Like evas_map_util_rotate(), this zooms the points of the map from a center
* point. That center is defined by @p cx and @p cy. The @p zoomx and @p zoomy
* parameters specific how much to zoom in the X and Y direction respectively.
* A value of 1.0 means "don't zoom". 2.0 means "dobule the size". 0.5 is
* "half the size" etc. All coordinates are canvas global coordinates.
*
* @param m map to change.
* @param zoomx horizontal zoom to use.
* @param zoomy vertical zoom to use.
* @param cx zooming center horizontal position.
* @param cy zooming center vertical position.
*
* @see evas_map_point_coord_set()
* @see evas_map_util_rotate()
*/
EAPI void evas_map_util_zoom (Evas_Map *m, double zoomx, double zoomy, Evas_Coord cx, Evas_Coord cy);
/**
* Rotate the map around 3 axes in 3D
*
* This will rotate not just around the "Z" axis as in evas_map_util_rotate()
* (which is a convenience call for those only wanting 2D). This will rotate
* around the X, Y and Z axes. The Z axis points "into" the screen with low
* values at the screen and higher values further away. The X axis runs from
* left to right on the screen and the Y axis from top to bottom. Like with
* evas_map_util_rotate(0 you provide a center point to rotate around (in 3D).
*
* @param m map to change.
* @param dx amount of degrees from 0.0 to 360.0 to rotate arount X axis.
* @param dy amount of degrees from 0.0 to 360.0 to rotate arount Y axis.
* @param dz amount of degrees from 0.0 to 360.0 to rotate arount Z axis.
* @param cx rotation's center horizontal position.
* @param cy rotation's center vertical position.
* @param cz rotation's center vertical position.
*/
EAPI void evas_map_util_3d_rotate (Evas_Map *m, double dx, double dy, double dz, Evas_Coord cx, Evas_Coord cy, Evas_Coord cz);
/**
* Perform lighting calculations on the given Map
*
* This is used to apply lighting calculations (from a single light source)
* to a given map. The R, G and B values of each vertex will be modified to
* reflect the lighting based on the lixth point coordinates, the light
* color and the ambient color, and at what angle the map is facing the
* light source. A surface should have its points be declared in a
* clockwise fashion if the face is "facing" towards you (as opposed to
* away from you) as faces have a "logical" side for lighting.
*
* @param m map to change.
* @param lx X coordinate in space of light point
* @param ly Y coordinate in space of light point
* @param lz Z coordinate in space of light point
* @param lr light red value (0 - 255)
* @param lg light green value (0 - 255)
* @param lb light blue value (0 - 255)
* @param ar ambient color red value (0 - 255)
* @param ag ambient color green value (0 - 255)
* @param ab ambient color blue value (0 - 255)
*/
EAPI void evas_map_util_3d_lighting (Evas_Map *m, Evas_Coord lx, Evas_Coord ly, Evas_Coord lz, int lr, int lg, int lb, int ar, int ag, int ab);
/**
* Apply a perspective transform to the map
*
* This applies a given perspective (3D) to the map coordinates. X, Y and Z
* values are used. The px and py points specify the "infinite distance" point
* in the 3D conversion (where all lines converge to like when artists draw
* 3D by hand). The @p z0 value specifis the z value at which there is a 1:1
* mapping between spatial coorinates and screen coordinates. Any points
* on this z value will not have their X and Y values modified in the transform.
* Those further away (Z value higher) will shrink into the distance, and
* those less than this value will expand and become bigger. The @p foc value
* determines the "focal length" of the camera. This is in reality the distance
* between the camera lens plane itself (at or closer than this rendering
* results are undefined) and the "z0" z value. This allows for some "depth"
* control and @p foc must be greater than 0.
*
* @param m map to change.
* @param px The pespective distance X coordinate
* @param py The pespective distance Y coordinate
* @param z0 The "0" z plane value
* @param foc The focal distance
*/
EAPI void evas_map_util_3d_perspective (Evas_Map *m, Evas_Coord px, Evas_Coord py, Evas_Coord z0, Evas_Coord foc);
/**
* Get the clockwise state of a map
*
* This determines if the output points (X and Y. Z is not used) are
* clockwise or anti-clockwise. This can be used for "back-face culling". This
* is where you hide objects that "face away" from you. In this case objects
* that are not clockwise.
*
* @param m map to query.
* @return 1 if clockwise, 0 otherwise
*/
EAPI Eina_Bool evas_map_util_clockwise_get (Evas_Map *m);
/**
* Create map of transformation points to be later used with an evas object.
*
* This creates a set of points (currently only 4 is supported. no other
* number for @p count will work). That is empty and ready to be modified
* with evas_map calls.
*
* @param count number of points in the map. *
* @return a newly allocated map or NULL on errors.
*
* @see evas_map_free()
* @see evas_map_dup()
* @see evas_map_point_coord_set()
* @see evas_map_point_image_uv_set()
* @see evas_map_util_points_populate_from_object_full()
* @see evas_map_util_points_populate_from_object()
*
* @see evas_object_map_set()
*/
EAPI Evas_Map *evas_map_new (int count);
/**
* Set the smoothing for map rendering
*
* This sets smoothing for map rendering. If the object is a type that has
* its own smoothing settings, then both the smooth settings for this object
* and the map must be turned off. By default smooth maps are enabled.
*
* @param m map to modify. Must not be NULL.
* @param enabled enable or disable smooth map rendering
*/
EAPI void evas_map_smooth_set (Evas_Map *m, Eina_Bool enabled);
/**
* get the smoothing for map rendering
*
* This gets smoothing for map rendering.
*
* @param m map to get the smooth from. Must not be NULL.
*/
EAPI Eina_Bool evas_map_smooth_get (const Evas_Map *m);
/**
* Set the alpha flag for map rendering
*
* This sets alpha flag for map rendering. If the object is a type that has
* its own alpha settings, then this will take precedence. Only image objects
* have this currently. Fits stops alpha blending of the map area, and is
* useful if you know the object and/or all sub-objects is 100% solid.
*
* @param m map to modify. Must not be NULL.
* @param enabled enable or disable alpha map rendering
*/
EAPI void evas_map_alpha_set (Evas_Map *m, Eina_Bool enabled);
/**
* get the alpha flag for map rendering
*
* This gets the alph flag for map rendering.
*
* @param m map to get the alpha from. Must not be NULL.
*/
EAPI Eina_Bool evas_map_alpha_get (const Evas_Map *m);
/**
* Copy a previously allocated map.
*
* This makes a duplicate of the @p m object and returns it.
*
* @param m map to copy. Must not be NULL.
* @return newly allocated map with the same count and contents as @p m.
*/
EAPI Evas_Map *evas_map_dup (const Evas_Map *m);
/**
* Free a previously allocated map.
*
* This frees a givem map @p m and all memory associated with it. You must NOT
* free a map returned by evas_object_map_get() as this is internal.
*
* @param m map to free.
*/
EAPI void evas_map_free (Evas_Map *m);
/**
* Get a maps size.
*
* Returns the number of points in a map. Should be at least 4.
*
* @param m map to get size.
* @return -1 on error, points otherwise.
*/
EAPI int evas_map_count_get (const Evas_Map *m) EINA_CONST;
/**
* Change the map point's coordinate.
*
* This sets the fixen point's coordinate in the map. Note that points
* describe the outline of a quadrangle and are ordered either clockwise
* or anit-clock-wise. It is suggested to keep your quadrangles concave and
* non-complex, though these polygon modes may work, they may not render
* a desired set of output. The quadrangle will use points 0 and 1 , 1 and 2,
* 2 and 3, and 3 and 0 to describe the edges of the quandrangle.
*
* The X and Y and Z coordinates are in canvas units. Z is optional and may
* or may not be honored in drawing. Z is a hint and does not affect the
* X and Y rendered coordinates. It may be used for calculating fills with
* perspective correct rendering.
*
* Remember all coordinates are canvas global ones like with move and reize
* in evas.
*
* @param m map to change point. Must not be @c NULL.
* @param idx index of point to change. Must be smaller than map size.
* @param x Point X Coordinate
* @param y Point Y Coordinate
* @param z Point Z Coordinate hint (pre-perspective transform)
*
* @see evas_map_util_rotate()
* @see evas_map_util_zoom()
* @see evas_map_util_points_populate_from_object_full()
* @see evas_map_util_points_populate_from_object()
*/
EAPI void evas_map_point_coord_set (Evas_Map *m, int idx, Evas_Coord x, Evas_Coord y, Evas_Coord z);
/**
* Get the map point's coordinate.
*
* This returns the coordinates of the given point in the map.
*
* @param m map to query point.
* @param idx index of point to query. Must be smaller than map size.
* @param x where to return the X coordinate.
* @param y where to return the Y coordinate.
* @param z where to return the Z coordinate.
*/
EAPI void evas_map_point_coord_get (const Evas_Map *m, int idx, Evas_Coord *x, Evas_Coord *y, Evas_Coord *z);
/**
* Change the map point's U and V texture source point
*
* This sets the U and V coordinates for the point. This determines which
* coordinate in the source image is mapped to the given point, much like
* OpenGL and textures. Notes that these points do select the pixel, but
* are double floating point values to allow for accuracy and sub-pixel
* selection.
*
* @param m map to change the point of.
* @param idx index of point to change. Must be smaller than map size.
* @param u the X coordinate within the image/texture source
* @param v the Y coordinate within the image/texture source
*
* @see evas_map_point_coord_set()
* @see evas_object_map_set()
* @see evas_map_util_points_populate_from_object_full()
* @see evas_map_util_points_populate_from_object()
*/
EAPI void evas_map_point_image_uv_set (Evas_Map *m, int idx, double u, double v);
/**
* Get the map point's U and V texture source points
*
* This returns the texture points set by evas_map_point_image_uv_set().
*
* @param m map to query point.
* @param idx index of point to query. Must be smaller than map size.
* @param u where to write the X coordinate within the image/texture source
* @param v where to write the Y coordinate within the image/texture source
*/
EAPI void evas_map_point_image_uv_get (const Evas_Map *m, int idx, double *u, double *v);
/**
* Set the color of a vertex in the map
*
* This sets the color of the vertex in the map. Colors will be linearly
* interpolated between vertex points through the map. Color will multiply
* the "texture" pixels (like GL_MODULATE in OpenGL). The default color of
* a vertex in a map is white solid (255, 255, 255, 255) which means it will
* have no affect on modifying the texture pixels.
*
* @param m map to change the color of.
* @param idx index of point to change. Must be smaller than map size.
* @param r red (0 - 255)
* @param g green (0 - 255)
* @param b blue (0 - 255)
* @param a alpha (0 - 255)
*
* @see evas_map_util_points_color_set()
* @see evas_map_point_coord_set()
* @see evas_object_map_set()
*/
EAPI void evas_map_point_color_set (Evas_Map *m, int idx, int r, int g, int b, int a);
/**
* Get the color set on a vertex in the map
*
* This gets the color set by evas_map_point_color_set() on the given vertex
* of the map.
*
* @param m map to get the color of the vertex from.
* @param idx index of point get. Must be smaller than map size.
* @param r pointer to red return
* @param g pointer to green return
* @param b pointer to blue return
* @param a pointer to alpha return (0 - 255)
*
* @see evas_map_point_coord_set()
* @see evas_object_map_set()
*/
EAPI void evas_map_point_color_get (const Evas_Map *m, int idx, int *r, int *g, int *b, int *a);
/**
* @defgroup Evas_Object_Group_Size_Hints Size Hints
*
* Objects may carry hints so another object that acts as a manager
* (see @ref Evas_Smart_Object_Group) may know how to properly position
* and resize the object. The Size Hints provide a common interface
* that is recommended as the protocol for such information.
*
* @ingroup Evas_Object_Group
*/
/**
* Retrieves the size hint for the minimum size.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p w or @p h are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param w Pointer to an integer in which to store the minimum width.
* @param h Pointer to an integer in which to store the minimum height.
*/
EAPI void evas_object_size_hint_min_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Sets the size hint for the minimum size.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Value 0 is considered unset.
*
* @param obj The given evas object.
* @param w Integer to use as the minimum width hint.
* @param h Integer to use as the minimum height hint.
*/
EAPI void evas_object_size_hint_min_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the size hint for the maximum size.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p w or @p h are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param w Pointer to an integer in which to store the maximum width.
* @param h Pointer to an integer in which to store the maximum height.
*/
EAPI void evas_object_size_hint_max_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Sets the size hint for the maximum size.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Value -1 is considered unset.
*
* @param obj The given evas object.
* @param w Integer to use as the maximum width hint.
* @param h Integer to use as the maximum height hint.
*/
EAPI void evas_object_size_hint_max_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the size request hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p w or @p h are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param w Pointer to an integer in which to store the requested width.
* @param h Pointer to an integer in which to store the requested height.
*/
EAPI void evas_object_size_hint_request_get (const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Sets the requested size hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Value 0 is considered unset.
*
* @param obj The given evas object.
* @param w Integer to use as the preferred width hint.
* @param h Integer to use as the preferred height hint.
*/
EAPI void evas_object_size_hint_request_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the size aspect control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p aspect, @p w or @p h are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param aspect Returns the hint on how size should be calculated.
* @param w Pointer to an integer in which to store the aspect width.
* @param h Pointer to an integer in which to store the aspect height.
*/
EAPI void evas_object_size_hint_aspect_get (const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Sets the size aspect control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* @param obj The given evas object.
* @param aspect Hint on how to calculate size.
* @param w Integer to use as aspect width hint.
* @param h Integer to use as aspect height hint.
*/
EAPI void evas_object_size_hint_aspect_set (Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the size align control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p x or @p y are @c NULL, the @c NULL
* parameters are ignored.
*
* @param obj The given evas object.
* @param x Pointer to a double in which to store the align x.
* @param y Pointer to a double in which to store the align y.
*/
EAPI void evas_object_size_hint_align_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
/**
* Sets the size align control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Accepted values are in the 0.0 to 1.0 range, with the special value
* -1.0 used to specify "justify" or "fill" by some users. See
* documentation of possible users.
*
* @param obj The given evas object.
* @param x Double (0.0..1.0 or -1.0) to use as align x hint.
* @param y Double (0.0..1.0 or -1.0) to use as align y hint.
*/
EAPI void evas_object_size_hint_align_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
/**
* Retrieves the size weight control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p x or @p y are @c NULL, the @c NULL
* parameters are ignored.
*
* Accepted values are zero or positive values. Some users might use
* this hint as a boolean, but some might consider it as a proportion,
* see documentation of possible users.
*
* @param obj The given evas object.
* @param x Pointer to a double in which to store the weight x.
* @param y Pointer to a double in which to store the weight y.
*/
EAPI void evas_object_size_hint_weight_get (const Evas_Object *obj, double *x, double *y) EINA_ARG_NONNULL(1);
/**
* Sets the size weight control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* @param obj The given evas object.
* @param x Double (0.0-1.0) to use as weight x hint.
* @param y Double (0.0-1.0) to use as weight y hint.
*/
EAPI void evas_object_size_hint_weight_set (Evas_Object *obj, double x, double y) EINA_ARG_NONNULL(1);
/**
* Retrieves the size padding control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* Note that if any of @p l, @p r, @p t or @p b are @c NULL, the @c
* NULL parameters are ignored.
*
* @param obj The given evas object.
* @param l Pointer to an integer in which to store left padding.
* @param r Pointer to an integer in which to store right padding.
* @param t Pointer to an integer in which to store top padding.
* @param b Pointer to an integer in which to store bottom padding.
*/
EAPI void evas_object_size_hint_padding_get (const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
/**
* Sets the size padding control hint.
*
* This is not a size enforcement in any way, it's just a hint that should
* be used whenever appropriate.
*
* @param obj The given evas object.
* @param l Integer to specify left padding.
* @param r Integer to specify right padding.
* @param t Integer to specify top padding.
* @param b Integer to specify bottom padding.
*/
EAPI void evas_object_size_hint_padding_set (Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b) EINA_ARG_NONNULL(1);
/**
* @defgroup Evas_Object_Group_Extras Extra Object Manipulation
*
* Miscellaneous functions that also apply to any object, but are less
* used or not implemented by all objects.
*
* @ingroup Evas_Object_Group
*/
/**
* @addtogroup Evas_Object_Group_Extras
* @{
*/
/**
* Set an attached data pointer to an object with a given string key.
* @param obj The object to attach the data pointer to
* @param key The string key for the data to access it
* @param data The ponter to the data to be attached
*
* This attaches the pointer @p data to the object @p obj given the string
* @p key. This pointer will stay "hooked" to the object until a new pointer
* with the same string key is attached with evas_object_data_set() or it is
* deleted with evas_object_data_del(). On deletion of the object @p obj, the
* pointers will not be accessible from the object anymore.
*
* You can find the pointer attached under a string key using
* evas_object_data_get(). It is the job of the calling application to free
* any data pointed to by @p data when it is no longer required.
*
* If @p data is NULL, the old value stored at @p key will be removed but no
* new value will be stored. This is synonymous with calling
* evas_object_data_del() with @p obj and @p key.
*
* Example:
*
* @code
* int *my_data;
* extern Evas_Object *obj;
*
* my_data = malloc(500);
* evas_object_data_set(obj, "name_of_data", my_data);
* printf("The data that was attached was %p\n", evas_object_data_get(obj, "name_of_data"));
* @endcode
*/
EAPI void evas_object_data_set (Evas_Object *obj, const char *key, const void *data) EINA_ARG_NONNULL(1, 2);
/**
* Return an attached data pointer by its given string key.
* @param obj The object to which the data was attached
* @param key The string key the data was stored under
* @return The data pointer stored, or NULL if none was stored
*
* This function will return the data pointer attached to the object @p obj
* stored using the string key @p key. If the object is valid and data was
* stored under the given key, the pointer that was stored will be reuturned.
* If this is not the case, NULL will be returned, signifying an invalid object
* or non-existent key. It is possible a NULL pointer was stored given that
* key, but this situation is non-sensical and thus can be considered an error
* as well. NULL pointers are never stored as this is the return value if an
* error occurs.
*
* Example:
*
* @code
* int *my_data;
* extern Evas_Object *obj;
*
* my_data = evas_object_data_get(obj, "name_of_my_data");
* if (my_data) printf("Data stored was %p\n", my_data);
* else printf("No data was stored on the object\n");
* @endcode
*/
EAPI void *evas_object_data_get (const Evas_Object *obj, const char *key) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
/**
* Delete at attached data pointer from an object.
* @param obj The object to delete the data pointer from
* @param key The string key the data was stored under
* @return The original data pointer stored at @p key on @p obj
*
* This will remove the stored data pointer from @p obj stored under @p key,
* and return the original pointer stored under @p key, if any, nor NULL if
* nothing was stored under that key.
*
* Example:
*
* @code
* int *my_data;
* extern Evas_Object *obj;
*
* my_data = evas_object_data_del(obj, "name_of_my_data");
* @endcode
*/
EAPI void *evas_object_data_del (Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
/**
* Set pointer behavior.
*
* @param obj
* @param setting desired behavior.
*
* This function has direct effect on event callbacks related to
* mouse.
*
* If @p setting is EVAS_OBJECT_POINTER_MODE_AUTOGRAB, then when mouse
* is down at this object, events will be restricted to it as source,
* mouse moves, for example, will be emitted even if outside this
* object area.
*
* If @p setting is EVAS_OBJECT_POINTER_MODE_NOGRAB, then events will
* be emitted just when inside this object area.
*
* The default value is EVAS_OBJECT_POINTER_MODE_AUTOGRAB.
*
* @ingroup Evas_Object_Group_Extras
*/
EAPI void evas_object_pointer_mode_set (Evas_Object *obj, Evas_Object_Pointer_Mode setting) EINA_ARG_NONNULL(1);
/**
* Determine how pointer will behave.
* @param obj
* @return pointer behavior.
* @ingroup Evas_Object_Group_Extras
*/
EAPI Evas_Object_Pointer_Mode evas_object_pointer_mode_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets whether or not the given evas object is to be drawn anti-aliased.
*
* @param obj The given evas object.
* @param anti_alias 1 if the object is to be anti_aliased, 0 otherwise.
* @ingroup Evas_Object_Group_Extras
*/
EAPI void evas_object_anti_alias_set (Evas_Object *obj, Eina_Bool antialias) EINA_ARG_NONNULL(1);
/**
* Retrieves whether or not the given evas object is to be drawn anti_aliased.
* @param obj The given evas object.
* @return @c 1 if the object is to be anti_aliased. @c 0 otherwise.
* @ingroup Evas_Object_Group_Extras
*/
EAPI Eina_Bool evas_object_anti_alias_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the scaling factor for an evas object. Does not affect all objects.
*
* @param obj The given evas object.
* @param scale The scaling factor. 1.0 == none.
* @ingroup Evas_Object_Group_Extras
*/
EAPI void evas_object_scale_set (Evas_Object *obj, double scale) EINA_ARG_NONNULL(1);
/**
* Retrieves the scaling factor for the given evas object.
* @param obj The given evas object.
* @return The scaling factor.
*
* @ingroup Evas_Object_Group_Extras
*/
EAPI double evas_object_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the render_op to be used for rendering the evas object.
* @param obj The given evas object.
* @param render_op one of the Evas_Render_Op values.
* @ingroup Evas_Object_Group_Extras
*/
EAPI void evas_object_render_op_set (Evas_Object *obj, Evas_Render_Op op) EINA_ARG_NONNULL(1);
/**
* Retrieves the current value of the operation used for rendering the evas object.
* @param obj The given evas object.
* @return one of the enumerated values in Evas_Render_Op.
* @ingroup Evas_Object_Group_Extras
*/
EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void evas_object_precise_is_inside_set(Evas_Object *obj, Eina_Bool precise) EINA_ARG_NONNULL(1);
EAPI Eina_Bool evas_object_precise_is_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void evas_object_static_clip_set (Evas_Object *obj, Eina_Bool is_static_clip) EINA_ARG_NONNULL(1);
EAPI Eina_Bool evas_object_static_clip_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @}
*/
/**
* @defgroup Evas_Object_Group_Find Finding Objects
*
* Functions that allows finding objects by their position, name or
* other properties.
*
* @ingroup Evas_Object_Group
*/
/**
* Retrieve the object that currently has focus.
*
* @param e The Evas canvas to query for focused object on.
*
* Evas can have (at most) one of its objects focused at a time.
* Focused objects will be the ones having key events delivered
* to, which the programmer can act upon by means of
* evas_object_event_callback_add() usage.
*
* @note Most users wouldn't be dealing directly with Evas' focused
* objects. Instead, they would be using a higher level library for
* that (like a toolkit, as Elementary) to handle focus and who's
* receiving input for them.
*
* This call returns the object that currently has focus on the canvas
* @p e or @c NULL, if none.
*
* @see evas_object_focus_set
* @see evas_object_focus_get
* @see evas_object_key_grab
* @see evas_object_key_ungrab
*
* @return The object that has focus or NULL if there is not one.
*
* @ingroup Evas_Object_Group_Find
*/
EAPI Evas_Object *evas_focus_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the object on the given evas with the given name.
* @param e The given evas.
* @param name The given name.
* @return If successful, the evas object with the given name. Otherwise,
* @c NULL.
* @ingroup Evas_Object_Group_Find
*/
EAPI Evas_Object *evas_object_name_find (const Evas *e, const char *name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the top object at the given position (x,y)
* @param e The given evas object.
* @param x The horizontal coordinate
* @param y The vertical coordinate
* @param include_pass_events_objects Boolean Flag to include or not
* pass events objects
* @param include_hidden_objects Boolean Flag to include or not hidden objects
* @return The evas object that is over all others objects at the given position.
*/
EAPI Evas_Object *evas_object_top_at_xy_get (const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the top object at mouse pointer position
* @param e The given evas object.
* @return The evas object that is over all others objects at the
* pointer position.
*/
EAPI Evas_Object *evas_object_top_at_pointer_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the top object in the given rectangle region
* @param e The given evas object.
* @param x The horizontal coordinate.
* @param y The vertical coordinate.
* @param w The width size.
* @param h The height size.
* @param include_pass_events_objects Boolean Flag to include or not pass events objects
* @param include_hidden_objects Boolean Flag to include or not hidden objects
* @return The evas object that is over all others objects at the pointer position.
*
*/
EAPI Evas_Object *evas_object_top_in_rectangle_get (const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves the objects at the given position
* @param e The given evas object.
* @param x The horizontal coordinate.
* @param y The vertical coordinate.
* @param include_pass_events_objects Boolean Flag to include or not
* pass events objects
* @param include_hidden_objects Boolean Flag to include or not hidden objects
* @return The list of evas objects at the pointer position.
*
*/
EAPI Eina_List *evas_objects_at_xy_get (const Evas *e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Eina_List *evas_objects_in_rectangle_get (const Evas *e, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Get the lowest evas object on the Evas @p e
*
* @param e an Evas
* @return the lowest object
*/
EAPI Evas_Object *evas_object_bottom_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Get the highest evas object on the Evas @p e
*
* @param e an Evas
* @return the highest object
*/
EAPI Evas_Object *evas_object_top_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @defgroup Evas_Object_Group_Interceptors Object Method Interceptors
*
* Evas provides a way to intercept method calls. The interceptor
* callback may opt to completely deny the call, or may check and
* change the parameters before continuing. The continuation of an
* intercepted call is done by calling the intercepted call again,
* from inside the interceptor callback.
*
* @ingroup Evas_Object_Group
*/
typedef void (*Evas_Object_Intercept_Show_Cb) (void *data, Evas_Object *obj);
typedef void (*Evas_Object_Intercept_Hide_Cb) (void *data, Evas_Object *obj);
typedef void (*Evas_Object_Intercept_Move_Cb) (void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y);
typedef void (*Evas_Object_Intercept_Resize_Cb) (void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h);
typedef void (*Evas_Object_Intercept_Raise_Cb) (void *data, Evas_Object *obj);
typedef void (*Evas_Object_Intercept_Lower_Cb) (void *data, Evas_Object *obj);
typedef void (*Evas_Object_Intercept_Stack_Above_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
typedef void (*Evas_Object_Intercept_Stack_Below_Cb) (void *data, Evas_Object *obj, Evas_Object *above);
typedef void (*Evas_Object_Intercept_Layer_Set_Cb) (void *data, Evas_Object *obj, int l);
typedef void (*Evas_Object_Intercept_Color_Set_Cb) (void *data, Evas_Object *obj, int r, int g, int b, int a);
typedef void (*Evas_Object_Intercept_Clip_Set_Cb) (void *data, Evas_Object *obj, Evas_Object *clip);
typedef void (*Evas_Object_Intercept_Clip_Unset_Cb) (void *data, Evas_Object *obj);
/**
* Set the callback function that intercepts a show event of a object.
*
* @param obj The given canvas object pointer.
* @param func The given function to be the callback function.
* @param data The data passed to the callback function.
*
* This function sets a callback function to intercepts a show event
* of a canvas object.
*
* @see evas_object_intercept_show_callback_del().
*
*/
EAPI void evas_object_intercept_show_callback_add (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
/**
* Unset the callback function that intercepts a show event of a
* object.
*
* @param obj The given canvas object pointer.
* @param func The given callback function.
*
* This function sets a callback function to intercepts a show event
* of a canvas object.
*
* @see evas_object_intercept_show_callback_add().
*
*/
EAPI void *evas_object_intercept_show_callback_del (Evas_Object *obj, Evas_Object_Intercept_Show_Cb func) EINA_ARG_NONNULL(1, 2);
/**
* Set the callback function that intercepts a hide event of a object.
*
* @param obj The given canvas object pointer.
* @param func The given function to be the callback function.
* @param data The data passed to the callback function.
*
* This function sets a callback function to intercepts a hide event
* of a canvas object.
*
* @see evas_object_intercept_hide_callback_del().
*
*/
EAPI void evas_object_intercept_hide_callback_add (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
/**
* Unset the callback function that intercepts a hide event of a
* object.
*
* @param obj The given canvas object pointer.
* @param func The given callback function.
*
* This function sets a callback function to intercepts a hide event
* of a canvas object.
*
* @see evas_object_intercept_hide_callback_add().
*
*/
EAPI void *evas_object_intercept_hide_callback_del (Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2);
/**
* Set the callback function that intercepts a move event of a object.
*
* @param obj The given canvas object pointer.
* @param func The given function to be the callback function.
* @param data The data passed to the callback function.
*
* This function sets a callback function to intercepts a move event
* of a canvas object.
*
* @see evas_object_intercept_move_callback_del().
*
*/
EAPI void evas_object_intercept_move_callback_add (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
/**
* Unset the callback function that intercepts a move event of a
* object.
*
* @param obj The given canvas object pointer.
* @param func The given callback function.
*
* This function sets a callback function to intercepts a move event
* of a canvas object.
*
* @see evas_object_intercept_move_callback_add().
*
*/
EAPI void *evas_object_intercept_move_callback_del (Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_resize_callback_add (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_resize_callback_del (Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_raise_callback_add (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_raise_callback_del (Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_lower_callback_add (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_lower_callback_del (Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_stack_above_callback_add (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_stack_above_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_stack_below_callback_add (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_stack_below_callback_del (Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_layer_set_callback_add (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_layer_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_color_set_callback_add (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_color_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_clip_set_callback_add (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_clip_set_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2);
EAPI void evas_object_intercept_clip_unset_callback_add (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2);
EAPI void *evas_object_intercept_clip_unset_callback_del (Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2);
/**
* @defgroup Evas_Object_Specific Specific Object Functions
*
* Functions that work on specific objects.
*
*/
/**
* @defgroup Evas_Object_Rectangle Rectangle Object Functions
*
* Functions that operate on evas rectangle objects.
*
* @ingroup Evas_Object_Specific
*/
/**
* Adds a rectangle to the given evas.
* @param e The given evas.
* @return The new rectangle object.
*/
EAPI Evas_Object *evas_object_rectangle_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* @defgroup Evas_Object_Image Image Object Functions
*
* Functions used to create and manipulate image objects.
*
* Note - Image objects may return or accept "image data" in multiple
* formats. This is based on the colorspace of an object. Here is a
* rundown on formats:
*
* EVAS_COLORSPACE_ARGB8888:
*
* This pixel format is a linear block of pixels, starting at the
* top-left row by row until the bottom right of the image or pixel
* region. All pixels are 32-bit unsigned int's with the high-byte
* being alpha and the low byte being blue in the format ARGB. Alpha
* may or may not be used by evas depending on the alpha flag of the
* image, but if not used, should be set to 0xff anyway.
*
* This colorspace uses premultiplied alpha. That means that R, G and
* B cannot exceed A in value. The conversion from non-premultiplied
* colorspace is:
*
* R = (r * a) / 255; G = (g * a) / 255; B = (b * a) / 255;
*
* So 50% transparent blue will be: 0x80000080. This will not be
* "dark" - just 50% transparent. Values are 0 == black, 255 == solid
* or full red, green or blue.
*
* EVAS_COLORSPACE_YCBCR422P601_PL:
*
* This is a pointer-list indirected set of YUV (YCbCr) pixel
* data. This means that the data returned or set is not actual pixel
* data, but pointers TO lines of pixel data. The list of pointers
* will first be N rows of pointers to the Y plane - pointing to the
* first pixel at the start of each row in the Y plane. N is the
* height of the image data in pixels. Each pixel in the Y, U and V
* planes is 1 byte exactly, packed. The next N / 2 pointers will
* point to rows in the U plane, and the next N / 2 pointers will
* point to the V plane rows. U and V planes are half the horizontal
* and vertical resolution of the Y plane.
*
* Row order is top to bottom and row pixels are stored left to right.
*
* There is a limitation that these images MUST be a multiple of 2
* pixels in size horizontally or vertically. This is due to the U and
* V planes being half resolution. Also note that this assumes the
* itu601 YUV colorspace specification. This is defined for standard
* television and mpeg streams. HDTV may use the itu709
* specification.
*
* Values are 0 to 255, indicating full or no signal in that plane
* respectively.
*
* EVAS_COLORSPACE_YCBCR422P709_PL:
*
* Not implemented yet.
*
* EVAS_COLORSPACE_RGB565_A5P:
*
* In the process of being implemented in 1 engine only. This may change.
*
* This is a pointer to image data for 16-bit half-word pixel data in
* 16bpp RGB 565 format (5 bits red, 6 bits green, 5 bits blue), with
* the high-byte containing red and the low byte containing blue, per
* pixel. This data is packed row by row from the top-left to the
* bottom right.
*
* If the image has an alpha channel enabled there will be an extra
* alpha plane after the color pixel plane. If not, then this data
* will not exist and should not be accessed in any way. This plane is
* a set of pixels with 1 byte per pixel defining the alpha values of
* all pixels in the image from the top-left to the bottom right of
* the image, row by row. Even though the values of the alpha pixels
* can be 0 to 255, only values 0 through to 32 are used, 32 being
* solid and 0 being transparent.
*
* RGB values can be 0 to 31 for red and blue and 0 to 63 for green,
* with 0 being black and 31 or 63 being full red, green or blue
* respectively. This colorspace is also pre-multiplied like
* EVAS_COLORSPACE_ARGB8888 so:
*
* R = (r * a) / 32; G = (g * a) / 32; B = (b * a) / 32;
*
* EVAS_COLORSPACE_A8:
*
* The image is just a alpha mask (8 bit's per pixel). This is used for alpha
* masking.
*
* @ingroup Evas_Object_Specific
*/
typedef void (*Evas_Object_Image_Pixels_Get_Cb) (void *data, Evas_Object *o);
/**
* Creates a new image object on the given evas.
*
* @param e The given evas.
* @return The created image object.
*/
EAPI Evas_Object *evas_object_image_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* Creates a new image object that automatically scales on the given evas.
*
* This is a helper around evas_object_image_add() and
* evas_object_image_filled_set(), it will track object resizes and apply
* evas_object_image_fill_set() with the new geometry.
*
* @see evas_object_image_add()
* @see evas_object_image_filled_set()
* @see evas_object_image_fill_set()
*/
EAPI Evas_Object *evas_object_image_filled_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* Sets the data for an image from memory to be loaded
*
* This is the same as evas_object_image_file_set() but the file to be loaded
* may exist at an address in memory (the data for the file, not the filename
* itself). The @p data at the address is copied and stored for future use, so
* no @p data needs to be kept after this call is made. It will be managed and
* freed for you when no longer needed. The @p size is limited to 2 gigabytes
* in size, and must be greater than 0. A NULL @p data pointer is also invalid.
* Set the filename to NULL to reset to empty state and have the image file
* data freed from memory using evas_object_image_file_set().
*
* The @p format is optional (pass NULL if you don't need/use it). It is used
* to help Evas guess better which loader to use for the data. It may simply
* be the "extension" of the file as it would normally be on disk such as
* "jpg" or "png" or "gif" etc.
*
* @param obj The given image object.
* @param data The image file data address
* @param size The size of the image file data in bytes
* @param format The format of the file (optional), or NULL if not needed
* @param key The image key in file, or NULL.
*/
EAPI void evas_object_image_memfile_set (Evas_Object *obj, void *data, int size, char *format, char *key) EINA_ARG_NONNULL(1, 2);
/**
* Sets the filename and key of the given image object.
*
* If the file supports multiple data stored in it as eet, you can
* specify the key to be used as the index of the image in this file.
*
* @param obj The given image object.
* @param file The image filename.
* @param key The image key in file, or NULL.
*/
EAPI void evas_object_image_file_set (Evas_Object *obj, const char *file, const char *key) EINA_ARG_NONNULL(1);
/**
* Retrieves the filename and key of the given image object.
*
* @param obj The given image object.
* @param file Location to store the image filename, or NULL.
* @param key Location to store the image key, or NULL.
*/
EAPI void evas_object_image_file_get (const Evas_Object *obj, const char **file, const char **key) EINA_ARG_NONNULL(1, 2);
/**
* Sets how much of each border of the given image object is not
* to be scaled.
*
* When rendering, the image may be scaled to fit the size of the
* image object. This function sets what area around the border of the
* image is not to be scaled. This sort of function is useful for
* widget theming, where, for example, buttons may be of varying
* sizes, but the border size must remain constant.
*
* The units used for @p l, @p r, @p t and @p b are output units.
*
* @param obj The given image object.
* @param l Distance of the left border that is not to be stretched.
* @param r Distance of the right border that is not to be stretched.
* @param t Distance of the top border that is not to be stretched.
* @param b Distance of the bottom border that is not to be stretched.
*/
EAPI void evas_object_image_border_set (Evas_Object *obj, int l, int r, int t, int b) EINA_ARG_NONNULL(1);
/**
* Retrieves how much of each border of the given image object is not
* to be scaled.
*
* See @ref evas_object_image_border_set for more details.
*
* @param obj The given image object.
* @param l Location to store the left border width in, or NULL.
* @param r Location to store the right border width in, or NULL.
* @param t Location to store the top border width in, or NULL.
* @param b Location to store the bottom border width in, or NULL.
*/
EAPI void evas_object_image_border_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
/**
* Sets if the center part of the given image object (not the border)
* should be drawn.
*
* When rendering, the image may be scaled to fit the size of the
* image object. This function sets if the center part of the scaled
* image is to be drawn or left completely blank, or forced to be
* solid. Very useful for frames and decorations.
*
* @param obj The given image object.
* @param fill Fill mode of the middle.
*/
EAPI void evas_object_image_border_center_fill_set (Evas_Object *obj, Evas_Border_Fill_Mode fill) EINA_ARG_NONNULL(1);
/**
* Retrieves if the center of the given image object is to be drawn or
* not.
*
* See @ref evas_object_image_fill_set for more details.
*
* @param obj The given image object.
* @return Fill mode of the center.
*/
EAPI Evas_Border_Fill_Mode evas_object_image_border_center_fill_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets if image fill property should track object size.
*
* If set to true, then every evas_object_resize() will automatically
* trigger call to evas_object_image_fill_set() with the new size so
* image will fill the whole object area.
*
* @param obj The given image object.
* @param setting whether to follow object size.
*
* @see evas_object_image_filled_add()
* @see evas_object_image_fill_set()
*/
EAPI void evas_object_image_filled_set (Evas_Object *obj, Eina_Bool setting) EINA_ARG_NONNULL(1);
/**
* Retrieves if image fill property is tracking object size.
*
* @param obj The given image object.
* @return 1 if it is tracking, 0 if not and evas_object_fill_set()
* must be called manually.
*/
EAPI Eina_Bool evas_object_image_filled_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets a scale factor (multiplier) for the borders of an image
*
* @param obj The given image object.
* @param scale The scale factor (default is 1.0 - i.e. no scale)
*/
EAPI void evas_object_image_border_scale_set (Evas_Object *obj, double scale);
/**
* Retrieves the border scale factor
*
* See evas_object_image_border_scale_set()
*
* @param obj The given image object.
* @return The scale factor
*/
EAPI double evas_object_image_border_scale_get (const Evas_Object *obj);
/**
* Sets the rectangle of the given image object that the image will be
* drawn to.
*
* Note that the image will be tiled around this one rectangle. To
* have only one copy of the image drawn, @p x and @p y must be 0 and
* @p w and @p h need to be the width and height of the image object
* respectively.
*
* The default values for the fill parameters is @p x = 0, @p y = 0,
* @p w = 32 and @p h = 32.
*
* @param obj The given image object.
* @param x The X coordinate for the top left corner of the image.
* @param y The Y coordinate for the top left corner of the image.
* @param w The width of the image.
* @param h The height of the image.
*/
EAPI void evas_object_image_fill_set (Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
/**
* Retrieves the dimensions of the rectangle of the given image object
* that the image will be drawn to.
*
* See @ref evas_object_image_fill_set for more details.
*
* @param obj The given image object.
* @param x Location to store the X coordinate for the top left corner of the image in, or NULL.
* @param y Location to store the Y coordinate for the top left corner of the image in, or NULL.
* @param w Location to store the width of the image in, or NULL.
* @param h Location to store the height of the image in, or NULL.
*/
EAPI void evas_object_image_fill_get (const Evas_Object *obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Sets the tiling mode for the given evas image object's fill.
* @param obj The given evas image object.
* @param spread One of EVAS_TEXTURE_REFLECT, EVAS_TEXTURE_REPEAT,
* EVAS_TEXTURE_RESTRICT, or EVAS_TEXTURE_PAD.
*/
EAPI void evas_object_image_fill_spread_set (Evas_Object *obj, Evas_Fill_Spread spread) EINA_ARG_NONNULL(1);
/**
* Retrieves the spread (tiling mode) for the given image object's
* fill.
*
* @param obj The given evas image object.
* @return The current spread mode of the image object.
*/
EAPI Evas_Fill_Spread evas_object_image_fill_spread_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the size of the given image object.
*
* This function will scale down or crop the image so that it is
* treated as if it were at the given size. If the size given is
* smaller than the image, it will be cropped. If the size given is
* larger, then the image will be treated as if it were in the upper
* left hand corner of a larger image that is otherwise transparent.
*
* @param obj The given image object.
* @param w The new width of the image.
* @param h The new height of the image.
*/
EAPI void evas_object_image_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
/**
* Retrieves the size of the given image object.
*
* See @ref evas_object_image_size_set for more details.
*
* @param obj The given image object.
* @param w Location to store the width of the image in, or NULL.
* @param h Location to store the height of the image in, or NULL.
*/
EAPI void evas_object_image_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
/**
* Retrieves the row stride of the given image object,
*
* The row stride is the number of units between the start of a
* row and the start of the next row.
*
* @param obj The given image object.
* @return The stride of the image.
*/
EAPI int evas_object_image_stride_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieves a number representing any error that occurred during the last
* load of the given image object.
*
* @param obj The given image object.
* @return A value giving the last error that occurred. It should be one of
* the @c EVAS_LOAD_ERROR_* values. @c EVAS_LOAD_ERROR_NONE is
* returned if there was no error.
*/
EAPI Evas_Load_Error evas_object_image_load_error_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets the raw image data of the given image object.
*
* Note that the raw data must be of the same size and colorspace of
* the image. If data is NULL the current image data will be freed.
*
* @param obj The given image object.
* @param data The raw data, or NULL.
*/
EAPI void evas_object_image_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
/**
* Converts the raw image data of the given image object to the
* specified colorspace.
*
* Note that this function does not modify the raw image data. If the
* requested colorspace is the same as the image colorspace nothing is
* done and NULL is returned. You should use
* evas_object_image_colorspace_get() to check the current image
* colorspace.
*
* See @ref evas_object_image_colorspace_get.
*
* @param obj The given image object.
* @param to_cspace The colorspace to which the image raw data will be converted.
* @return data A newly allocated data in the format specified by to_cspace.
*/
EAPI void *evas_object_image_data_convert (Evas_Object *obj, Evas_Colorspace to_cspace) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Get a pointer to the raw image data of the given image object.
*
* This function returns a pointer to an image object's internal pixel
* buffer, for reading only or read/write. If you request it for
* writing, the image will be marked dirty so that it gets redrawn at
* the next update.
*
* This is best suited when you want to modify an existing image,
* without changing its dimensions.
*
* @param obj The given image object.
* @param for_writing Whether the data being retrieved will be modified.
* @return The raw image data.
*/
EAPI void *evas_object_image_data_get (const Evas_Object *obj, Eina_Bool for_writing) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Replaces the raw image data of the given image object.
*
* This function lets the application replace an image object's
* internal pixel buffer with a user-allocated one. For best results,
* you should generally first call evas_object_image_size_set() with
* the width and height for the new buffer.
*
* This call is best suited for when you will be using image data with
* different dimensions than the existing image data, if any. If you
* only need to modify the existing image in some fashion, then using
* evas_object_image_data_get() is probably what you are after.
*
* Note that the caller is responsible for freeing the buffer when
* finished with it, as user-set image data will not be automatically
* freed when the image object is deleted.
*
* See @ref evas_object_image_data_get for more details.
*
* @param obj The given image object.
* @param data The raw data.
*/
EAPI void evas_object_image_data_copy_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1);
/**
* Mark a sub-region of the given image object to be redrawn.
*
* This function schedules a particular rectangular region of an image
* object to be updated (redrawn) at the next render.
*
* @param obj The given image object.
* @param x X-offset of the region to be updated.
* @param y Y-offset of the region to be updated.
* @param w Width of the region to be updated.
* @param h Height of the region to be updated.
*/
EAPI void evas_object_image_data_update_add (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
/**
* Enable or disable alpha channel of the given image object.
*
* This function sets a flag on an image object indicating whether or
* not to use alpha channel data. A value of 1 indicates to use alpha
* channel data, and 0 indicates to ignore any alpha channel
* data. Note that this has nothing to do with an object's color as
* manipulated by evas_object_color_set().
*
* @param obj The given image object.
* @param has_alpha Whether to use alpha channel data or not.
*/
EAPI void evas_object_image_alpha_set (Evas_Object *obj, Eina_Bool has_alpha) EINA_ARG_NONNULL(1);
/**
* @brief Retrieves the alpha channel setting of the given image object.
*
* @param obj The given image object.
* @return Whether the alpha channel data is being used.
*
* This function returns 1 if the image object's alpha channel is
* being used, or 0 otherwise.
*
* See @ref evas_object_image_alpha_set for more details.
*/
EAPI Eina_Bool evas_object_image_alpha_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Sets whether to use of high-quality image scaling algorithm
* of the given image object.
*
* When enabled, a higher quality image scaling algorithm is used when
* scaling images to sizes other than the source image. This gives
* better results but is more computationally expensive.
*
* @param obj The given image object.
* @param smooth_scale Whether to use smooth scale or not.
*/
EAPI void evas_object_image_smooth_scale_set (Evas_Object *obj, Eina_Bool smooth_scale) EINA_ARG_NONNULL(1);
/**
* Retrieves whether the given image object is using use a
* high-quality image scaling algorithm.
*
* See @ref evas_object_image_smooth_scale_set for more details.
*
* @param obj The given image object.
* @return Whether smooth scale is being used.
*/
EAPI Eina_Bool evas_object_image_smooth_scale_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Preload image in the background
*
* This function request the preload of the data image in the
* background. The worked is queued before being processed.
*
* If image data is already loaded, it will callback
* EVAS_CALLBACK_IMAGE_PRELOADED immediately and do nothing else.
*
* If cancel is set, it will remove the image from the workqueue.
*
* @param obj The given image object.
* @param cancel 0 means add to the workqueue, 1 remove it.
*/
EAPI void evas_object_image_preload (Evas_Object *obj, Eina_Bool cancel) EINA_ARG_NONNULL(1);
/**
* Reload a image of the canvas.
*
* @param obj The given image object pointer.
*
* This function reloads a image of the given canvas.
*
*/
EAPI void evas_object_image_reload (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Save the given image object to a file.
*
* Note that you should pass the filename extension when saving. If
* the file supports multiple data stored in it as eet, you can
* specify the key to be used as the index of the image in this file.
*
* You can specify some flags when saving the image. Currently
* acceptable flags are quality and compress. Eg.: "quality=100
* compress=9"
*
* @param obj The given image object.
* @param file The filename to be used to save the image.
* @param key The image key in file, or NULL.
* @param flags String containing the flags to be used.
*/
EAPI Eina_Bool evas_object_image_save (const Evas_Object *obj, const char *file, const char *key, const char *flags) EINA_ARG_NONNULL(1, 2);
/**
* Import pixels from given source to a given canvas image object.
*
* @param obj The given canvas object.
* @param pixels The pixel's source to be imported.
*
* This function imports pixels from a given source to a given canvas image.
*
*/
EAPI Eina_Bool evas_object_image_pixels_import (Evas_Object *obj, Evas_Pixel_Import_Source *pixels) EINA_ARG_NONNULL(1, 2);
/**
* Set the callback function to get pixels from a canva's image.
*
* @param obj The given canvas pointer.
* @param func The callback function.
* @param data The data pointer to be passed to @a func.
*
* This functions sets a function to be the callback function that get
* pixes from a image of the canvas.
*
*/
EAPI void evas_object_image_pixels_get_callback_set(Evas_Object *obj, Evas_Object_Image_Pixels_Get_Cb func, void *data) EINA_ARG_NONNULL(1, 2);
/**
* Mark whether the given image object is dirty (needs to be redrawn).
*
* @param obj The given image object.
* @param dirty Whether the image is dirty.
*/
EAPI void evas_object_image_pixels_dirty_set (Evas_Object *obj, Eina_Bool dirty) EINA_ARG_NONNULL(1);
/**
* Retrieves whether the given image object is dirty (needs to be redrawn).
*
* @param obj The given image object.
* @return Whether the image is dirty.
*/
EAPI Eina_Bool evas_object_image_pixels_dirty_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set the dpi resolution of a loaded image of the canvas.
*
* @param obj The given canvas pointer.
* @param dpi The new dpi resolution.
*
* This function set the dpi resolution of a given loaded canvas image.
*
*/
EAPI void evas_object_image_load_dpi_set (Evas_Object *obj, double dpi) EINA_ARG_NONNULL(1);
/**
* Get the dpi resolution of a loaded image of the canvas.
*
* @param obj The given canvas pointer.
* @return The dpi resolution of the given canvas image.
*
* This function returns the dpi resolution of given canvas image.
*
*/
EAPI double evas_object_image_load_dpi_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set the size of a loaded image of the canvas.
*
* @param obj The given canvas object.
* @param w The new width of the canvas image given.
* @param h The new height of the canvas image given.
*
* This function sets a new size for the given canvas image.
*
*/
EAPI void evas_object_image_load_size_set (Evas_Object *obj, int w, int h) EINA_ARG_NONNULL(1);
/**
* Get the size of a loaded image of the canvas.
*
* @param obj The given image object.
* @param w The width of the canvas image given.
* @param h The height of the canvas image given.
*
* This function get the size of the given canvas image.
*
*/
EAPI void evas_object_image_load_size_get (const Evas_Object *obj, int *w, int *h) EINA_ARG_NONNULL(1);
/**
* Set the scale down of a loaded image of the canvas.
*
* @param obj The given image object pointer.
* @param scale_down The scale to down value.
*
* This function sets the scale down of a given canvas image.
*
*/
EAPI void evas_object_image_load_scale_down_set (Evas_Object *obj, int scale_down) EINA_ARG_NONNULL(1);
/**
* Get the scale down value of given image of the canvas.
*
* @param obj The given image object pointer.
*
* This function returns the scale down value of a given canvas image.
*
*/
EAPI int evas_object_image_load_scale_down_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void evas_object_image_load_region_set (Evas_Object *obj, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
EAPI void evas_object_image_load_region_get (const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
/**
* Define if the orientation information in the image file should be honored.
*
* @param obj The given image object pointer.
* @param enable @p EINA_TRUE means that it should honor the orientation information
* @since 1.1
*/
EAPI void evas_object_image_load_orientation_set (Evas_Object *obj, Eina_Bool enable) EINA_ARG_NONNULL(1);
/**
* Get if the orientation information in the image file should be honored.
*
* @param obj The given image object pointer.
* @since 1.1
*/
EAPI Eina_Bool evas_object_image_load_orientation_get (const Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Set the colorspace of a given image of the canvas.
*
* @param obj The given image object pointer.
* @param cspace The new color space.
*
* This function sets the colorspace of given canvas image.
*
*/
EAPI void evas_object_image_colorspace_set (Evas_Object *obj, Evas_Colorspace cspace) EINA_ARG_NONNULL(1);
/**
* Get the colorspace of a given image of the canvas.
*
* @param obj The given image object pointer.
* @return The colorspace of the image.
*
* This function returns the colorspace of given canvas image.
*
*/
EAPI Evas_Colorspace evas_object_image_colorspace_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set the native surface of a given image of the canvas
*
* @param obj The given canvas pointer.
* @param surf The new native surface.
*
* This function sets a native surface of a given canvas image.
*
*/
EAPI void evas_object_image_native_surface_set (Evas_Object *obj, Evas_Native_Surface *surf) EINA_ARG_NONNULL(1, 2);
/**
* Get the native surface of a given image of the canvas
*
* @param obj The given canvas pointer.
* @return The native surface of the given canvas image.
*
* This function returns the native surface of a given canvas image.
*
*/
EAPI Evas_Native_Surface *evas_object_image_native_surface_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set the scale hint of a given image of the canvas.
*
* @param obj The given canvas pointer.
* @param hint The scale hint value.
*
* This function sets the scale hint value of the given image of the canvas.
*
*/
EAPI void evas_object_image_scale_hint_set (Evas_Object *obj, Evas_Image_Scale_Hint hint) EINA_ARG_NONNULL(1);
/**
* Get the scale hint of a given image of the canvas.
*
* @param obj The given canvas pointer.
*
* This function returns the scale hint value of the given image of the canvas.
*
*/
EAPI Evas_Image_Scale_Hint evas_object_image_scale_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Set the content hint of a given image of the canvas.
*
* @param obj The given canvas pointer.
* @param hint The content hint value.
*
* This function sets the content hint value of the given image of the canvas.
*
*/
EAPI void evas_object_image_content_hint_set (Evas_Object *obj, Evas_Image_Content_Hint hint) EINA_ARG_NONNULL(1);
/**
* Get the content hint of a given image of the canvas.
*
* @param obj The given canvas pointer.
*
* This function returns the content hint value of the given image of the canvas.
*
*/
EAPI Evas_Image_Content_Hint evas_object_image_content_hint_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Enable an image to be used as an alpha mask.
*
* This will set any flags, and discard any excess image data not used as an
* alpha mask.
*
* Note there is little point in using a image as alpha mask unless it has an
* alpha channel.
*
* @param obj Object to use as an alpha mask.
* @param ismask Use image as alphamask, must be true.
*/
EAPI void evas_object_image_alpha_mask_set (Evas_Object *obj, Eina_Bool ismask) EINA_ARG_NONNULL(1);
/**
* Set the source object on a proxy object.
*
* The source must be another object. The proxy will have the same base
* appearance of the source object. Obviously other effects may be applied to
* the proxy, such as a map to create a reflection of the original object.
*
* Any existing source object will be removed. Setting the src to NULL clears
* the proxy object.
*
* You cannot set a proxy on a proxy.
*
* @param obj Proxy object.
* @param src Source of the proxy.
* @return EINA_TRUE on success, EINA_FALSE on error.
*/
EAPI Eina_Bool evas_object_image_source_set (Evas_Object *obj, Evas_Object *src) EINA_ARG_NONNULL(1);
/**
* Get the current source object of an image.
*
* @param obj Image object
* @return Source object, or NULL on error.
*/
EAPI Evas_Object *evas_object_image_source_get (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Clear the source on a proxy image.
*
* This is equivalent to calling evas_object_image_source_set with a NULL
* source.
*
* @param obj Image object to clear source of.
* @return EINA_TRUE on success, EINA_FALSE on error.
*/
EAPI Eina_Bool evas_object_image_source_unset (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Check if a file extention may be supported by @ref Evas_Object_Image.
*
* @param file The file to check
* @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
* @since 1.1.0
*
* If file is a Eina_Stringshare, use directly @ref evas_object_image_extension_can_load_fast_get.
*
* This functions is threadsafe.
*/
EAPI Eina_Bool evas_object_image_extension_can_load_get(const char *file);
/**
* Check if a file extention may be supported by @ref Evas_Object_Image.
*
* @param file The file to check, it should be an Eina_Stringshare.
* @return EINA_TRUE if we may be able to opeen it, EINA_FALSE if it's unlikely.
* @since 1.1.0
*
* This functions is threadsafe.
*/
EAPI Eina_Bool evas_object_image_extension_can_load_fast_get(const char *file);
/**
* @defgroup Evas_Object_Text Text Object Functions
*
* Functions that operate on single line, single style text objects.
*
* For multiline and multiple style text, see @ref Evas_Object_Textblock.
*
* @ingroup Evas_Object_Specific
*/
typedef enum _Evas_Text_Style_Type
{
/* basic styles (4 bits allocatedm use 0->10 now, 5 left) */
#define EVAS_TEXT_STYLE_MASK_BASIC 0xf
#define EVAS_TEXT_STYLE_BASIC_SET(x, s) \
do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_BASIC) | (s); } while (0)
EVAS_TEXT_STYLE_PLAIN,
EVAS_TEXT_STYLE_SHADOW,
EVAS_TEXT_STYLE_OUTLINE,
EVAS_TEXT_STYLE_SOFT_OUTLINE,
EVAS_TEXT_STYLE_GLOW,
EVAS_TEXT_STYLE_OUTLINE_SHADOW,
EVAS_TEXT_STYLE_FAR_SHADOW,
EVAS_TEXT_STYLE_OUTLINE_SOFT_SHADOW,
EVAS_TEXT_STYLE_SOFT_SHADOW,
EVAS_TEXT_STYLE_FAR_SOFT_SHADOW,
#define EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION (0x7 << 4)
#define EVAS_TEXT_STYLE_SHADOW_DIRECTION_SET(x, s) \
do { x = ((x) & ~EVAS_TEXT_STYLE_MASK_SHADOW_DIRECTION) | (s); } while (0)
/* OR these to modify shadow direction (3 bits needed) */
EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM = (0x1 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_LEFT = (0x3 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP = (0x5 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4),
EVAS_TEXT_STYLE_SHADOW_DIRECTION_RIGHT = (0x7 << 4)
} Evas_Text_Style_Type;
/**
* Creates a new text @c Evas_Object on the provided @c Evas canvas.
*
* @param e The @c Evas canvas to create the text object upon.
*
* @see evas_object_text_font_source_set
* @see evas_object_text_font_set
* @see evas_object_text_text_set
*
* @returns NULL on error, A pointer to a new @c Evas_Object on success.
*/
EAPI Evas_Object *evas_object_text_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
EAPI void evas_object_text_font_source_set (Evas_Object *obj, const char *font) EINA_ARG_NONNULL(1);
EAPI const char *evas_object_text_font_source_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void evas_object_text_font_set (Evas_Object *obj, const char *font, Evas_Font_Size size) EINA_ARG_NONNULL(1);
/**
* Query evas for font information of a text @c Evas_Object.
*
* This function allows the font name and size of a text @c Evas_Object as
* created with evas_object_text_add() to be queried. Be aware that the font
* name string is still owned by Evas and should NOT have free() called on
* it by the caller of the function.
*
* @param obj The evas text object to query for font information.
* @param font A pointer to the location to store the font name in (may be NULL).
* @param size A pointer to the location to store the font size in (may be NULL).
*/
EAPI void evas_object_text_font_get (const Evas_Object *obj, const char **font, Evas_Font_Size *size) EINA_ARG_NONNULL(1, 2);
/**
* Sets the text to be displayed by the given evas text object.
* @param obj Evas text object.
* @param text Text to display.
*/
EAPI void evas_object_text_text_set (Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
/**
* @brief Sets the BiDi delimiters used in the textblock.
*
* BiDi delimiters are use for in-paragraph separation of bidi segments. This
* is useful for example in recipients fields of e-mail clients where bidi
* oddities can occur when mixing rtl and ltr.
*
* @param obj The given text object.
* @param delim A null terminated string of delimiters, e.g ",|".
* @since 1.1.0
*/
EAPI void evas_object_text_bidi_delimiters_set(Evas_Object *obj, const char *delim);
/**
* @brief Gets the BiDi delimiters used in the textblock.
*
* BiDi delimiters are use for in-paragraph separation of bidi segments. This
* is useful for example in recipients fields of e-mail clients where bidi
* oddities can occur when mixing rtl and ltr.
*
* @param obj The given text object.
* @return A null terminated string of delimiters, e.g ",|". If empty, returns NULL.
* @since 1.1.0
*/
EAPI const char *evas_object_text_bidi_delimiters_get(const Evas_Object *obj);
/**
* Retrieves the text currently being displayed by the given evas text object.
* @param obj The given evas text object.
* @return The text currently being displayed. Do not free it.
*/
EAPI const char *evas_object_text_text_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_max_ascent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_max_descent_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_horiz_advance_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_vert_advance_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI Evas_Coord evas_object_text_inset_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Retrieve position and dimension information of a character within a text @c Evas_Object.
*
* This function is used to obtain the X, Y, width and height of a the character
* located at @p pos within the @c Evas_Object @p obj. @p obj must be a text object
* as created with evas_object_text_add(). Any of the @c Evas_Coord parameters (@p cx,
* @p cy, @p cw, @p ch) may be NULL in which case no value will be assigned to that
* parameter.
*
* @param obj The text object to retrieve position information for.
* @param pos The character position to request co-ordinates for.
* @param cx A pointer to an @c Evas_Coord to store the X value in (can be NULL).
* @param cy A pointer to an @c Evas_Coord to store the Y value in (can be NULL).
* @param cw A pointer to an @c Evas_Coord to store the Width value in (can be NULL).
* @param ch A pointer to an @c Evas_Coord to store the Height value in (can be NULL).
*
* @returns EINA_FALSE on error, EINA_TRUE on success.
*/
EAPI Eina_Bool evas_object_text_char_pos_get (const Evas_Object *obj, int pos, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
EAPI int evas_object_text_char_coords_get (const Evas_Object *obj, Evas_Coord x, Evas_Coord y, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Returns the logical position of the last char in the text
* up to the pos given. this is NOT the position of the last char
* because of the possibility of RTL in the text.
*/
EAPI int evas_object_text_last_up_to_pos (const Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
EAPI Evas_Text_Style_Type evas_object_text_style_get (const Evas_Object *obj) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
EAPI void evas_object_text_style_set (Evas_Object *obj, Evas_Text_Style_Type type) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_shadow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_shadow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_glow_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_glow_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_glow2_color_set (Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_glow2_color_get (const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_outline_color_set(Evas_Object *obj, int r, int g, int b, int a) EINA_ARG_NONNULL(1);
EAPI void evas_object_text_outline_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a) EINA_ARG_NONNULL(1);
/**
* Gets the text style pad of a text object.
*
* @param obj The given text object.
* @param l The left pad (or NULL).
* @param r The right pad (or NULL).
* @param t The top pad (or NULL).
* @param b The bottom pad (or NULL).
*
*/
EAPI void evas_object_text_style_pad_get (const Evas_Object *obj, int *l, int *r, int *t, int *b) EINA_ARG_NONNULL(1);
/**
* Retrieves the direction of the text currently being displayed in the
* text object.
* @param obj The given evas text object.
* @return the direction of the text
*/
EAPI Evas_BiDi_Direction evas_object_text_direction_get (const Evas_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @defgroup Evas_Object_Textblock Textblock Object Functions
*
* Functions used to create and manipulate textblock objects. Unlike
* @ref Evas_Object_Text, these handle complex text, doing multiple
* styles and multiline text based on HTML-like tags. Of these extra
* features will be heavier on memory and processing cost.
*
* @todo put here some usage examples
*
* @ingroup Evas_Object_Specific
*/
/**
* @section Evas_Object_Textblock_Tutorial Textblock Object Tutorial
*
* This part explains about the textblock object's API and proper usage.
* If you want to develop textblock, you should also refer to @ref Evas_Object_Textblock_Internal.
* The main user of the textblock object is the edje entry object in Edje, so
* that's a good place to learn from, but I think this document is more than
* enough, if it's not, please request for me info and I'll update it.
*
* @subsection textblock_intro Introduction
* The textblock objects is, as implied, an object that can show big chunks of
* text. Textblock supports many features including: Text formatting, automatic
* and manual text alignment, embedding items (for example icons) and more.
* Textblock has three important parts, the text paragraphs, the format nodes
* and the cursors.
*
* @subsection textblock_cursors Textblock Object Cursors
* A textblock Cursor @ref Evas_Textblock_Cursor is data type that represents
* a position in a textblock. Each cursor contains information about the
* paragraph it points to, the position in that paragraph and the object itself.
* Cursors register to textblock objects upon creation, this means that once
* you created a cursor, it belongs to a specific obj and you can't for example
* copy a cursor "into" a cursor of a different object. Registered cursors
* also have the added benefit of updating automatically upon textblock changes,
* this means that if you have a cursor pointing to a specific character, it'll
* still point to it even after you change the whole object completely (as long
* as the char was not deleted), this is not possible without updating, because
* as mentioned, each cursor holds a character position. There are many
* functions that handle cursors, just check out the evas_textblock_cursor*
* functions. For creation and deletion of cursors check out:
* @see evas_object_textblock_cursor_new()
* @see evas_textblock_cursor_free()
* @note Cursors are generally the correct way to handle text in the textblock object, and there are enough functions to do everything you need with them (no need to get big chunks of text and processing them yourself).
*
* @subsection textblock_paragraphs Textblock Object Paragraphs
* The textblock object is made out of text splitted to paragraphs (delimited
* by the paragraph separation character). Each paragraph has many (or none)
* format nodes associated with it which are responsible for the formatting
* of that paragraph.
*
* @subsection textblock_format_nodes Textblock Object Format Nodes
* As explained in @ref textblock_paragraphs each one of the format nodes
* is associated with a paragraph.
* There are two types of format nodes, visible and invisible:
* Visible: formats that a cursor can point to, i.e formats that
* occupy space, for example: newlines, tabs, items and etc. Some visible items
* are made of two parts, in this case, only the opening tag is visible.
* A closing tag (i.e a tag) should NEVER be visible.
* Invisible: formats that don't occupy space, for example: bold and underline.
* Being able to access format nodes is very important for some uses. For
* example, edje uses the "" format to create links in the text (and pop
* popups above them when clicked). For the textblock object a is just a
* formatting instruction (how to color the text), but edje utilizes the access
* to the format nodes to make it do more.
* For more information, take a look at all the evas_textblock_node_format_*
* functions.
* The translation of "
won't work here. For those kind of things use markup prepend.
*
* @param cur the cursor to where to add format at.
* @param format the format to add.
* @return Returns true if a visible format was added, false otherwise.
* @see evas_textblock_cursor_format_prepend()
*/
/**
* Check if the current cursor position points to the terminating null of the
* last paragraph. (shouldn't be allowed to point to the terminating null of
* any previous paragraph anyway.
*
* @param cur the cursor to look at.
* @return #EINA_TRUE if the cursor points to the terminating null, #EINA_FALSE otherwise.
*/
EAPI Eina_Bool evas_textblock_cursor_format_append(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
/**
* Adds format to the current cursor position. If the format being added is a
* visible format, add it *before* the cursor position, otherwise, add it after.
* This behavior is because visible formats are like characters and invisible
* should be stacked in a way that the last one is added last.
* If the format is visible the cursor is advanced after it.
*
* This function works with native formats, that means that style defined
* tags like
won't work here. For those kind of things use markup prepend.
*
* @param cur the cursor to where to add format at.
* @param format the format to add.
* @return Returns true if a visible format was added, false otherwise.
* @see evas_textblock_cursor_format_prepend()
*/
EAPI Eina_Bool evas_textblock_cursor_format_prepend(Evas_Textblock_Cursor *cur, const char *format) EINA_ARG_NONNULL(1, 2);
/**
* Delete the character at the location of the cursor. If there's a format
* pointing to this position, delete it as well.
*
* @param cur the cursor pointing to the current location.
* @return Returns no value.
*/
EAPI void evas_textblock_cursor_char_delete(Evas_Textblock_Cursor *cur) EINA_ARG_NONNULL(1);
/**
* Delete the range between cur1 and cur2.
*
* @param cur1 one side of the range.
* @param cur2 the second side of the range
* @return Returns no value.
*/
EAPI void evas_textblock_cursor_range_delete(Evas_Textblock_Cursor *cur1, Evas_Textblock_Cursor *cur2) EINA_ARG_NONNULL(1, 2);
/**
* Return the text of the paragraph cur points to - returns the text in markup..
*
* @param cur the cursor pointing to the paragraph.
* @return the text on success, NULL otherwise.
*/
EAPI const char *evas_textblock_cursor_paragraph_text_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Return the length of the paragraph, cheaper the eina_unicode_strlen()
*
* @param cur the position of the paragraph.
* @return the length of the paragraph on success, -1 otehrwise.
*/
EAPI int evas_textblock_cursor_paragraph_text_length_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Return the text in the range between cur1 and cur2
*
* FIXME: format is currently unused, you always get markup back.
*
* @param cur1 one side of the range.
* @param cur2 the other side of the range
* @param format to be documented
* @return the text in the range
* @see elm_entry_markup_to_utf8()
*/
EAPI char *evas_textblock_cursor_range_text_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2, Evas_Textblock_Text_Type format) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
/**
* Return the content of the cursor.
*
* @param cur the cursor
* @return the text in the range
*/
EAPI char *evas_textblock_cursor_content_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* Returns the geometry of the cursor. Depends on the type of cursor requested.
* This should be used instead of char_geometry_get because there are weird
* special cases with BiDi text.
* in '_' cursor mode (i.e a line below the char) it's the same as char_geometry
* get, except for the case of the last char of a line which depends on the
* paragraph direction.
*
* in '|' cursor mode (i.e a line between two chars) it is very varyable.
* For example consider the following visual string:
* "abcCBA" (ABC are rtl chars), a cursor pointing on A should actually draw
* a '|' between the c and the C.
*
* @param cur the cursor.
* @param cx the x of the cursor
* @param cy the y of the cursor
* @param cw the width of the cursor
* @param ch the height of the cursor
* @param dir the direction of the cursor, can be NULL.
* @param ctype the type of the cursor.
* @return line number of the char on success, -1 on error.
*/
EAPI int evas_textblock_cursor_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch, Evas_BiDi_Direction *dir, Evas_Textblock_Cursor_Type ctype) EINA_ARG_NONNULL(1);
/**
* Returns the geometry of the char at cur.
*
* @param cur the position of the char.
* @param cx the x of the char.
* @param cy the y of the char.
* @param cw the w of the char.
* @param ch the h of the char.
* @return line number of the char on success, -1 on error.
*/
EAPI int evas_textblock_cursor_char_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Returns the geometry of the pen at cur.
*
* @param cur the position of the char.
* @param cpen_x the pen_x of the char.
* @param cy the y of the char.
* @param cadv the adv of the char.
* @param ch the h of the char.
* @return line number of the char on success, -1 on error.
*/
EAPI int evas_textblock_cursor_pen_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cpen_x, Evas_Coord *cy, Evas_Coord *cadv, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Returns the geometry of the line at cur.
*
* @param cur the position of the line.
* @param cx the x of the line.
* @param cy the y of the line.
* @param cw the width of the line.
* @param ch the height of the line.
* @return line number of the line on success, -1 on error.
*/
EAPI int evas_textblock_cursor_line_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Set the position of the cursor according to the X and Y coordinates.
*
* @param cur the cursor to set.
* @param x coord to set by.
* @param y coord to set by.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
EAPI Eina_Bool evas_textblock_cursor_char_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
/**
* Set the cursor position according to the y coord.
*
* @param cur the cur to be set.
* @param y the coord to set by.
* @return the line number found, -1 on error.
*/
EAPI int evas_textblock_cursor_line_coord_set(Evas_Textblock_Cursor *cur, Evas_Coord y) EINA_ARG_NONNULL(1);
/**
* Get the geometry of a range.
*
* @param cur1 one side of the range.
* @param cur2 other side of the range.
* @return a list of Rectangles representing the geometry of the range.
*/
EAPI Eina_List *evas_textblock_cursor_range_geometry_get(const Evas_Textblock_Cursor *cur1, const Evas_Textblock_Cursor *cur2) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
EAPI Eina_Bool evas_textblock_cursor_format_item_geometry_get(const Evas_Textblock_Cursor *cur, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Checks if the cursor points to the end of the line.
*
* @param cur the cursor to check.
* @return #EINA_TRUE if true, #EINA_FALSE otherwise.
*/
EAPI Eina_Bool evas_textblock_cursor_eol_get(const Evas_Textblock_Cursor *cur) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Get the geometry of a line number.
*
* @param obj the object.
* @param line the line number.
* @param cx x coord of the line.
* @param cy y coord of the line.
* @param cw w coord of the line.
* @param ch h coord of the line.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
EAPI Eina_Bool evas_object_textblock_line_number_geometry_get(const Evas_Object *obj, int line, Evas_Coord *cx, Evas_Coord *cy, Evas_Coord *cw, Evas_Coord *ch) EINA_ARG_NONNULL(1);
/**
* Clear the textblock object.
* @note Does *NOT* free the evas object itself.
*
* @param obj the object to clear.
* @return nothing.
*/
EAPI void evas_object_textblock_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* Get the formatted width and height. This calculates the actual size after restricting
* the textblock to the current size of the object.
* The main difference between this and @ref evas_object_textblock_size_native_get
* is that the "native" function does not wrapping into account
* it just calculates the real width of the object if it was placed on an
* infinite canvas, while this function gives the size after wrapping
* according to the size restrictions of the object.
*
* For example for a textblock containing the text: "You shall not pass!"
* with no margins or padding and assuming a monospace font and a size of
* 7x10 char widths (for simplicity) has a native size of 19x1
* and a formatted size of 5x4.
*
*
* @param obj the evas object.
* @param w[out] the width of the object.
* @param h[out] the height of the object
* @return Returns no value.
* @see evas_object_textblock_size_native_get
*/
EAPI void evas_object_textblock_size_formatted_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
/**
* Get the native width and height. This calculates the actual size without taking account
* the current size of the object.
* The main difference between this and @ref evas_object_textblock_size_formatted_get
* is that the "native" function does not take wrapping into account
* it just calculates the real width of the object if it was placed on an
* infinite canvas, while the "formatted" function gives the size after
* wrapping text according to the size restrictions of the object.
*
* For example for a textblock containing the text: "You shall not pass!"
* with no margins or padding and assuming a monospace font and a size of
* 7x10 char widths (for simplicity) has a native size of 19x1
* and a formatted size of 5x4.
*
* @param obj the evas object of the textblock
* @param w[out] the width returned
* @param h[out] the height returned
* @return Returns no value.
*/
EAPI void evas_object_textblock_size_native_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h) EINA_ARG_NONNULL(1);
EAPI void evas_object_textblock_style_insets_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b) EINA_ARG_NONNULL(1);
/**
* @defgroup Evas_Line_Group Line Object Functions
*
* Functions used to deal with evas line objects.
*
* @ingroup Evas_Object_Specific
*/
/**
* Adds a new evas line object to the given evas.
* @param e The given evas.
* @return The new evas line object.
*/
EAPI Evas_Object *evas_object_line_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* Sets the coordinates of the end points of the given evas line object.
* @param obj The given evas line object.
* @param x1 The X coordinate of the first point.
* @param y1 The Y coordinate of the first point.
* @param x2 The X coordinate of the second point.
* @param y2 The Y coordinate of the second point.
*/
EAPI void evas_object_line_xy_set (Evas_Object *obj, Evas_Coord x1, Evas_Coord y1, Evas_Coord x2, Evas_Coord y2);
/**
* Retrieves the coordinates of the end points of the given evas line object.
* @param obj The given line object.
* @param x1 Pointer to an integer in which to store the X coordinate of the
* first end point.
* @param y1 Pointer to an integer in which to store the Y coordinate of the
* first end point.
* @param x2 Pointer to an integer in which to store the X coordinate of the
* second end point.
* @param y2 Pointer to an integer in which to store the Y coordinate of the
* second end point.
*/
EAPI void evas_object_line_xy_get (const Evas_Object *obj, Evas_Coord *x1, Evas_Coord *y1, Evas_Coord *x2, Evas_Coord *y2);
/**
* @defgroup Evas_Object_Polygon Polygon Object Functions
*
* Functions that operate on evas polygon objects.
*
* Hint: as evas does not provide ellipse, smooth paths or circle, one
* can calculate points and convert these to a polygon.
*
* @ingroup Evas_Object_Specific
*/
/**
* Adds a new evas polygon object to the given evas.
* @param e The given evas.
* @return A new evas polygon object.
*/
EAPI Evas_Object *evas_object_polygon_add (Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/**
* Adds the given point to the given evas polygon object.
* @param obj The given evas polygon object.
* @param x The X coordinate of the given point.
* @param y The Y coordinate of the given point.
* @ingroup Evas_Polygon_Group
*/
EAPI void evas_object_polygon_point_add (Evas_Object *obj, Evas_Coord x, Evas_Coord y) EINA_ARG_NONNULL(1);
/**
* Removes all of the points from the given evas polygon object.
* @param obj The given polygon object.
*/
EAPI void evas_object_polygon_points_clear (Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* @defgroup Evas_Smart_Group Smart Functions
*
* Functions that deal with Evas_Smart's, creating definition
* (classes) of objects that will have customized behavior for methods
* like evas_object_move(), evas_object_resize(),
* evas_object_clip_set() and others.
*
* These objects will accept the generic methods defined in @ref
* Evas_Object_Group and the extensions defined in @ref
* Evas_Smart_Object_Group. There are couple of existent smart objects
* in Evas itself, see @ref Evas_Object_Box, @ref Evas_Object_Table
* and @ref Evas_Smart_Object_Clipped.
*/
/**
* @def EVAS_SMART_CLASS_VERSION
* The version you have to put into the version field in the smart
* class struct
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_VERSION 4
/**
* @struct _Evas_Smart_Class
* a smart object class
* @ingroup Evas_Smart_Group
*/
struct _Evas_Smart_Class
{
const char *name; /**< the string name of the class */
int version;
void (*add) (Evas_Object *o);
void (*del) (Evas_Object *o);
void (*move) (Evas_Object *o, Evas_Coord x, Evas_Coord y);
void (*resize) (Evas_Object *o, Evas_Coord w, Evas_Coord h);
void (*show) (Evas_Object *o);
void (*hide) (Evas_Object *o);
void (*color_set) (Evas_Object *o, int r, int g, int b, int a);
void (*clip_set) (Evas_Object *o, Evas_Object *clip);
void (*clip_unset) (Evas_Object *o);
void (*calculate) (Evas_Object *o);
void (*member_add) (Evas_Object *o, Evas_Object *child);
void (*member_del) (Evas_Object *o, Evas_Object *child);
const Evas_Smart_Class *parent; /**< this class inherits from this parent */
const Evas_Smart_Cb_Description *callbacks; /**< callbacks at this level, NULL terminated */
void *interfaces; /**< to be used in a future near you */
const void *data;
};
/**
* @struct _Evas_Smart_Cb_Description
*
* Describes a callback used by a smart class
* evas_object_smart_callback_call(), particularly useful to explain
* to user and its code (ie: introspection) what the parameter @c
* event_info will contain.
*
* @ingroup Evas_Smart_Group
*/
struct _Evas_Smart_Cb_Description
{
const char *name; /**< callback name, ie: "changed" */
/**
* @brief Hint type of @c event_info parameter of Evas_Smart_Cb.
*
* The type string uses the pattern similar to
*
* http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures
*
* but extended to optionally include variable names within
* brackets preceding types. Example:
*
* @li Structure with two integers:
* @c "(ii)"
*
* @li Structure called 'x' with two integers named 'a' and 'b':
* @c "[x]([a]i[b]i)"
*
* @li Array of integers:
* @c "ai"
*
* @li Array called 'x' of struct with two integers:
* @c "[x]a(ii)"
*
* @note This type string is used as a hint and is @b not validated
* or enforced anyhow. Implementors should make the best use
* of it to help bindings, documentation and other users of
* introspection features.
*/
const char *type;
};
/**
* @def EVAS_SMART_CLASS_INIT_NULL
* Initializer to zero a whole Evas_Smart_Class structure.
*
* @see EVAS_SMART_CLASS_INIT_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
/**
* @def EVAS_SMART_CLASS_INIT_VERSION
* Initializer to zero a whole Evas_Smart_Class structure and set version.
*
* Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
* latest EVAS_SMART_CLASS_VERSION.
*
* @see EVAS_SMART_CLASS_INIT_NULL
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
/**
* @def EVAS_SMART_CLASS_INIT_NAME_VERSION
* Initializer to zero a whole Evas_Smart_Class structure and set name
* and version.
*
* Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
* latest EVAS_SMART_CLASS_VERSION and name to the specified value.
*
* It will keep a reference to name field as a "const char *", that is,
* name must be available while the structure is used (hint: static or global!)
* and will not be modified.
*
* @see EVAS_SMART_CLASS_INIT_NULL
* @see EVAS_SMART_CLASS_INIT_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_INIT_NAME_VERSION(name) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
/**
* @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
* Initializer to zero a whole Evas_Smart_Class structure and set name,
* version and parent class.
*
* Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
* latest EVAS_SMART_CLASS_VERSION, name to the specified value and
* parent class.
*
* It will keep a reference to name field as a "const char *", that is,
* name must be available while the structure is used (hint: static or global!)
* and will not be modified. Similarly, parent reference will be kept.
*
* @see EVAS_SMART_CLASS_INIT_NULL
* @see EVAS_SMART_CLASS_INIT_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}
/**
* @def EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS
* Initializer to zero a whole Evas_Smart_Class structure and set name,
* version, parent class and callbacks definition.
*
* Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to
* latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent
* class and callbacks at this level.
*
* It will keep a reference to name field as a "const char *", that is,
* name must be available while the structure is used (hint: static or global!)
* and will not be modified. Similarly, parent and callbacks reference
* will be kept.
*
* @see EVAS_SMART_CLASS_INIT_NULL
* @see EVAS_SMART_CLASS_INIT_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION
* @see EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT
* @ingroup Evas_Smart_Group
*/
#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}
/**
* @def EVAS_SMART_SUBCLASS_NEW
*
* Convenience macro to subclass a Smart Class.
*
* This macro saves some typing when writing a Smart Class derived from
* another one. In order to work, the user needs to provide some functions
* adhering to the following guidelines.
* - @"Unknown error"
is returned.
*
* Mostly evas_object_image_file_set() would be the function setting
* that error value afterwards, but also evas_object_image_load(),
* evas_object_image_save(), evas_object_image_data_get(),
* evas_object_image_data_convert(), evas_object_image_pixels_import()
* and evas_object_image_is_inside(). This function is meant to be
* used in conjunction with evas_object_image_load_error_get(), as in:
*
* Example code:
* @dontinclude evas-load-error-str.c
* @skip img1 =
* @until ecore_main_loop_begin(
*
* Here, being @c valid_path the path to a valid image and @c
* bogus_path a path to a file which does not exist, the two outputs
* of evas_load_error_str() would be (if no other errors occur):
* "No error on load"
and "File (or file path) does
* not exist"
, respectively. See the full @ref
* Example_Evas_Load_Error_Str "example".
*
* @ingroup Evas_Utils
*/
EAPI const char *evas_load_error_str (Evas_Load_Error error);
/* Evas utility routines for color space conversions */
/* hsv color space has h in the range 0.0 to 360.0, and s,v in the range 0.0 to 1.0 */
/* rgb color space has r,g,b in the range 0 to 255 */
/**
* Convert a given color from HSV to RGB format.
*
* @param h The Hue component of the color.
* @param s The Saturation component of the color.
* @param v The Value component of the color.
* @param r The Red component of the color.
* @param g The Green component of the color.
* @param b The Blue component of the color.
*
* This function converts a given color in HSV color format to RGB
* color format.
*
* @ingroup Evas_Utils
**/
EAPI void evas_color_hsv_to_rgb (float h, float s, float v, int *r, int *g, int *b);
/**
* Convert a given color from RGB to HSV format.
*
* @param r The Red component of the color.
* @param g The Green component of the color.
* @param b The Blue component of the color.
* @param h The Hue component of the color.
* @param s The Saturation component of the color.
* @param v The Value component of the color.
*
* This function converts a given color in RGB color format to HSV
* color format.
*
* @ingroup Evas_Utils
**/
EAPI void evas_color_rgb_to_hsv (int r, int g, int b, float *h, float *s, float *v);
/* argb color space has a,r,g,b in the range 0 to 255 */
/**
* Pre-multiplies a rgb triplet by an alpha factor.
*
* @param a The alpha factor.
* @param r The Red component of the color.
* @param g The Green component of the color.
* @param b The Blue component of the color.
*
* This function pre-multiplies a given rbg triplet by an alpha
* factor. Alpha factor is used to define transparency.
*
* @ingroup Evas_Utils
**/
EAPI void evas_color_argb_premul (int a, int *r, int *g, int *b);
/**
* Undo pre-multiplication of a rgb triplet by an alpha factor.
*
* @param a The alpha factor.
* @param r The Red component of the color.
* @param g The Green component of the color.
* @param b The Blue component of the color.
*
* This function undoes pre-multiplication a given rbg triplet by an
* alpha factor. Alpha factor is used to define transparency.
*
* @see evas_color_argb_premul().
*
* @ingroup Evas_Utils
**/
EAPI void evas_color_argb_unpremul (int a, int *r, int *g, int *b);
/**
* Pre-multiplies data by an alpha factor.
*
* @param data The data value.
* @param len The length value.
*
* This function pre-multiplies a given data by an alpha
* factor. Alpha factor is used to define transparency.
*
* @ingroup Evas_Utils
**/
EAPI void evas_data_argb_premul (unsigned int *data, unsigned int len);
/**
* Undo pre-multiplication data by an alpha factor.
*
* @param data The data value.
* @param len The length value.
*
* This function undoes pre-multiplication of a given data by an alpha
* factor. Alpha factor is used to define transparency.
*
* @ingroup Evas_Utils
**/
EAPI void evas_data_argb_unpremul (unsigned int *data, unsigned int len);
/* string and font handling */
/**
* Gets the next character in the string
*
* Given the UTF-8 string in @p str, and starting byte position in @p pos,
* this function will place in @p decoded the decoded code point at @p pos
* and return the byte index for the next character in the string.
*
* The only boundary check done is that @p pos must be >= 0. Other than that,
* no checks are performed, so passing an index value that's not within the
* length of the string will result in undefined behavior.
*
* @param str The UTF-8 string
* @param pos The byte index where to start
* @param decoded Address where to store the decoded code point. Optional.
*
* @return The byte index of the next character
*
* @ingroup Evas_Utils
*/
EAPI int evas_string_char_next_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
/**
* Gets the previous character in the string
*
* Given the UTF-8 string in @p str, and starting byte position in @p pos,
* this function will place in @p decoded the decoded code point at @p pos
* and return the byte index for the previous character in the string.
*
* The only boundary check done is that @p pos must be >= 1. Other than that,
* no checks are performed, so passing an index value that's not within the
* length of the string will result in undefined behavior.
*
* @param str The UTF-8 string
* @param pos The byte index where to start
* @param decoded Address where to store the decoded code point. Optional.
*
* @return The byte index of the previous character
*
* @ingroup Evas_Utils
*/
EAPI int evas_string_char_prev_get (const char *str, int pos, int *decoded) EINA_ARG_NONNULL(1);
/**
* Get the length in characters of the string.
* @param str The string to get the length of.
* @return The length in characters (not bytes)
* @ingroup Evas_Utils
*/
EAPI int evas_string_char_len_get (const char *str) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* @defgroup Evas_Keys Key Input Functions
*
* Functions which feed key events to the canvas.
*
* As explained in @ref intro_not_evas, Evas is not aware of
* input systems at all. Then, the user, if using it crudely
* (evas_new()), will have to feed it with input events, so that it
* can react somehow. If, however, the user creates a canvas by means
* of the Ecore_Evas wrapper, it will automatically bind the chosen
* display engine's input events to the canvas, for you.
*
* This group presents the functions dealing with the feeding of key
* events to the canvas. On most of them, one has to reference a given
* key by a name (keyname
argument). Those are
* platform dependent symbolic names for the keys. Sometimes
* you'll get the right keyname
by simply using an ASCII
* value of the key name, but it won't be like that always.
*
* Typical platforms are Linux frame buffer (Ecore_FB) and X server
* (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
* to your display engine's documentation when using evas through an
* Ecore helper wrapper when you need the keyname
s.
*
* @ingroup Evas_Canvas
*/
/**
* @addtogroup Evas_Keys
* @{
*/
/**
* Returns a handle to the list of modifier keys registered in the
* canvas @p e. This is required to check for which modifiers are set
* at a given time with the evas_key_modifier_is_set() function.
*
* @param e The pointer to the Evas canvas
*
* @see evas_key_modifier_add
* @see evas_key_modifier_del
* @see evas_key_modifier_on
* @see evas_key_modifier_off
* @see evas_key_modifier_is_set
*
* @return An ::Evas_Modifier handle to query Evas' keys subsystem
* with evas_key_modifier_is_set(), or @c NULL on error.
*/
EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Returns a handle to the list of lock keys registered in the canvas
* @p e. This is required to check for which locks are set at a given
* time with the evas_key_lock_is_set() function.
*
* @param e The pointer to the Evas canvas
*
* @see evas_key_lock_add
* @see evas_key_lock_del
* @see evas_key_lock_on
* @see evas_key_lock_off
* @see evas_key_lock_is_set
*
* @return An ::Evas_Lock handle to query Evas' keys subsystem with
* evas_key_lock_is_set(), or @c NULL on error.
*/
EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
/**
* Checks the state of a given modifier key, at the time of the
* call. If the modifier is set, such as shift being pressed, this
* function returns @c Eina_True.
*
* @param m The current modifiers set, as returned by
* evas_key_modifier_get().
* @param keyname The name of the modifier key to check status for.
*
* @return @c Eina_True if the modifier key named @p keyname is on, @c
* Eina_False otherwise.
*
* @see evas_key_modifier_add
* @see evas_key_modifier_del
* @see evas_key_modifier_get
* @see evas_key_modifier_on
* @see evas_key_modifier_off
*/
EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
/**
* Checks the state of a given lock key, at the time of the call. If
* the lock is set, such as caps lock, this function returns @c
* Eina_True.
*
* @param l The current locks set, as returned by evas_key_lock_get().
* @param keyname The name of the lock key to check status for.
*
* @return @c Eina_True if the @p keyname lock key is set, @c
* Eina_False otherwise.
*
* @see evas_key_lock_get
* @see evas_key_lock_add
* @see evas_key_lock_del
* @see evas_key_lock_on
* @see evas_key_lock_off
*/
EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
/**
* Adds the @p keyname key to the current list of modifier keys.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the modifier key to add to the list of
* Evas modifiers.
*
* Modifiers are keys like shift, alt and ctrl, i.e., keys which are
* meant to be pressed together with others, altering the behavior of
* the secondly pressed keys somehow. Evas is so that these keys can
* be user defined.
*
* This call allows custom modifiers to be added to the Evas system at
* run time. It is then possible to set and unset modifier keys
* programmatically for other parts of the program to check and act
* on. Programmers using Evas would check for modifier keys on key
* event callbacks using evas_key_modifier_is_set().
*
* @see evas_key_modifier_del
* @see evas_key_modifier_get
* @see evas_key_modifier_on
* @see evas_key_modifier_off
* @see evas_key_modifier_is_set
*
* @note If the programmer instantiates the canvas by means of the
* ecore_evas_new() family of helper functions, Ecore will take
* care of registering on it all standard modifiers: "Shift",
* "Control", "Alt", "Meta", "Hyper", "Super".
*/
EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Removes the @p keyname key from the current list of modifier keys
* on canvas @e.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the key to remove from the modifiers list.
*
* @see evas_key_modifier_add
* @see evas_key_modifier_get
* @see evas_key_modifier_on
* @see evas_key_modifier_off
* @see evas_key_modifier_is_set
*/
EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Adds the @p keyname key to the current list of lock keys.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the key to add to the locks list.
*
* Locks are keys like caps lock, num lock or scroll lock, i.e., keys
* which are meant to be pressed once -- toggling a binary state which
* is bound to it -- and thus altering the behavior of all
* subsequently pressed keys somehow, depending on its state. Evas is
* so that these keys can be defined by the user.
*
* This allows custom locks to be added to the evas system at run
* time. It is then possible to set and unset lock keys
* programmatically for other parts of the program to check and act
* on. Programmers using Evas would check for lock keys on key event
* callbacks using evas_key_lock_is_set().
*
* @see evas_key_lock_get
* @see evas_key_lock_del
* @see evas_key_lock_on
* @see evas_key_lock_off
* @see evas_key_lock_is_set
*
* @note If the programmer instantiates the canvas by means of the
* ecore_evas_new() family of helper functions, Ecore will take
* care of registering on it all standard lock keys: "Caps_Lock",
* "Num_Lock", "Scroll_Lock".
*/
EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Removes the @p keyname key from the current list of lock keys on
* canvas @e.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the key to remove from the locks list.
*
* @see evas_key_lock_get
* @see evas_key_lock_add
* @see evas_key_lock_on
* @see evas_key_lock_off
*/
EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Enables or turns on programmatically the modifier key with name @p
* keyname.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the modifier to enable.
*
* The effect will be as if the key was pressed for the whole time
* between this call and a matching evas_key_modifier_off().
*
* @see evas_key_modifier_add
* @see evas_key_modifier_get
* @see evas_key_modifier_off
* @see evas_key_modifier_is_set
*/
EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Disables or turns off programmatically the modifier key with name
* @p keyname.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the modifier to disable.
*
* @see evas_key_modifier_add
* @see evas_key_modifier_get
* @see evas_key_modifier_on
* @see evas_key_modifier_is_set
*/
EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Enables or turns on programmatically the lock key with name @p
* keyname.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the lock to enable.
*
* The effect will be as if the key was put on its active state after
* this call.
*
* @see evas_key_lock_get
* @see evas_key_lock_add
* @see evas_key_lock_del
* @see evas_key_lock_off
*/
EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Disables or turns off programmatically the lock key with name @p
* keyname.
*
* @param e The pointer to the Evas canvas
* @param keyname The name of the lock to disable.
*
* The effect will be as if the key was put on its inactive state
* after this call.
*
* @see evas_key_lock_get
* @see evas_key_lock_add
* @see evas_key_lock_del
* @see evas_key_lock_on
*/
EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
/**
* Creates a bit mask from the @p keyname modifier key.
* Values returned from different calls to it may be ORed together,
* naturally.
*
* @param e The canvas whom to query the bit mask from.
* @param keyname The name of the modifier key to create the mask for.
*
* @returns the bit mask or 0 if the @p keyname key wasn't registered as a
* modifier for canvas @p e.
*
* This function is meant to be using in conjunction with
* evas_object_key_grab()/evas_object_key_ungrab(). Go check their
* documentation for more information.
*
* @see evas_key_modifier_add
* @see evas_key_modifier_get
* @see evas_key_modifier_on
* @see evas_key_modifier_off
* @see evas_key_modifier_is_set
* @see evas_object_key_grab
* @see evas_object_key_ungrab
*/
EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
/**
* Requests @p keyname key events be directed to @p obj.
*
* Key grabs allow an object to receive key events for specific key
* strokes even if another object has focus. If the grab is
* non-exclusive then all objects that have grabs on the key will get
* the event, however if the grab is exclusive, no other object can
* get a grab on the key and only that object will get the event.
*
* @p keyname is a platform dependent symbolic name for the key
* pressed. It is sometimes possible to convert the string to an
* ASCII value of the key, but not always for example the enter key
* may be returned as the string 'Enter'.
*
* Typical platforms are Linux frame buffer (Ecore_FB) and X server
* (Ecore_X) when using Evas with Ecore and Ecore_Evas.
*
* For a list of keynames for the Linux frame buffer, please refer to
* the Ecore_FB documentation.
*
* @p modifiers and @p not_modifiers are bit masks of all the
* modifiers that are required and not required respectively for the
* new grab. Modifiers can be things such as shift and ctrl as well
* as user defigned types via evas_key_modifier_add.
*
* @see evas_object_key_ungrab
* @see evas_object_focus_set
* @see evas_object_focus_get
* @see evas_focus_get
* @see evas_key_modifier_add
*
* @param obj the object to direct @p keyname events to.
* @param keyname the key to request events for.
* @param modifiers a mask of modifiers that should be present to
* trigger the event.
* @param not_modifiers a mask of modifiers that should not be present
* to trigger the event.
* @param exclusive request that the @p obj is the only object
* receiving the @p keyname events.
* @return Boolean indicating whether the grab succeeded
*/
EAPI Eina_Bool evas_object_key_grab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
/**
* Request that the grab on @p obj be removed.
*
* Removes the grab on @p obj if @p keyname, @p modifiers, and @p not_modifiers
* match.
*
* @see evas_object_key_grab
* @see evas_object_focus_set
* @see evas_object_focus_get
* @see evas_focus_get
*
* @param obj the object that has an existing grab.
* @param keyname the key the grab is for.
* @param modifiers a mask of modifiers that should be present to
* trigger the event.
* @param not_modifiers a mask of modifiers that should not be present
* to trigger the event.
*/
EAPI void evas_object_key_ungrab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) EINA_ARG_NONNULL(1, 2);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif