You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

8492 lines
300 KiB

#ifndef _EVAS_H
# error You shall not include this header directly
#endif
/**
* @ingroup Evas_Canvas
*
* @{
*/
/**
* Creates a new empty evas.
*
* Note that before you can use the evas, you will to at a minimum:
* @li Set its render method with @ref evas_output_method_set .
* @li Set its viewport size with @ref evas_output_viewport_set .
* @li Set its size of the canvas with @ref evas_output_size_set .
* @li Ensure that the render engine is given the correct settings
* with @ref evas_engine_info_set .
*
* This function should only fail if the memory allocation fails
*
* @note this function is very low level. Instead of using it
* directly, consider using the high level functions in
* @ref Ecore_Evas_Group such as @c ecore_evas_new(). See
* @ref Ecore.
*
* @attention it is recommended that one calls evas_init() before
* creating new canvas.
*
* @return A new uninitialised Evas canvas on success. Otherwise, @c NULL.
* @ingroup Evas_Canvas
*/
EAPI Evas *evas_new(void) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
/**
* Frees the given evas and any objects created on it.
*
* Any objects with 'free' callbacks will have those callbacks called
* in this function.
*
* @param e The given evas.
*
* @ingroup Evas_Canvas
*/
EAPI void evas_free(Evas *e) EINA_ARG_NONNULL(1);
typedef struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */
{
int magic; /**< Magic number */
} Evas_Engine_Info;
/**
* @brief Applies the engine settings for the given evas from the given
* @c Evas_Engine_Info structure.
*
* To get the Evas_Engine_Info structure to use, call
* @ref evas_engine_info_get. Do not try to obtain a pointer to an
* @c Evas_Engine_Info structure in any other way.
*
* You will need to call this function at least once before you can create
* objects on an evas or render that evas. Some engines allow their settings to
* be changed more than once.
*
* Once called, the @c info pointer should be considered invalid.
*
* @param[in] info The pointer to the engine info to use.
*
* @return @c true if no error occurred, @c false otherwise.
*
* @ingroup Evas_Canvas
*/
EAPI Eina_Bool evas_engine_info_set(Evas *obj, Evas_Engine_Info *info);
/**
* @brief Retrieves the current render engine info struct from the given evas.
*
* The returned structure is publicly modifiable. The contents are valid until
* either @ref evas_engine_info_set or @ref evas_render are called.
*
* This structure does not need to be freed by the caller.
*
* @return The pointer to the engine info to use.
*
* @ingroup Evas_Canvas
*/
EAPI Evas_Engine_Info *evas_engine_info_get(const Evas *obj);
/**
* @brief Get the maximum image size evas can possibly handle.
*
* This function returns the largest image or surface size that evas can handle
* in pixels, and if there is one, returns @c true. It returns @c false if no
* extra constraint on maximum image size exists. You still should check the
* return values of @c maxw and @c maxh as there may still be a limit, just a
* much higher one.
*
* @param[in] obj The object.
* @param[out] max The maximum image size (in pixels).
*
* @return @c true on success, @c false otherwise
*/
EAPI Eina_Bool evas_image_max_size_get(Eo *eo_e, int *w, int *h);
#include "canvas/evas_canvas_eo.legacy.h"
/**
* @}
*/
/** @addtogroup Evas_Keys
* @{
*/
/**
* An opaque type containing information on which lock keys are registered in
* an Evas canvas.
*/
typedef struct _Evas_Lock Evas_Lock;
/**
* An opaque type containing information on which modifier keys are registered
* in an Evas canvas.
*/
typedef struct _Evas_Modifier Evas_Modifier;
/**
* A bitmask of modifier keys.
*
* See evas_key_modifier_mask_get() for the keyname to bit conversion.
*/
typedef unsigned long long Evas_Modifier_Mask;
/**
* @}
*/
/**
* @addtogroup Evas_Canvas_Events
*
* @{
*/
typedef struct _Evas_Event_Mouse_Down Evas_Event_Mouse_Down; /**< Event structure for #EVAS_CALLBACK_MOUSE_DOWN event callbacks */
typedef struct _Evas_Event_Mouse_Up Evas_Event_Mouse_Up; /**< Event structure for #EVAS_CALLBACK_MOUSE_UP event callbacks */
typedef struct _Evas_Event_Mouse_In Evas_Event_Mouse_In; /**< Event structure for #EVAS_CALLBACK_MOUSE_IN event callbacks */
typedef struct _Evas_Event_Mouse_Out Evas_Event_Mouse_Out; /**< Event structure for #EVAS_CALLBACK_MOUSE_OUT event callbacks */
typedef struct _Evas_Event_Mouse_Move Evas_Event_Mouse_Move; /**< Event structure for #EVAS_CALLBACK_MOUSE_MOVE event callbacks */
typedef struct _Evas_Event_Mouse_Wheel Evas_Event_Mouse_Wheel; /**< Event structure for #EVAS_CALLBACK_MOUSE_WHEEL event callbacks */
typedef struct _Evas_Event_Multi_Down Evas_Event_Multi_Down; /**< Event structure for #EVAS_CALLBACK_MULTI_DOWN event callbacks */
typedef struct _Evas_Event_Multi_Up Evas_Event_Multi_Up; /**< Event structure for #EVAS_CALLBACK_MULTI_UP event callbacks */
typedef struct _Evas_Event_Multi_Move Evas_Event_Multi_Move; /**< Event structure for #EVAS_CALLBACK_MULTI_MOVE event callbacks */
typedef struct _Evas_Event_Key_Down Evas_Event_Key_Down; /**< Event structure for #EVAS_CALLBACK_KEY_DOWN event callbacks */
typedef struct _Evas_Event_Key_Up Evas_Event_Key_Up; /**< Event structure for #EVAS_CALLBACK_KEY_UP event callbacks */
typedef struct _Evas_Event_Hold Evas_Event_Hold; /**< Event structure for #EVAS_CALLBACK_HOLD event callbacks */
typedef struct _Evas_Event_Axis_Update Evas_Event_Axis_Update; /**< Event structure for #EVAS_CALLBACK_AXIS_UPDATE event callbacks @since 1.13 */
struct _Evas_Event_Mouse_Down /** Mouse button press event */
{
int button; /**< Mouse button number that went down (1 - 32) */
Evas_Point output; /**< The X/Y location of the cursor */
Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
Evas_Button_Flags flags; /**< button flags set during the event */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
Evas_Object *event_src; /**< The Evas Object that actually triggered the event, used in cases of proxy event propagation */
};
struct _Evas_Event_Mouse_Up /** Mouse button release event */
{
int button; /**< Mouse button number that was raised (1 - 32) */
Evas_Point output; /**< The X/Y location of the cursor */
Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
Evas_Button_Flags flags; /**< button flags set during the event */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
Evas_Object *event_src; /**< The Evas Object that actually triggered the event, used in cases of proxy event propagation */
};
struct _Evas_Event_Mouse_In /** Mouse enter event */
{
int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
Evas_Point output; /**< The X/Y location of the cursor */
Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
Evas_Object *event_src; /**< The Evas Object that actually triggered the event, used in cases of proxy event propagation */
};
struct _Evas_Event_Mouse_Out /** Mouse leave event */
{
int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
Evas_Point output; /**< The X/Y location of the cursor */
Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
Evas_Object *event_src; /**< The Evas Object that actually triggered the event, used in cases of proxy event propagation */
};
struct _Evas_Event_Mouse_Move /** Mouse move event */
{
int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */
Evas_Position cur; /**< Current mouse position */
Evas_Position prev; /**< Previous mouse position */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
Evas_Object *event_src; /**< The Evas Object that actually triggered the event, used in cases of proxy event propagation */
};
struct _Evas_Event_Mouse_Wheel /** Wheel event */
{
int direction; /**< Axis of screen wheel - 0 = default up/down wheel, 1 = horizontal left/right wheel */
int z; /**< The step for the wheel movement relative to the direction above...,-2,-1 = down, 1,2,... = up */
Evas_Point output; /**< The X/Y location of the cursor */
Evas_Coord_Point canvas; /**< The X/Y location of the cursor */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
};
struct _Evas_Event_Multi_Down /** Multi button press event */
{
int device; /**< Multi device number that went down (1 or more for extra touches) */
double radius, radius_x, radius_y;
double pressure, angle;
Evas_Point output;
Evas_Coord_Precision_Point canvas;
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
Evas_Button_Flags flags; /**< button flags set during the event */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
};
struct _Evas_Event_Multi_Up /** Multi button release event */
{
int device; /**< Multi device number that went up (1 or more for extra touches) */
double radius, radius_x, radius_y;
double pressure, angle;
Evas_Point output;
Evas_Coord_Precision_Point canvas;
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
Evas_Button_Flags flags; /**< button flags set during the event */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
};
struct _Evas_Event_Multi_Move /** Multi button down event */
{
int device; /**< Multi device number that moved (1 or more for extra touches) */
double radius, radius_x, radius_y;
double pressure, angle;
Evas_Precision_Position cur;
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
};
struct _Evas_Event_Key_Down /** Key press event */
{
char *keyname; /**< the name string of the key pressed */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
const char *key; /**< The logical key : (eg shift+1 == exclamation) */
const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
};
struct _Evas_Event_Key_Up /** Key release event */
{
char *keyname; /**< the name string of the key released */
void *data;
Evas_Modifier *modifiers; /**< modifier keys pressed during the event */
Evas_Lock *locks;
const char *key; /**< The logical key : (eg shift+1 == exclamation) */
const char *string; /**< A UTF8 string if this keystroke has produced a visible string to be ADDED */
const char *compose; /**< A UTF8 string if this keystroke has modified a string in the middle of being composed - this string replaces the previous one */
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
unsigned int keycode; /**< Key scan code numeric value @since 1.10 */
};
struct _Evas_Event_Hold /** Hold change event */
{
int hold; /**< The hold flag */
void *data;
unsigned int timestamp;
Evas_Event_Flags event_flags;
Evas_Device *dev;
};
typedef enum _Evas_Axis_Label
{
EVAS_AXIS_LABEL_UNKNOWN, /**< Axis containing unknown (or not yet representable) data. Range: Unbounded. Unit: Undefined. @since 1.13 */
EVAS_AXIS_LABEL_X, /**< Position along physical X axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
EVAS_AXIS_LABEL_Y, /**< Position along physical Y axis; not window relative. Range: Unbounded. Unit: Undefined. @since 1.13 */
EVAS_AXIS_LABEL_PRESSURE, /**< Force applied to tool tip. Range: [0.0, 1.0]. Unit: Unitless. @since 1.13 */
EVAS_AXIS_LABEL_DISTANCE, /**< Relative distance along physical Z axis. Range: [0.0, 1.0]. Unit: Unitless @since 1.13 */
EVAS_AXIS_LABEL_AZIMUTH, /**< Angle of tool about the Z axis from positive X axis. Range: [-PI, PI]. Unit: Radians. @since 1.13 */
EVAS_AXIS_LABEL_TILT, /**< Angle of tool about plane of sensor from positive Z axis. Range: [0.0, PI]. Unit: Radians. @since 1.13 */
EVAS_AXIS_LABEL_TWIST, /**< Rotation of tool about its major axis from its "natural" position. Range: [-PI, PI] Unit: Radians. @since 1.13 */
EVAS_AXIS_LABEL_TOUCH_WIDTH_MAJOR, /**< Length of contact ellipse along AZIMUTH. Range: Unbounded: Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
EVAS_AXIS_LABEL_TOUCH_WIDTH_MINOR, /**< Length of contact ellipse perpendicular to AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
EVAS_AXIS_LABEL_TOOL_WIDTH_MAJOR, /**< Length of tool ellipse along AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
EVAS_AXIS_LABEL_TOOL_WIDTH_MINOR, /**< Length of tool ellipse perpendicular to AZIMUTH. Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}. @since 1.13 */
EVAS_AXIS_LABEL_WINDOW_X, /**< X coordinate mapped to the window. @since 1.19 */
EVAS_AXIS_LABEL_WINDOW_Y, /**< Y coordinate mapped to the window. @since 1.19 */
EVAS_AXIS_LABEL_NORMAL_X, /**< X normalized to the [0, 1] range. @since 1.19 */
EVAS_AXIS_LABEL_NORMAL_Y, /**< Y normalized to the [0, 1] range. @since 1.19 */
} Evas_Axis_Label; /**< Types of recognized device axes @since 1.13 */
typedef struct _Evas_Axis
{
Evas_Axis_Label label;
double value;
} Evas_Axis;
struct _Evas_Event_Axis_Update
{
void *data;
unsigned int timestamp;
int device;
int toolid;
int naxis;
Evas_Axis *axis;
Evas_Device *dev;
};
/**
* Add (register) a callback function to a given canvas event.
*
* @param e Canvas to attach a callback to
* @param type The type of event that will trigger the callback
* @param func The (callback) 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 the canvas @p e when the
* event of type @p type occurs on it. The function pointer is @p
* func.
*
* In the event of a memory allocation error during the addition of
* the callback to the canvas, evas_alloc_error() should be used to
* determine the nature of the error, if any, and the program should
* sensibly try and recover.
*
* A callback function must have the ::Evas_Event_Cb prototype
* definition. The first parameter (@p data) in this definition will
* have the same value passed to evas_event_callback_add() as the @p
* data parameter, at runtime. The second parameter @p e is the canvas
* pointer on which the event occurred. The third 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. This is so because some events don't carry extra
* context with them, but others do.
*
* The event type @p type to trigger the function may be one of
* #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST,
* #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT,
* #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and
* #EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of
* event that will trigger the callback to be called. Only the last
* two of the event types listed here provide useful event information
* data -- a pointer to the recently focused Evas object. For the
* others the @p event_info pointer is going to be @c NULL.
*
* Example:
* @dontinclude evas-events.c
* @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE
* @until two canvas event callbacks
*
* Looking to the callbacks registered above,
* @dontinclude evas-events.c
* @skip called when our rectangle gets focus
* @until let's have our events back
*
* we see that the canvas flushes its rendering pipeline
* (#EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the @c _resize_cb
* routine takes place: it has to redraw that image at a different
* size. Also, the callback on an object being focused comes just
* after we focus it explicitly, on code.
*
* See the full @ref Example_Evas_Events "example".
*
* @note Be careful not to add the same callback multiple times, if
* that's not what you want, because Evas won't check if a callback
* existed before exactly as the one being registered (and thus, call
* it more than once on the event, in this case). This would make
* sense if you passed different functions and/or callback data, only.
*/
EAPI void evas_event_callback_add(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
/**
* Add (register) a callback function to a given canvas event with a
* non-default priority set. Except for the priority field, it's exactly the
* same as @ref evas_event_callback_add
*
* @param e Canvas to attach a callback to
* @param type The type of event that will trigger the callback
* @param priority The priority of the callback, lower values called first.
* @param func The (callback) function to be called when the event is
* triggered
* @param data The data pointer to be passed to @p func
*
* @see evas_event_callback_add
* @since 1.1
*/
EAPI void evas_event_callback_priority_add(Evas *e, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
/**
* Delete a callback function from the canvas.
*
* @param e Canvas 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
* canvas @p e 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_event_callback_add() when the callback was added to the
* canvas. If not successful @c NULL will be returned.
*
* Example:
* @code
* extern Evas *e;
* void *my_data;
* void focus_in_callback(void *data, Evas *e, void *event_info);
*
* my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
* @endcode
*/
EAPI void *evas_event_callback_del(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
/**
* Delete (unregister) a callback function registered to a given
* canvas event.
*
* @param e Canvas to remove an event 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 <b>the first</b> added callback from the
* canvas @p e matching the event type @p type, the registered
* function pointer @p func and the callback data pointer @p data. If
* the removal is successful it will also return the data pointer that
* was passed to evas_event_callback_add() (that will be the same as
* the parameter) when the callback(s) was(were) added to the
* canvas. If not successful @c NULL will be returned. A common use
* would be to remove an exact match of a callback.
*
* Example:
* @dontinclude evas-events.c
* @skip evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
* @until _object_focus_in_cb, NULL);
*
* See the full @ref Example_Evas_Events "example".
*
* @note For deletion of canvas events callbacks filtering by just
* type and function pointer, user evas_event_callback_del().
*/
EAPI void *evas_event_callback_del_full(Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3);
/**
* Push a callback on the post-event callback stack
*
* @param e Canvas to push the callback on
* @param func The function that to be called when the stack is unwound
* @param data The data pointer to be passed to the callback
*
* Evas has a stack of callbacks that get called after all the callbacks for
* an event have triggered (all the objects it triggers on and all the callbacks
* in each object triggered). When all these have been called, the stack is
* unwound from most recently to least recently pushed item and removed from the
* stack calling the callback set for it.
*
* This is intended for doing reverse logic-like processing, example - when a
* child object that happens to get the event later is meant to be able to
* "steal" functions from a parent and thus on unwind of this stack have its
* function called first, thus being able to set flags, or return 0 from the
* post-callback that stops all other post-callbacks in the current stack from
* being called (thus basically allowing a child to take control, if the event
* callback prepares information ready for taking action, but the post callback
* actually does the action).
*
* This function should only be called from inside an evas input event
* callback. The event_info data may be kept up until @p func is called, in
* order to check the state of the "on-hold" flag for instance. Do not modify
* the canvas or otherwise trigger or feed a events to the canvas from inside
* @p func. Use jobs to safely modify the canvas.
*
* @warning Only use this function if you know exactly what you are doing!
*
*/
EAPI void evas_post_event_callback_push(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
/**
* Remove a callback from the post-event callback stack
*
* @param e Canvas to push the callback on
* @param func The function that to be called when the stack is unwound
*
* This removes a callback from the stack added with
* evas_post_event_callback_push(). The first instance of the function in
* the callback stack is removed from being executed when the stack is
* unwound. Further instances may still be run on unwind.
*/
EAPI void evas_post_event_callback_remove(Evas *e, Evas_Object_Event_Post_Cb func);
/**
* Remove a callback from the post-event callback stack
*
* @param e Canvas to push the callback on
* @param func The function that to be called when the stack is unwound
* @param data The data pointer to be passed to the callback
*
* This removes a callback from the stack added with
* evas_post_event_callback_push(). The first instance of the function and data
* in the callback stack is removed from being executed when the stack is
* unwound. Further instances may still be run on unwind.
*/
EAPI void evas_post_event_callback_remove_full(Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
/**
* @}
*/
/**
* @ingroup Evas_Event_Feeding_Group
*
* @{
*/
/**
* Freeze all input events processing.
*
* @param e The canvas to freeze input events processing on.
*
* This function will indicate to Evas that the canvas @p e is to have
* all input event processing frozen until a matching
* evas_event_thaw() function is called on the same canvas. All events
* of this kind during the freeze will get @b discarded. Every freeze
* call must be matched by a thaw call in order to completely thaw out
* a canvas (i.e. these calls may be nested). The most common use is
* when you don't want the user to interact with your user interface
* when you're populating a view or changing the layout.
*
* Example:
* @dontinclude evas-events.c
* @skip freeze input for 3 seconds
* @until }
* @dontinclude evas-events.c
* @skip let's have our events back
* @until }
*
* See the full @ref Example_Evas_Events "example".
*
* If you run that example, you'll see the canvas ignoring all input
* events for 3 seconds, when the "f" key is pressed. In a more
* realistic code we would be freezing while a toolkit or Edje was
* doing some UI changes, thawing it back afterwards.
*/
EAPI void evas_event_freeze(Evas *e) EINA_ARG_NONNULL(1);
/**
* Thaw a canvas out after freezing (for input events).
*
* @param e The canvas to thaw out.
*
* This will thaw out a canvas after a matching evas_event_freeze()
* call. If this call completely thaws out a canvas, i.e., there's no
* other unbalanced call to evas_event_freeze(), events will start to
* be processed again, but any "missed" events will @b not be
* evaluated.
*
* See evas_event_freeze() for an example.
*/
EAPI void evas_event_thaw(Evas *e) EINA_ARG_NONNULL(1);
/**
* Return the freeze count on input events of a given canvas.
*
* @param e The canvas to fetch the freeze count from.
*
* This returns the number of times the canvas has been told to freeze
* input events. It is possible to call evas_event_freeze() multiple
* times, and these must be matched by evas_event_thaw() calls. This
* call allows the program to discover just how many times things have
* been frozen in case it may want to break out of a deep freeze state
* where the count is high.
*
* Example:
* @code
* extern Evas *evas;
*
* while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
* @endcode
*
*/
EAPI int evas_event_freeze_get(const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* After thaw of a canvas, re-evaluate the state of objects and call callbacks
*
* @param e The canvas to evaluate after a thaw
*
* This is normally called after evas_event_thaw() to re-evaluate mouse
* containment and other states and thus also call callbacks for mouse in and
* out on new objects if the state change demands it.
*/
EAPI void evas_event_thaw_eval(Evas *e) EINA_ARG_NONNULL(1);
/**
* @brief Mouse move event feed.
*
* This function will set some evas properties that are necessary when the mouse
* is moved from its last position. It prepares information to be treated by
* the callback function.
*
* @param[in] y The vertical position of the mouse pointer.
* @param[in] timestamp The timestamp of the mouse up event.
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_move(Evas *obj, int x, int y, unsigned int timestamp, const void *data);
/**
* @brief Mouse move event feed from input.
*
* Similar to the @ref evas_event_feed_mouse_move, this function will inform
* Evas about mouse move events which were received by the input system,
* relative to the 0,0 of the window, not to the canvas 0,0. It will take care
* of doing any special transformation like adding the framespace offset to the
* mouse event.
*
* @param[in] y The vertical position of the mouse pointer relative to the 0,0
* of the window/surface.
* @param[in] timestamp The timestamp of the mouse move event.
* @param[in] data The data for canvas.
*
* @since 1.8
*/
EAPI void evas_event_input_mouse_move(Evas *obj, int x, int y, unsigned int timestamp, const void *data);
/**
* @brief Mouse up event feed.
*
* This function will set some evas properties that are necessary when the mouse
* button is released. It prepares information to be treated by the callback
* function.
*
* @param[in] flags Evas button flags.
* @param[in] timestamp The timestamp of the mouse up event.
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_up(Evas *obj, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
/**
* @brief Mouse down event feed.
*
* This function will set some evas properties that are necessary when the mouse
* button is pressed. It prepares information to be treated by the callback
* function.
*
* @param[in] flags Evas button flags.
* @param[in] timestamp The timestamp of the mouse up event.
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_down(Evas *obj, int b, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
/**
* @brief Mouse wheel event feed.
*
* This function will set some evas properties that are necessary when the mouse
* wheel is scrolled up or down. It prepares information to be treated by the
* callback function.
*
* @param[in] z How much mouse wheel was scrolled up or down.
* @param[in] timestamp The timestamp of the mouse up event.
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_wheel(Evas *obj, int direction, int z, unsigned int timestamp, const void *data);
/**
* @brief Mouse in event feed.
*
* This function will set some evas properties that are necessary when the mouse
* in event happens. It prepares information to be treated by the callback
* function.
*
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_in(Evas *obj, unsigned int timestamp, const void *data);
/**
* @brief Mouse out event feed.
*
* This function will set some evas properties that are necessary when the mouse
* out event happens. It prepares information to be treated by the callback
* function.
*
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_out(Evas *obj, unsigned int timestamp, const void *data);
/**
* @brief Mouse cancel event feed.
*
* This function will call generate a mouse up event.
*
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_mouse_cancel(Evas *obj, unsigned int timestamp, const void *data);
/* multi touch events - no doc */
EAPI void evas_event_input_multi_down(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
EAPI void evas_event_input_multi_move(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, unsigned int timestamp, const void *data);
EAPI void evas_event_input_multi_up(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
EAPI void evas_event_feed_multi_down(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
EAPI void evas_event_feed_multi_move(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, unsigned int timestamp, const void *data);
EAPI void evas_event_feed_multi_up(Evas *obj, int d, int x, int y, double rad, double radx, double rady, double pres, double ang, double fx, double fy, Evas_Button_Flags flags, unsigned int timestamp, const void *data);
/**
* @brief Key down event feed.
*
* This function will set some evas properties that are necessary when a key is
* pressed. It prepares information to be treated by the callback function.
*
* @param[in] key The key pressed.
* @param[in] string A string.
* @param[in] compose The compose string.
* @param[in] timestamp Timestamp of the mouse up event.
* @param[in] data Data for canvas.
*/
EAPI void evas_event_feed_key_down(Evas *obj, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data);
/**
* @brief Key up event feed.
*
* This function will set some evas properties that are necessary when a key is
* released. It prepares information to be treated by the callback function.
*
* @param[in] key The key released.
* @param[in] string A string.
* @param[in] compose Compose.
* @param[in] timestamp Timestamp of the mouse up event.
* @param[in] data Data for canvas.
*/
EAPI void evas_event_feed_key_up(Evas *obj, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data);
/**
* @brief Key down event feed with keycode.
*
* This function will set some evas properties that are necessary when a key is
* pressed. It prepares information to be treated by the callback function.
*
* @param[in] key The key released.
* @param[in] string A string.
* @param[in] compose Compose.
* @param[in] timestamp Timestamp of the mouse up event.
* @param[in] data Data for canvas.
* @param[in] keycode Key scan code numeric value for canvas.
*
* @since 1.10
*/
EAPI void evas_event_feed_key_down_with_keycode(Evas *obj, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data, unsigned int keycode);
/**
* @brief Key up event feed with keycode.
*
* This function will set some evas properties that are necessary when a key is
* released. It prepares information to be treated by the callback function.
*
* @param[in] key The key released.
* @param[in] string A string.
* @param[in] compose Compose.
* @param[in] timestamp Timestamp of the mouse up event.
* @param[in] data Data for canvas.
* @param[in] keycode Key scan code numeric value for canvas.
*
* @since 1.10
*/
EAPI void evas_event_feed_key_up_with_keycode(Evas *obj, const char *keyname, const char *key, const char *string, const char *compose, unsigned int timestamp, const void *data, unsigned int keycode);
/**
* @brief Input device axis update event feed.
*
* This function will set some evas properties that are necessary when an e.g.
* stylus axis is updated. It prepares information to be treated by the
* callback function.
*
* @param[in] device System-provided device identifier.
* @param[in] toolid Type of tool currently being used.
* @param[in] naxes Number of elements in the \p axis array.
* @param[in] axis Array containing the current value of all updated axes.
* @param[in] data Data for canvas.
*
* @since 1.13
*/
EAPI void evas_event_feed_axis_update(Evas *obj, unsigned int timestamp, int device, int toolid, int naxes, const Evas_Axis *axis, const void *data);
/**
* @brief Hold event feed.
*
* This function makes the object to stop sending events.
*
* @param[in] timestamp The timestamp of the mouse up event.
* @param[in] data The data for canvas.
*/
EAPI void evas_event_feed_hold(Evas *obj, int hold, unsigned int timestamp, const void *data);
/**
* @brief Re feed event.
*
* This function re-feeds the event pointed by event_copy.
*
* This function call evas_event_feed_* functions, so it can cause havoc if not
* used wisely. Please use it responsibly.
*
* @param[in] event_type Event type.
*/
EAPI void evas_event_refeed_event(Evas *obj, void *event_copy, Evas_Callback_Type event_type);
/**
* @}
*/
/**
* @addtogroup Evas_Keys
* @{
*/
/**
* @brief Returns a handle to the list of modifier keys registered in the
* canvas @c e.
*
* This is required to check for which modifiers are set at a given time with
* the @ref evas_key_modifier_is_set function.
*
* See also @ref evas_key_modifier_add, @ref evas_key_modifier_del,
* @ref evas_key_modifier_on, @ref evas_key_modifier_off,
* @ref evas_seat_key_modifier_on, @ref evas_seat_key_modifier_off.
*
* @return An Evas_Modifier handle to query Evas' keys subsystem with @ref
* evas_key_modifier_is_set or @ref evas_seat_key_modifier_is_set, or @c null
* on error.
*
* @ingroup Evas_Canvas
*/
EAPI const Evas_Modifier *evas_key_modifier_get(const Evas *obj) EINA_WARN_UNUSED_RESULT;
/**
* @brief Creates a bit mask from the @c keyname modifier key. Values returned
* from different calls to it may be ORed together, naturally.
*
* This function is meant to be using in conjunction with @ref
* evas_object_key_grab/\@ref evas_object_key_ungrab. Go check their
* documentation for more information.
*
* See also @ref evas_key_modifier_add, @ref evas_key_modifier_get,
* @ref evas_key_modifier_on, @ref evas_key_modifier_off,
* @ref evas_seat_key_modifier_on, @ref evas_seat_key_modifier_off, @ref
* evas_key_modifier_is_set, @ref evas_seat_key_modifier_is_set..
*
* @param[in] keyname The name of the modifier key to create the mask for.
*
* @return The bit mask or 0 if the @c keyname key wasn't registered as a
* modifier for canvas @c e.
*
* @ingroup Evas_Canvas
*/
EAPI Evas_Modifier_Mask evas_key_modifier_mask_get(const Evas *evas, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2);
/**
* Checks the state of a given modifier of the default seat, 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
* @see evas_seat_key_modifier_is_set
*/
EAPI Eina_Bool evas_key_modifier_is_set(const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
/**
* Checks the state of a given modifier key of a given seat, 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.
* @param seat The seat to check if the lock is set. Use @c NULL for the default seat.
*
* @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
* @see evas_seat_key_modifier_on
* @see evas_seat_key_modifier_off
* @see evas_key_modifier_is_set
* @since 1.19
*/
EAPI Eina_Bool evas_seat_key_modifier_is_set(const Evas_Modifier *m, const char *keyname, const Evas_Device *seat) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
/**
* Checks the state of a given lock key of the default seat, 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
* @see evas_seat_key_lock_on
* @see evas_seat_key_lock_off
* @see evas_seat_key_lock_is_set
*/
EAPI Eina_Bool evas_key_lock_is_set(const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
/**
* Checks the state of a given lock key of a given seat, 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.
* @param seat The seat to check if the lock is set. Use @c NULL for the default seat.
*
* @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
* @see evas_key_lock_is_set
* @since 1.19
*/
EAPI Eina_Bool evas_seat_key_lock_is_set(const Evas_Lock *l, const char *keyname, const Evas_Device *seat) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2);
/**
* @brief Returns a handle to the list of lock keys registered in the canvas
* @c e.
*
* This is required to check for which locks are set at a given time with the
* @ref evas_key_lock_is_set function.
*
* @return An Evas_Lock handle to query Evas' keys subsystem with @ref
* evas_key_lock_is_set or @ref evas_seat_key_lock_is_set, or @c null on error.
*
* @ingroup Evas_Canvas
*/
EAPI const Evas_Lock *evas_key_lock_get(const Evas *obj) EINA_WARN_UNUSED_RESULT;
/**
* @}
*/
/**
* @brief Returns whether the mouse pointer is logically inside the canvas.
*
* @param[in] obj The object.
* @param[in] dev The pointer device.
*
* @return @c true if the pointer is inside, @c false otherwise.
*
* @since 1.19
*
* @ingroup Evas_Canvas
*/
EAPI Eina_Bool evas_pointer_inside_by_device_get(const Evas *obj, Efl_Input_Device *dev);
/**
* @brief Returns whether the default mouse pointer is logically inside the
* canvas.
*
* When this function is called it will return a value of either @c false or
* @c true, depending on if event_feed_mouse_in or event_feed_mouse_out have
* been called to feed in a mouse enter event into the canvas.
*
* A return value of @c true indicates the mouse is logically inside the
* canvas, and @c false implies it is logically outside the canvas.
*
* A canvas begins with the mouse being assumed outside ($false).
*
* If @c e is not a valid canvas, the return value is undefined.
*
* @param[in] obj The object.
*
* @return @c true if the mouse pointer is inside the canvas, @c false
* otherwise
*
* @ingroup Evas_Canvas
*/
EAPI Eina_Bool evas_pointer_inside_get(const Evas *obj) EINA_WARN_UNUSED_RESULT;
/**
* @defgroup Evas_Touch_Point_List Touch Point List Functions
*
* Functions to get information of touched points in the Evas.
*
* Evas maintains list of touched points on the canvas. Each point has
* its co-ordinates, id and state. You can get the number of touched
* points and information of each point using evas_touch_point_list
* functions.
*
* @ingroup Evas_Canvas
*
* @{
*/
/**
* State of Evas_Coord_Touch_Point
*/
typedef enum
{
EVAS_TOUCH_POINT_DOWN = 0, /**< Touch point is pressed down */
EVAS_TOUCH_POINT_UP, /**< Touch point is released */
EVAS_TOUCH_POINT_MOVE, /**< Touch point is moved */
EVAS_TOUCH_POINT_STILL, /**< Touch point is not moved after pressed */
EVAS_TOUCH_POINT_CANCEL /**< Touch point is cancelled */
} Evas_Touch_Point_State;
/**
* @brief Get the number of touched point in the evas.
*
* New touched point is added to the list whenever touching the evas and point
* is removed whenever removing touched point from the evas.
*
* @return The number of touched point on the evas.
*/
EAPI unsigned int evas_touch_point_list_count(Evas *obj);
/**
* @brief This function returns the @c id of nth touch point.
*
* The point which comes from Mouse Event has @c id 0 and The point which comes
* from Multi Event has @c id that is same as Multi Event's device id.
*
* @param[in] n The number of the touched point (0 being the first).
*
* @return id of nth touch point, if the call succeeded, -1 otherwise.
*/
EAPI int evas_touch_point_list_nth_id_get(Evas *obj, unsigned int n);
/**
* @brief This function returns the @c state of nth touch point.
*
* The point's @c state is EVAS_TOUCH_POINT_DOWN when pressed,
* EVAS_TOUCH_POINT_STILL when the point is not moved after pressed,
* EVAS_TOUCH_POINT_MOVE when moved at least once after pressed and
* EVAS_TOUCH_POINT_UP when released.
*
* @param[in] n The number of the touched point (0 being the first).
*
* @return @c state of nth touch point, if the call succeeded,
* EVAS_TOUCH_POINT_CANCEL otherwise.
*/
EAPI Evas_Touch_Point_State evas_touch_point_list_nth_state_get(Evas *obj, unsigned int n);
/**
* @brief This function returns the nth touch point's coordinates.
*
* Touch point's coordinates is updated whenever moving that point on the
* canvas.
*
* @param[in] n The number of the touched point (0 being the first).
* @param[out] x The pointer to a Evas_Coord to be filled in.
* @param[out] y The pointer to a Evas_Coord to be filled in.
*/
EAPI void evas_touch_point_list_nth_xy_get(Evas *eo_e, unsigned int n, Evas_Coord *x, Evas_Coord *y);
/**
* @}
*/
/**
* @addtogroup Evas_Font_Group
*
* @{
*/
/**
* Free list of font descriptions returned by evas_font_dir_available_list().
*
* @param e The evas instance that returned such list.
* @param available the list returned by evas_font_dir_available_list().
*/
EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1);
/** Flags for Font Hinting
*/
typedef enum
{
EVAS_FONT_HINTING_NONE = 0, /**< No font hinting */
EVAS_FONT_HINTING_AUTO, /**< Automatic font hinting */
EVAS_FONT_HINTING_BYTECODE /**< Bytecode font hinting */
} Evas_Font_Hinting_Flags;
/**
* @brief Changes the font hinting for the given evas.
*
* #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
*
* @param[in] hinting The used hinting, one of #EVAS_FONT_HINTING_NONE,
* #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
*/
EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting);
/**
* @brief Retrieves the font hinting used by the given evas.
*
* @return The used hinting, one of #EVAS_FONT_HINTING_NONE,
* #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE.
*/
EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e);
/**
* @brief Checks if the font hinting is supported by the given evas.
*
* One of #EVAS_FONT_HINTING_NONE, #EVAS_FONT_HINTING_AUTO,
* #EVAS_FONT_HINTING_BYTECODE.
*
* @param[in] hinting The hinting to use.
*
* @return @c true if it is supported, @c false otherwise.
*
* @ingroup Evas_Canvas
*/
EAPI Eina_Bool evas_font_hinting_can_hint(const Evas *e, Evas_Font_Hinting_Flags hinting) EINA_WARN_UNUSED_RESULT;
/**
* @}
*/
/**
* @ingroup Evas_Object_Group_Basic
*
* @{
*/
/**
* Increments object reference count to defer its deletion.
*
* @param obj The given Evas object to reference
*
* 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 (counter back to 0). References cannot
* go below 0 and unreferencing past that will result in the reference
* count being limited to 0. References are limited to <c>2^32 - 1</c>
* for an object. Referencing it more than this will result in it
* being limited to this value.
*
* @see evas_object_unref()
* @see evas_object_del()
*
* @note This is a <b>very simple</b> reference counting mechanism! For
* instance, Evas is not ready to check for pending references on a
* canvas deletion, or things like that. This is useful on scenarios
* where, inside a code block, callbacks exist which would possibly
* delete an object we are operating on afterwards. Then, one would
* evas_object_ref() it on the beginning of the block and
* evas_object_unref() it on the end. It would then be deleted at this
* point, if it should be.
*
* Example:
* @code
* evas_object_ref(obj);
*
* // action here...
* evas_object_smart_callback_call(obj, SIG_SELECTED, NULL);
* // more action here...
* evas_object_unref(obj);
* @endcode
*
* @ingroup Evas_Object_Group_Basic
* @since 1.1
*/
EAPI void evas_object_ref(Evas_Object *obj);
/**
* Decrements object reference count.
*
* @param obj The given Evas object to unreference
*
* 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 and puts
* the counter back to 0. See evas_object_ref() for more information.
*
* @see evas_object_ref() (for an example)
* @see evas_object_del()
*
* @ingroup Evas_Object_Group_Basic
* @since 1.1
*/
EAPI void evas_object_unref(Evas_Object *obj);
/**
* Get the object reference count.
*
* @param obj The given Evas object to query
*
* This gets the reference count for an object (normally 0 until it is
* referenced). Values of 1 or greater mean that someone is holding a
* reference to this object that needs to be unreffed before it can be
* deleted.
*
* @see evas_object_ref()
* @see evas_object_unref()
* @see evas_object_del()
*
* @ingroup Evas_Object_Group_Basic
* @since 1.2
*/
EAPI int evas_object_ref_get(const Evas_Object *obj);
/**
* Marks the given Evas object for deletion (when Evas will free its
* memory).
*
* @param obj The given Evas object.
*
* This call will mark @p obj for deletion, which will take place
* whenever it has no more references to it (see evas_object_ref() and
* evas_object_unref()).
*
* At actual deletion time, which may or may not be just after this
* call, ::EVAS_CALLBACK_DEL and ::EVAS_CALLBACK_FREE callbacks will
* be called. If the object currently had the focus, its
* ::EVAS_CALLBACK_FOCUS_OUT callback will also be called.
*
* @see evas_object_ref()
* @see evas_object_unref()
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_del(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
* @brief Retrieves the type of the given Evas object.
*
* For Evas' builtin types, the return strings will be one of "rectangle",
* "line", "polygon", "text", "textblock" or "image".
*
* For Evas smart objects (see @ref Evas_Smart_Group), the name of the smart
* class itself is returned on this call. For the built-in smart objects, these
* names are "EvasObjectSmartClipped" for the clipped smart object,
* "Evas_Object_Box" for the box object and "Evas_Object_Table for the table
* object.
*
* @return The type of the object.
*
* @ingroup Evas_Object_Group_Basic
* @since 1.18
*/
EAPI const char *evas_object_type_get(const Evas_Object *obj);
/**
* @brief Sets the name of the given Evas object to the given name.
*
* There might be occasions where one would like to name his/her objects.
*
* @param[in] name The given name.
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_name_set(Evas_Object *obj, const char *name);
/**
* @brief Retrieves the name of the given Evas object.
*
* Return: The name of the object or @c null, if no name has been given to it.
*
* @return The given name.
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI const char *evas_object_name_get(const Evas_Object *obj);
/**
* @brief Retrieves the object from children of the given object with the given
* name.
*
* This looks for the evas object given a name by @ref evas_object_name_set,
* but it ONLY looks at the children of the object *p obj, and will only
* recurse into those children if @c recurse is greater than 0. If the name is
* not unique within immediate children (or the whole child tree) then it is
* not defined which child object will be returned. If @c recurse is set to -1
* then it will recurse without limit.
*
* @param[in] name The given name.
* @param[in] recurse Set to the number of child levels to recurse (0 == don't
* recurse, 1 == only look at the children of @c obj or their immediate
* children, but no further etc.).
*
* @return The Evas object with the given name on success, Otherwise @c null.
*
* @since 1.2
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI Evas_Object *evas_object_name_child_find(const Evas_Object *obj, const char *name, int recurse) EINA_WARN_UNUSED_RESULT;
/**
* Retrieves the position and (rectangular) size of the given Evas
* object.
*
* @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.
*
* The position, naturally, will be relative to the top left corner of
* the canvas' viewport.
*
* @note Use @c NULL pointers on the geometry components you're not
* interested in: they'll be ignored by the function.
*
* Example:
* @dontinclude evas-events.c
* @skip int w, h, cw, ch;
* @until return
*
* See the full @ref Example_Evas_Events "example".
*
* @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);
/**
* Set the position and (rectangular) size of the given Evas object.
*
* @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.
* @param w The new width of the Evas object.
* @param h The new height of the Evas object.
*
* The position, naturally, will be relative to the top left corner of
* the canvas' viewport.
*
* If the object get moved, the object's ::EVAS_CALLBACK_MOVE callback
* will be called.
*
* If the object get resized, the object's ::EVAS_CALLBACK_RESIZE callback
* will be called.
*
* @see evas_object_move()
* @see evas_object_resize()
* @see evas_object_geometry_get
*
* @since 1.8
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_geometry_set(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.
*
* Besides becoming visible, the object's ::EVAS_CALLBACK_SHOW
* callback will be called.
*
* @see evas_object_hide() for more on object visibility.
* @see evas_object_visible_get()
*
* @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.
*
* Hidden objects, besides not being shown at all in your canvas,
* won't be checked for changes on the canvas rendering
* process. Furthermore, they will not catch input events. Thus, they
* are much ligher (in processing needs) than an object that is
* invisible due to indirect causes, such as being clipped or out of
* the canvas' viewport.
*
* Besides becoming hidden, @p obj object's ::EVAS_CALLBACK_SHOW
* callback will be called.
*
* @note All objects are created in the hidden state! If you want them
* shown, use evas_object_show() after their creation.
*
* @see evas_object_show()
* @see evas_object_visible_get()
*
* Example:
* @dontinclude evas-object-manipulation.c
* @skip if (evas_object_visible_get(d.clipper))
* @until return
*
* See the full @ref Example_Evas_Object_Manipulation "example".
*
* @ingroup Evas_Object_Group_Basic
*/
EAPI void evas_object_hide(Evas_Object *obj) EINA_ARG_NONNULL(1);
/**
*
* Sets the general/main color of the given Evas object to the given
* one.
*
* @see evas_object_color_get() (for an example)
* @note These color values are expected to be premultiplied by @p a.
*
* @ingroup Evas_Object_Group_Basic
*
* @param[in] r The red component of the given color.
* @param[in] g The green component of the given color.
* @param[in] b The blue component of the given color.
* @param[in] a The alpha component of the given color.
*/
EAPI void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a);
/**
*
* Retrieves the general/main color of the given Evas object.
*
* Retrieves the “main” color's RGB component (and alpha channel)
* values, <b>which range from 0 to 255</b>. For the alpha channel,
* which defines the object's transparency level, 0 means totally
* transparent, while 255 means opaque. These color values are
* premultiplied by the alpha value.
*
* Usually you’ll use this attribute for text and rectangle objects,
* where the “main” color is their unique one. If set for objects
* which themselves have colors, like the images one, those colors get
* modulated by this one.
*
* @note All newly created Evas rectangles get the default color
* values of <code>255 255 255 255</code> (opaque white).
*
* @note Use @c NULL pointers on the components you're not interested
* in: they'll be ignored by the function.
*
* Example:
* @dontinclude evas-object-manipulation.c
* @skip int alpha, r, g, b;
* @until return
*
* See the full @ref Example_Evas_Object_Manipulation "example".
*
* @ingroup Evas_Object_Group_Basic
*
* @param[out] r The red component of the given color.
* @param[out] g The green component of the given color.
* @param[out] b The blue component of the given color.
* @param[out] a The alpha component of the given color.
*/
EAPI void evas_object_color_get(const Evas_Object *obj, int *r, int *g, int *b, int *a);
/**
*
* Move the given Evas object to the given location inside its canvas' viewport.
*
* @param[in] x in
* @param[in] y in
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y);
/**
*
* Changes the size of the given Evas object.
*
* @param[in] w in
* @param[in] h in
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
*
* Retrieves whether or not the given Evas object is visible.
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_visible_get(const Evas_Object *obj);
/**
* @brief Sets the hints for an object's maximum size.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* Values -1 will be treated as unset hint components, when queried by
* managers.
*
* @note Smart objects (such as elementary) can have their own size hint
* policy. So calling this API may or may not affect the size of smart objects.
*
* @param[in] w Integer to use as the maximum width hint.
* @param[in] h Integer to use as the maximum height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_max_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
* @brief Retrieves the hints for an object's maximum size.
*
* These are hints on the maximum sizes @c obj should have. This is not a size
* enforcement in any way, it's just a hint that should be used whenever
* appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @param[out] w Integer to use as the maximum width hint.
* @param[out] h Integer to use as the maximum height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_max_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
/**
* @brief Sets the hints for an object's optimum size.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* Values 0 will be treated as unset hint components, when queried by managers.
*
* @note Smart objects(such as elementary) can have their own size hint policy.
* So calling this API may or may not affect the size of smart objects.
*
* @param[in] w Integer to use as the preferred width hint.
* @param[in] h Integer to use as the preferred height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_request_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
* @brief Retrieves the hints for an object's optimum size.
*
* These are hints on the optimum sizes @c obj should have. This is not a size
* enforcement in any way, it's just a hint that should be used whenever
* appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @param[out] w Integer to use as the preferred width hint.
* @param[out] h Integer to use as the preferred height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_request_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
/**
* @brief Sets the hints for an object's minimum size.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* Values 0 will be treated as unset hint components, when queried by managers.
*
* @note Smart objects(such as elementary) can have their own size hint policy.
* So calling this API may or may not affect the size of smart objects.
*
* @param[in] w Integer to use as the minimum width hint.
* @param[in] h Integer to use as the minimum height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_min_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
/**
* @brief Disable/cease clipping on a clipped @c obj object.
*
* This function disables clipping for the object @c obj, if it was already
* clipped, i.e., its visibility and color get detached from the previous
* clipper. If it wasn't, this has no effect. The object @c obj must be a valid
* Evas_Object.
*
* See also @ref evas_object_clip_set, @ref evas_object_clipees_get and
* @ref evas_object_clip_get.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_clip_unset(Evas_Object *obj);
/**
* @brief Retrieves the hints for an object's minimum size.
*
* These are hints on the minimum sizes @c obj should have. This is not a size
* enforcement in any way, it's just a hint that should be used whenever
* appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @param[out] w Integer to use as the minimum width hint.
* @param[out] h Integer to use as the minimum height hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_min_get(const Evas_Object *obj, Evas_Coord *w, Evas_Coord *h);
/**
* @brief Sets the hints for an object's padding space.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* @note Smart objects(such as elementary) can have their own size hint policy.
* So calling this API may or may not affect the size of smart objects.
*
* @param[in] l Integer to specify left padding.
* @param[in] r Integer to specify right padding.
* @param[in] t Integer to specify top padding.
* @param[in] b Integer to specify bottom padding.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_padding_set(Evas_Object *obj, Evas_Coord l, Evas_Coord r, Evas_Coord t, Evas_Coord b);
/**
* @brief Retrieves the hints for an object's padding space.
*
* Padding is extra space an object takes on each of its delimiting rectangle
* sides, in canvas units.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @param[out] l Integer to specify left padding.
* @param[out] r Integer to specify right padding.
* @param[out] t Integer to specify top padding.
* @param[out] b Integer to specify bottom padding.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_padding_get(const Evas_Object *obj, Evas_Coord *l, Evas_Coord *r, Evas_Coord *t, Evas_Coord *b);
/**
* @brief Sets the hints for an object's weight.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* This is a hint on how a container object should resize a given child within
* its area. Containers may adhere to the simpler logic of just expanding the
* child object's dimensions to fit its own (see the #EVAS_HINT_EXPAND helper
* weight macro) or the complete one of taking each child's weight hint as real
* weights to how much of its size to allocate for them in each axis. A
* container is supposed to, after normalizing the weights of its children
* (with weight hints), distribute the space it has to layout them by those
* factors -- most weighted children get larger in this process than the least
* ones.
*
* @note Default weight hint values are 0.0, for both axis.
*
* @param[in] x Non-negative double value to use as horizontal weight hint.
* @param[in] y Non-negative double value to use as vertical weight hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_weight_set(Evas_Object *obj, double x, double y);
/**
* @brief Retrieves the hints for an object's weight.
*
* 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, which in Evas are the @ref Evas_Object_Box "box" and @ref
* Evas_Object_Table "table" smart objects.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @note If @c obj is invalid, then the hint components will be set with 0.0.
*
* @param[out] x Non-negative double value to use as horizontal weight hint.
* @param[out] y Non-negative double value to use as vertical weight hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_weight_get(const Evas_Object *obj, double *x, double *y);
/**
* @brief Sets the hints for an object's alignment.
*
* These are hints on how to align an object inside the boundaries of a
* container/manager. Accepted values are in the 0.0 to 1.0 range, with the
* special value #EVAS_HINT_FILL used to specify "justify" or "fill" by some
* users. In this case, maximum size hints should be enforced with higher
* priority, if they are set. Also, any padding hint set on objects should add
* up to the alignment space on the final scene composition.
*
* See documentation of possible users: in Evas, they are the @ref
* Evas_Object_Box "box" and @ref Evas_Object_Table "table" smart objects.
*
* For the horizontal component, 0.0 means to the left, 1.0 means to the right.
* Analogously, for the vertical component, 0.0 to the top, 1.0 means to the
* bottom.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* @note Default alignment hint values are 0.5, for both axis.
*
* @param[in] x Double, ranging from 0.0 to 1.0 or with the special value
* #EVAS_HINT_FILL, to use as horizontal alignment hint.
* @param[in] y Double, ranging from 0.0 to 1.0 or with the special value
* #EVAS_HINT_FILL, to use as vertical alignment hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_align_set(Evas_Object *obj, double x, double y);
/**
* @brief Retrieves the hints for on object's alignment.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @note If @c obj is invalid, then the hint components will be set with 0.5
*
* @param[out] x Double, ranging from 0.0 to 1.0 or with the special value
* #EVAS_HINT_FILL, to use as horizontal alignment hint.
* @param[out] y Double, ranging from 0.0 to 1.0 or with the special value
* #EVAS_HINT_FILL, to use as vertical alignment hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_align_get(const Evas_Object *obj, double *x, double *y);
/**
* @brief Sets the hints for an object's aspect ratio.
*
* This is not a size enforcement in any way, it's just a hint that should be
* used whenever appropriate.
*
* If any of the given aspect ratio terms are 0, the object's container will
* ignore the aspect and scale @c obj to occupy the whole available area, for
* any given policy.
*
* @note Smart objects(such as elementary) can have their own size hint policy.
* So calling this API may or may not affect the size of smart objects.
*
* @param[in] aspect The policy/type of aspect ratio to apply to @c obj.
* @param[in] w Integer to use as aspect width ratio term.
* @param[in] h Integer to use as aspect height ratio term.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_aspect_set(Evas_Object *obj, Evas_Aspect_Control aspect, Evas_Coord w, Evas_Coord h);
/**
* @brief Retrieves the hints for an object's aspect ratio.
*
* The different aspect ratio policies are documented in the
* #Evas_Aspect_Control type. A container respecting these size hints would
* resize its children accordingly to those policies.
*
* For any policy, if any of the given aspect ratio terms are 0, the object's
* container should ignore the aspect and scale @c obj to occupy the whole
* available area. If they are both positive integers, that proportion will be
* respected, under each scaling policy.
*
* @note Use @c null pointers on the hint components you're not interested in:
* they'll be ignored by the function.
*
* @param[out] aspect The policy/type of aspect ratio to apply to @c obj.
* @param[out] w Integer to use as aspect width ratio term.
* @param[out] h Integer to use as aspect height ratio term.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_aspect_get(const Evas_Object *obj, Evas_Aspect_Control *aspect, Evas_Coord *w, Evas_Coord *h);
/** Display mode size hint. */
typedef enum
{
EFL_GFX_HINT_MODE_NONE = 0, /**< Default mode */
EFL_GFX_HINT_MODE_COMPRESS = 1, /**< Use this mode when you want to give
* compress display mode hint to an object */
EFL_GFX_HINT_MODE_EXPAND = 2, /**< Use this mode when you want to give
* expand display mode hint to an object */
EFL_GFX_HINT_MODE_DONT_CHANGE = 3 /**< Use this mode when an object
* should not change its display mode */
} Efl_Gfx_Hint_Mode;
typedef Efl_Gfx_Hint_Mode Evas_Display_Mode;
#define EVAS_DISPLAY_MODE_NONE EFL_GFX_HINT_MODE_NONE
#define EVAS_DISPLAY_MODE_COMPRESS EFL_GFX_HINT_MODE_COMPRESS
#define EVAS_DISPLAY_MODE_EXPAND EFL_GFX_HINT_MODE_EXPAND
#define EVAS_DISPLAY_MODE_DONT_CHANGE EFL_GFX_HINT_MODE_DONT_CHANGE
/**
* @brief Sets the hints for an object's disply mode,
*
* This is not a size enforcement in any way, it's just a hint that can be used
* whenever appropriate.
*
* @param[in] dispmode Display mode hint.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_size_hint_display_mode_set(Evas_Object *obj, Evas_Display_Mode dispmode);
/**
* @brief Retrieves the hints for an object's display mode
*
* These are hints on the display mode @c obj. This is not a size enforcement
* in any way, it's just a hint that can be used whenever appropriate. This
* mode can be used object's display mode like compress or expand.
*
* @return Display mode hint.
*
* @ingroup Evas_Object_Group
*/
EAPI Evas_Display_Mode evas_object_size_hint_display_mode_get(const Evas_Object *obj);
/**
*
* Sets the layer of its canvas that the given object will be part of.
*
* If you don't use this function, you'll be dealing with an @b unique
* layer of objects, the default one. Additional layers are handy when
* you don't want a set of objects to interfere with another set with
* regard to @b stacking. Two layers are completely disjoint in that
* matter.
*
* This is a low-level function, which you'd be using when something
* should be always on top, for example.
*
* @warning Be careful, it doesn't make sense to change the layer of
* smart objects' children. Smart objects have a layer of their own,
* which should contain all their children objects.
*
* @see evas_object_layer_get()
*
* @param[in] l The number of the layer to place the object on.
Must be between #EVAS_LAYER_MIN and #EVAS_LAYER_MAX.
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_layer_set(Evas_Object *obj, short l);
/**
*
* Retrieves the layer of its canvas that the given object is part of.
*
* @return Number of its layer
*
* @see evas_object_layer_set()
*
* @ingroup Evas_Object_Group
*/
EAPI short evas_object_layer_get(const Evas_Object *obj);
/**
*
* Get the Evas object stacked right below @p obj
*
* @return the #Evas_Object directly below @p obj, if any, or @c NULL,
* if none
*
* This function will traverse layers in its search, if there are
* objects on layers below the one @p obj is placed at.
*
* @see evas_object_layer_get()
* @see evas_object_layer_set()
* @see evas_object_below_get()
*
* @ingroup Evas_Object_Group
*/
EAPI Evas_Object *evas_object_below_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT;
/**
*
* Get the Evas object stacked right above @p obj
*
* @return the #Evas_Object directly above @p obj, if any, or @c NULL,
* if none
*
* This function will traverse layers in its search, if there are
* objects on layers above the one @p obj is placed at.
*
* @see evas_object_layer_get()
* @see evas_object_layer_set()
* @see evas_object_below_get()
*
* @ingroup Evas_Object_Group
*/
EAPI Evas_Object *evas_object_above_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT;
/**
*
* Stack @p obj immediately below @p below
*
* Objects, in a given canvas, are stacked in the order they get added
* to it. This means that, if they overlap, the highest ones will
* cover the lowest ones, in that order. This function is a way to
* change the stacking order for the objects.
*
* This function is intended to be used with <b>objects belonging to
* the same layer</b> in a given canvas, otherwise it will fail (and
* accomplish nothing).
*
* If you have smart objects on your canvas and @p obj is a member of
* one of them, then @p below must also be a member of the same
* smart object.
*
* Similarly, if @p obj is not a member of a smart object, @p below
* must not be either.
*
* @see evas_object_layer_get()
* @see evas_object_layer_set()
* @see evas_object_stack_below()
*
*
* @param[in] below the object below which to stack
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_stack_below(Evas_Object *obj, Evas_Object *below) EINA_ARG_NONNULL(2);
/**
*
* Raise @p obj to the top of its layer.
*
* @p obj will, then, be the highest one in the layer it belongs
* to. Object on other layers won't get touched.
*
* @see evas_object_stack_above()
* @see evas_object_stack_below()
* @see evas_object_lower()
*
* @ingroup Evas_Object_Group
*
*/
EAPI void evas_object_raise(Evas_Object *obj);
/**
*
* Stack @p obj immediately above @p above
*
* Objects, in a given canvas, are stacked in the order they get added
* to it. This means that, if they overlap, the highest ones will
* cover the lowest ones, in that order. This function is a way to
* change the stacking order for the objects.
*
* This function is intended to be used with <b>objects belonging to
* the same layer</b> in a given canvas, otherwise it will fail (and
* accomplish nothing).
*
* If you have smart objects on your canvas and @p obj is a member of
* one of them, then @p above must also be a member of the same
* smart object.
*
* Similarly, if @p obj is not a member of a smart object, @p above
* must not be either.
*
* @see evas_object_layer_get()
* @see evas_object_layer_set()
* @see evas_object_stack_below()
*
*
* @param[in] above the object above which to stack
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_stack_above(Evas_Object *obj, Evas_Object *above) EINA_ARG_NONNULL(2);
/**
*
* Lower @p obj to the bottom of its layer.
*
* @p obj will, then, be the lowest one in the layer it belongs
* to. Objects on other layers won't get touched.
*
* @see evas_object_stack_above()
* @see evas_object_stack_below()
* @see evas_object_raise()
*
* @ingroup Evas_Object_Group
*
*/
EAPI void evas_object_lower(Evas_Object *obj);
/**
* @brief Set a hint flag on the given Evas object that it's used as a "static
* clipper".
*
* This is a hint to Evas that this object is used as a big static clipper and
* shouldn't be moved with children and otherwise considered specially. The
* default value for new objects is @c false.
*
* @param[in] is_static_clip @c true if it's to be used as a static clipper,
* @c false otherwise.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_static_clip_set(Evas_Object *obj, Eina_Bool is_static_clip);
/**
* @brief Return a list of objects currently clipped by @c obj.
*
* This returns the internal list handle that contains all objects clipped by
* the object @c obj. If none are clipped by it, the call returns @c null. This
* list is only valid until the clip list is changed and should be fetched
* again with another call to this function if any objects being clipped by
* this object are unclipped, clipped by a new object, deleted or get the
* clipper deleted. These operations will invalidate the list returned, so it
* should not be used anymore after that point. Any use of the list after this
* may have undefined results, possibly leading to crashes. The object @c obj
* must be a valid Evas_Object.
*
* See also @ref evas_object_clip_set, @ref evas_object_clip_unset and
* @ref evas_object_clip_get.
*
* @return A list of objects being clipped by @c obj.
*
* @ingroup Evas_Object_Group
*/
EAPI const Eina_List *evas_object_clipees_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT;
/**
* @brief Test if any object is clipped by @c obj.
*
* @param[in] obj The object.
*
* @return @c true if any object is clipped by @c obj, @c false otherwise
*
* @since 1.8
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_clipees_has(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT;
/** How the object should be rendered to output.
*
* @ingroup Evas_Object_Group
*/
typedef enum
{
EVAS_RENDER_BLEND = 0, /**< Default render operation: d = d*(1-sa) + s. The
* object will be merged onto the bottom objects using
* simple alpha compositing (a over b). */
EVAS_RENDER_BLEND_REL = 1, /**< DEPRECATED. d = d*(1 - sa) + s*da */
EVAS_RENDER_COPY = 2, /**< Copy mode, d = s. The object's pixels will replace
* everything that was below, effectively hiding them.
*/
EVAS_RENDER_COPY_REL = 3, /**< DEPRECATED. d = s*da */
EVAS_RENDER_ADD = 4, /**< DEPRECATED. d = d + s */
EVAS_RENDER_ADD_REL = 5, /**< DEPRECATED. d = d + s*da */
EVAS_RENDER_SUB = 6, /**< DEPRECATED. d = d - s */
EVAS_RENDER_SUB_REL = 7, /**< DEPRECATED. d = d - s*da */
EVAS_RENDER_TINT = 8, /**< DEPRECATED. d = d*s + d*(1 - sa) + s*(1 - da) */
EVAS_RENDER_TINT_REL = 9, /**< DEPRECATED. d = d*(1 - sa + s) */
EVAS_RENDER_MASK = 10, /**< DEPRECATED. d = d*sa. For masking support, please
* use Efl.Canvas.Object.clip_set or EDC "clip_to" instead.
*/
EVAS_RENDER_MUL = 11 /**< DEPRECATED. d = d*s */
} Evas_Render_Op;
/**
* @brief Sets the render mode to be used for compositing the Evas object.
*
* Note that only copy and blend modes are actually supported: -
* @ref Evas_Render_Op.EVAS_RENDER_BLEND means the object will be merged on top
* of objects below it using simple alpha compositing. -
* @ref Evas_Render_Op.EVAS_RENDER_COPY means this object's pixels will replace
* everything that is below, making this object opaque.
*
* Please do not assume that @ref Evas_Render_Op.EVAS_RENDER_COPY mode can be
* used to "poke" holes in a window (to see through it), as only the compositor
* can ensure that. Copy mode should only be used with otherwise opaque
* widgets, or inside non-window surfaces (eg. a transparent background inside
* an Ecore.Evas.Buffer).
*
* @param[in] render_op One of the Evas_Render_Op values. Only blend (default)
* and copy modes are supported.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_render_op_set(Evas_Object *obj, Evas_Render_Op render_op);
/**
* @brief Retrieves the current value of the operation used for rendering the
* Evas object.
*
* @return One of the Evas_Render_Op values. Only blend (default) and copy
* modes are supported.
*
* @ingroup Evas_Object_Group
*/
EAPI Evas_Render_Op evas_object_render_op_get(const Evas_Object *obj);
/**
* @brief Get the "static clipper" hint flag for a given Evas object.
*
* @return @c true if it's to be used as a static clipper, @c false otherwise.
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_static_clip_get(const Evas_Object *obj);
/**
* @brief Sets the scaling factor for an Evas object. Does not affect all
* objects.
*
* This will multiply the object's dimension by the given factor, thus altering
* its geometry (width and height). Useful when you want scalable UI elements,
* possibly at run time.
*
* @note Only text and textblock objects have scaling change handlers. Other
* objects won't change visually on this call.
*
* @param[in] obj The object.
* @param[in] scale The scaling factor. 1.0 means no scaling, default size.
*
* @ingroup Evas_Object_Group
*/
EAPI void evas_object_scale_set(Evas_Object *obj, double scale);
/**
* @brief Retrieves the scaling factor for the given Evas object.
*
* @param[in] obj The object.
*
* @return The scaling factor. 1.0 means no scaling, default size.
*
* @ingroup Evas_Object_Group
*/
EAPI double evas_object_scale_get(const Evas_Object *obj);
/**
* @brief Returns whether the mouse pointer is logically inside the object.
*
* @param[in] dev The pointer device.
*
* @return @c true if the pointer is inside, @c false otherwise.
*
* @since 1.20
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_pointer_inside_by_device_get(const Evas_Object *obj, Efl_Input_Device * dev);
/**
* @brief Returns whether the default mouse pointer is logically inside the
* object.
*
* When this function is called it will return a value of either @c false or
* @c true, depending on if event_feed_mouse_in or event_feed_mouse_out have
* been called to feed in a mouse enter event into the object.
*
* A return value of @c true indicates the mouse is logically inside the
* object, and @c false implies it is logically outside the object.
*
* If @c e is not a valid object, the return value is undefined.
*
* @return @c true if the mouse pointer is inside the object, @c false
* otherwise
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_pointer_inside_get(const Evas_Object *obj) EINA_WARN_UNUSED_RESULT;
/**
* @brief Returns whether the coords are logically inside the object.
*
* When this function is called it will return a value of either @c false or
* @c true, depending on if the coords are inside the object's current
* geometry.
*
* A return value of @c true indicates the position is logically inside the
* object, and @c false implies it is logically outside the object.
*
* If @c e is not a valid object, the return value is undefined.
*
* @param[in] x The canvas-relative x coordinate.
* @param[in] y The canvas-relative y coordinate.
*
* @return @c true if the coords are inside the object, @c false otherwise
*
* @ingroup Evas_Object_Group
*/
EAPI Eina_Bool evas_object_pointer_coords_inside_get(const Evas_Object *eo_obj, int x, int y) EINA_WARN_UNUSED_RESULT;
#include "canvas/efl_canvas_object_eo.legacy.h"
/**
* @brief Get the Evas to which this object belongs to
*
* The object may be an evas object, an elementary object or window, or an
* evas 3D / VG object.
*/
EAPI Evas *evas_object_evas_get(const Eo *obj);
/**
* @brief Retrieve a list of objects lying over a given position in a canvas.
*
* This function will traverse all the layers of the given canvas, from top to
* bottom, querying for objects with areas covering the given position. The
* user can remove from query objects which are hidden and/or which are set to
* pass events.
*
* @warning This function will skip objects parented by smart objects, acting
* only on the ones at the "top level", with regard to object parenting.
*
* @param[in] obj The object.
* @param[in] x The pixel position.
* @param[in] y The pixel position.
* @param[in] include_pass_events_objects Boolean flag to include or not
* objects which pass events in this calculation.
* @param[in] include_hidden_objects Boolean flag to include or not hidden
* objects in this calculation.
*
* @return The list of objects that are over the given position in @c e.
*
* @ingroup Efl_Canvas
*/
EAPI Eina_List *evas_objects_at_xy_get(Eo *eo_e, int x, int y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects);
/**
* @brief Retrieve the object stacked at the top of a given position in a
* canvas.
*
* This function will traverse all the layers of the given canvas, from top to
* bottom, querying for objects with areas covering the given position. The
* user can remove from the query objects which are hidden and/or which are set
* to pass events.
*
* @warning This function will skip objects parented by smart objects, acting
* only on the ones at the "top level", with regard to object parenting.
*
* @param[in] obj The object.
* @param[in] x The pixel position.
* @param[in] y The pixel position.
* @param[in] include_pass_events_objects Boolean flag to include or not
* objects which pass events in this calculation.
* @param[in] include_hidden_objects Boolean flag to include or not hidden
* objects in this calculation.
*
* @return The Evas object that is over all other objects at the given
* position.
*/
EAPI Evas_Object* evas_object_top_at_xy_get(Eo *eo_e, Evas_Coord x, Evas_Coord y, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects);
/**
* @brief Get all objects in the given rectangle
*
* @param[in] obj The object.
* @param[in] x X coordinate
* @param[in] y Y coordinate
* @param[in] w Width
* @param[in] h Height
* @param[in] include_pass_events_objects @c true if the list should include
* objects which pass events
* @param[in] include_hidden_objects @c true if the list should include hidden
* objects
*
* @return List of objects
*/
EAPI Eina_List *evas_objects_in_rectangle_get(const Eo *obj, int x, int y, int w, int h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT;
/**
* @brief Retrieve the Evas object stacked at the top of a given rectangular
* region in a canvas
*
* This function will traverse all the layers of the given canvas, from top to
* bottom, querying for objects with areas overlapping with the given
* rectangular region inside @c e. The user can remove from the query objects
* which are hidden and/or which are set to pass events.
*
* @warning This function will skip objects parented by smart objects, acting
* only on the ones at the "top level", with regard to object parenting.
*
* @param[in] obj The object.
* @param[in] x The top left corner's horizontal coordinate for the rectangular
* region.
* @param[in] y The top left corner's vertical coordinate for the rectangular
* region.
* @param[in] w The width of the rectangular region.
* @param[in] h The height of the rectangular region.
* @param[in] include_pass_events_objects Boolean flag to include or not
* objects which pass events in this calculation.
* @param[in] include_hidden_objects Boolean flag to include or not hidden
* objects in this calculation.
*
* @return The Evas object that is over all other objects at the given
* rectangular region.
*
* @ingroup Evas_Canvas
*/
EAPI Evas_Object *evas_object_top_in_rectangle_get(const Eo *obj, int x, int y, int w, int h, Eina_Bool include_pass_events_objects, Eina_Bool include_hidden_objects) EINA_WARN_UNUSED_RESULT;
/**
* @}
*/
/**
* @ingroup Evas_Object_Group_Events
*
* @{
*/
/**
* Add (register) a callback function to a given Evas object event.
*
* @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.
*
* A callback function must have the ::Evas_Object_Event_Cb prototype
* definition. The first parameter (@p data) in this definition will
* have the same value passed to evas_object_event_callback_add() as
* the @p data parameter, at runtime. The second parameter @p e is the
* canvas pointer on which the event occurred. The third parameter is
* a pointer to the object on which event occurred. Finally, the
* fourth 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. This is so because some
* events don't carry extra context with them, but others do.
*
* 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_MULTI_DOWN, #EVAS_CALLBACK_MULTI_UP,
* #EVAS_CALLBACK_AXIS_UPDATE,
* #EVAS_CALLBACK_MULTI_MOVE, #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, #EVAS_CALLBACK_RESTACK, #EVAS_CALLBACK_DEL,
* #EVAS_CALLBACK_HOLD, #EVAS_CALLBACK_CHANGED_SIZE_HINTS,
* #EVAS_CALLBACK_IMAGE_PRELOADED or #EVAS_CALLBACK_IMAGE_UNLOADED.
*
* This determines the kind of event that will trigger the callback.
* What follows is a list explaining better the nature of each type of
* event, along with their associated @p event_info pointers:
*
* - #EVAS_CALLBACK_MOUSE_IN: @p event_info is a pointer to an
* #Evas_Event_Mouse_In struct\n\n
* This event is triggered when the mouse pointer enters the area
* (not shaded by other objects) of the object @p obj. This may
* occur by the mouse pointer being moved by
* evas_event_feed_mouse_move() calls, or by the object being shown,
* raised, moved, resized, or other objects being moved out of the
* way, hidden or lowered, whatever may cause the mouse pointer to
* get on top of @p obj, having been on top of another object
* previously.
*
* - #EVAS_CALLBACK_MOUSE_OUT: @p event_info is a pointer to an
* #Evas_Event_Mouse_Out struct\n\n
* This event is triggered exactly like #EVAS_CALLBACK_MOUSE_IN is,
* but it occurs when the mouse pointer exits an object's area. Note
* that no mouse out events will be reported if the mouse pointer is
* implicitly grabbed to an object (mouse buttons are down, having
* been pressed while the pointer was over that object). In these
* cases, mouse out events will be reported once all buttons are
* released, if the mouse pointer has left the object's area. The
* indirect ways of taking off the mouse pointer from an object,
* like cited above, for #EVAS_CALLBACK_MOUSE_IN, also apply here,
* naturally.
*
* - #EVAS_CALLBACK_MOUSE_DOWN: @p event_info is a pointer to an
* #Evas_Event_Mouse_Down struct\n\n
* This event is triggered by a mouse button being pressed while the
* mouse pointer is over an object. If the pointer mode for Evas is
* #EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this
* object to <b>passively grab the mouse</b> until all mouse buttons
* have been released: all future mouse events will be reported to
* only this object until no buttons are down. That includes mouse
* move events, mouse in and mouse out events, and further button
* presses. When all buttons are released, event propagation will
* occur as normal (see #Evas_Object_Pointer_Mode).
*
* - #EVAS_CALLBACK_MOUSE_UP: @p event_info is a pointer to an
* #Evas_Event_Mouse_Up struct\n\n
* This event is triggered by a mouse button being released while
* the mouse pointer is over an object's area (or when passively
* grabbed to an object).
*
* - #EVAS_CALLBACK_MOUSE_MOVE: @p event_info is a pointer to an
* #Evas_Event_Mouse_Move struct\n\n
* This event is triggered by the mouse pointer being moved while
* over an object's area (or while passively grabbed to an object).
*
* - #EVAS_CALLBACK_MOUSE_WHEEL: @p event_info is a pointer to an
* #Evas_Event_Mouse_Wheel struct\n\n
* This event is triggered by the mouse wheel being rolled while the
* mouse pointer is over an object (or passively grabbed to an
* object).
*
* - #EVAS_CALLBACK_MULTI_DOWN: @p event_info is a pointer to an
* #Evas_Event_Multi_Down struct
*
* - #EVAS_CALLBACK_MULTI_UP: @p event_info is a pointer to an
* #Evas_Event_Multi_Up struct
*
* - #EVAS_CALLBACK_MULTI_MOVE: @p event_info is a pointer to an
* #Evas_Event_Multi_Move struct
*
* - #EVAS_CALLBACK_AXIS_UPDATE: @p event_info is a pointer to an
* #Evas_Event_Axis_Update struct
*
* - #EVAS_CALLBACK_FREE: @p event_info is @c NULL \n\n
* 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 it returns, there
* is no guarantee on the object's validity.
*
* - #EVAS_CALLBACK_KEY_DOWN: @p event_info is a pointer to an
* #Evas_Event_Key_Down struct\n\n
* 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: @p event_info is a pointer to an
* #Evas_Event_Key_Up struct \n\n
* 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: @p event_info is @c NULL \n\n
* This event is called when an object gains the focus. When it is
* called the object has already gained the focus.
*
* - #EVAS_CALLBACK_FOCUS_OUT: @p event_info is @c NULL \n\n
* This event is triggered when an object loses the focus. When it
* is called the object has already lost the focus.
*
* - #EVAS_CALLBACK_SHOW: @p event_info is @c NULL \n\n
* This event is triggered by the object being shown by
* evas_object_show().
*
* - #EVAS_CALLBACK_HIDE: @p event_info is @c NULL \n\n
* This event is triggered by an object being hidden by
* evas_object_hide().
*
* - #EVAS_CALLBACK_MOVE: @p event_info is @c NULL \n\n
* 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: @p event_info is @c NULL \n\n
* 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.
*
* - #EVAS_CALLBACK_RESTACK: @p event_info is @c NULL \n\n
* This event is triggered by an object being re-stacked. Stacking
* changes can be triggered by
* evas_object_stack_below()/evas_object_stack_above() and others.
*
* - #EVAS_CALLBACK_DEL: @p event_info is @c NULL.
*
* - #EVAS_CALLBACK_HOLD: @p event_info is a pointer to an
* #Evas_Event_Hold struct
*
* - #EVAS_CALLBACK_CHANGED_SIZE_HINTS: @p event_info is @c NULL.
*
* - #EVAS_CALLBACK_IMAGE_PRELOADED: @p event_info is @c NULL.
*
* - #EVAS_CALLBACK_IMAGE_UNLOADED: @p event_info is @c NULL.
*
* @note Be careful not to add the same callback multiple times, if
* that's not what you want, because Evas won't check if a callback
* existed before exactly as the one being registered (and thus, call
* it more than once on the event, in this case). This would make
* sense if you passed different functions and/or callback data, only.
*
* Example:
* @dontinclude evas-events.c
* @skip evas_object_event_callback_add(
* @until }
*
* See the full example @ref Example_Evas_Events "here".
*
*/
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);
/**
* Add (register) a callback function to a given Evas object event with a
* non-default priority set. Except for the priority field, it's exactly the
* same as @ref evas_object_event_callback_add
*
* @param obj Object to attach a callback to
* @param type The type of event that will trigger the callback
* @param priority The priority of the callback, lower values called first.
* @param func The function to be called when the event is triggered
* @param data The data pointer to be passed to @p func
*
* @see evas_object_event_callback_add
* @since 1.1
*/
EAPI void evas_object_event_callback_priority_add(Evas_Object *obj, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Object_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 4);
/**
* 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 @c 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 (unregister) a callback function registered to a given
* Evas object event.
*
* @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. In errors, @c NULL will be returned.
*
* @note For deletion of Evas object events callbacks filtering by
* just type and function pointer, use
* evas_object_event_callback_del().
*
* 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);
/**
* @brief Requests @c keyname key events be directed to @c obj.
*
* Key grabs allow one or more objects to receive key events for specific key
* strokes even if other objects have focus. Whenever a key is grabbed, only
* the objects grabbing it will get the events for the given keys.
*
* @c keyname is a platform dependent symbolic name for the key pressed (see
* @ref Evas_Keys for more information).
*
* @c modifiers and @c not_modifiers are bit masks of all the modifiers that
* must and mustn't, respectively, be pressed along with @c keyname key in
* order to trigger this new key grab. Modifiers can be things such as Shift
* and Ctrl as well as user defined types via @ref evas_key_modifier_add.
* Retrieve them with @ref evas_key_modifier_mask_get or use 0 for empty masks.
*
* @c exclusive will make the given object the only one permitted to grab the
* given key. If given @c true, subsequent calls on this function with
* different @c obj arguments will fail, unless the key is ungrabbed again.
*
* @warning Providing impossible modifier sets creates undefined behavior.