[evas] Document one more block of functions.
Examples for them come next. SVN revision: 60204
This commit is contained in:
parent
e20d293856
commit
8aae6106b1
|
@ -490,7 +490,7 @@ typedef struct _Evas_Map Evas_Map;
|
|||
|
||||
/**
|
||||
* @typedef Evas
|
||||
* An Evas canvas handle.
|
||||
* An opaque handle to an Evas canvas.
|
||||
* @see evas_new()
|
||||
* @see evas_free()
|
||||
* @ingroup Evas_Canvas
|
||||
|
@ -505,8 +505,8 @@ typedef struct _Evas Evas;
|
|||
typedef struct _Evas_Object Evas_Object;
|
||||
|
||||
typedef void Evas_Performance; /**< An Evas Performance handle */
|
||||
typedef struct _Evas_Modifier Evas_Modifier; /**< An Evas Modifier */
|
||||
typedef struct _Evas_Lock Evas_Lock; /**< An Evas Lock */
|
||||
typedef struct _Evas_Modifier Evas_Modifier; /**< An opaque type containing information on which modifier keys are registered in an Evas canvas */
|
||||
typedef struct _Evas_Lock Evas_Lock; /**< An opaque type containing information on which lock keys are registered in an Evas canvas */
|
||||
typedef struct _Evas_Smart Evas_Smart; /**< An Evas Smart Object handle */
|
||||
typedef struct _Evas_Native_Surface Evas_Native_Surface; /**< A generic datatype for engine specific native surface information */
|
||||
typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */
|
||||
|
@ -922,7 +922,7 @@ typedef enum _Evas_Object_Pointer_Mode
|
|||
} Evas_Object_Pointer_Mode; /**< How mouse pointer should be handled by Evas. */
|
||||
|
||||
typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info);
|
||||
typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info);
|
||||
typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */
|
||||
typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e);
|
||||
typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info);
|
||||
typedef void (*Evas_Async_Events_Put_Cb)(void *target, Evas_Callback_Type type, void *event_info);
|
||||
|
@ -1115,13 +1115,25 @@ EAPI Eina_Bool evas_async_events_put (const void *target, Ev
|
|||
/**
|
||||
* @defgroup Evas_Canvas Canvas Functions
|
||||
*
|
||||
* Functions that deal with the basic evas object. They are the
|
||||
* functions you need to use at a minimum to get a working evas, and
|
||||
* to destroy it.
|
||||
* Low level Evas canvas functions. Sub groups will present more high
|
||||
* level ones, though.
|
||||
*
|
||||
* Most of these functions deal with low level Evas actions, like:
|
||||
* @li create/destroy raw canvases, not bound to any displaying engine
|
||||
* @li tell a canvas i got focused (in a windowing context, for example)
|
||||
* @li tell a canvas a region should not be calculated anymore in rendering
|
||||
* @li tell a canvas to render its contents, immediately
|
||||
*
|
||||
* Most users will be using Evas by means of the @c Ecore_Evas
|
||||
* wrapper, which deals with all the above mentioned issues
|
||||
* automatically for them. Thus, you'll be looking at this section
|
||||
* only if you're building low level stuff.
|
||||
*
|
||||
* The groups within present you functions that deal with the canvas
|
||||
* directly, too, and not yet with its <b>objects</b>. They are the
|
||||
* functions you need to use at a minimum to get a working canvas.
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* Creates a new empty evas.
|
||||
*
|
||||
|
@ -1244,47 +1256,81 @@ EAPI void *evas_data_attach_get (const Evas *e) EINA_WA
|
|||
EAPI void evas_damage_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Add an obscured region.
|
||||
* Add an "obscured region" to an Evas canvas.
|
||||
*
|
||||
* @param e The given canvas pointer.
|
||||
* @param x The rectangle's left position.
|
||||
* @param y The rectangle's top position
|
||||
* @param x The rectangle's top left corner's horizontal coordinate.
|
||||
* @param y The rectangle's top left corner's vertical coordinate
|
||||
* @param w The rectangle's width.
|
||||
* @param h The rectangle's height.
|
||||
*
|
||||
* This is the function by which one tells evas that a part of the
|
||||
* canvas has not to be repainted. To make this region one that have
|
||||
* to be repainted, call the function evas_obscured_clear().
|
||||
* This is the function by which one tells an Evas canvas that a part
|
||||
* of it <b>must not</b> be repainted. The region must be
|
||||
* rectangular and its coordinates inside the canvas viewport are
|
||||
* passed in the call. After this call, the region specified won't
|
||||
* participate in any form in Evas' calculations and actions during
|
||||
* its rendering updates, having its displaying content frozen as it
|
||||
* was just after this function took place.
|
||||
*
|
||||
* @see evas_obscured_clear().
|
||||
* We call it "obscured region" because the most common use case for
|
||||
* this rendering (partial) freeze is something else (most problaby
|
||||
* other canvas) being on top of the specified rectangular region,
|
||||
* thus shading it completely from the user's final scene in a
|
||||
* display. To avoid unecessary processing, one should indicate to the
|
||||
* obscured canvas not to bother about the non-important area.
|
||||
*
|
||||
* The majority of users won't have to worry about this funcion, as
|
||||
* they'll be using just one canvas in their applications, with
|
||||
* nothing inset or on top of it in any form.
|
||||
*
|
||||
* To make this region one that <b>has</b> to be repainted
|
||||
* again, call the function evas_obscured_clear().
|
||||
*
|
||||
* @note This is a <b>very low level function</b>, which most of
|
||||
* Evas' users wouldn't care about.
|
||||
*
|
||||
* @see evas_obscured_clear()
|
||||
* @see evas_render_updates()
|
||||
*
|
||||
* @ingroup Evas_Canvas
|
||||
*/
|
||||
EAPI void evas_obscured_rectangle_add (Evas *e, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Remove all obscured region rectangles from the canvas.
|
||||
* Remove all "obscured regions" from an Evas canvas.
|
||||
*
|
||||
* @param e The given canvas pointer.
|
||||
*
|
||||
* This function removes all the rectangles from the obscured list of
|
||||
* the canvas. It takes obscured areas added with
|
||||
* evas_obscured_rectangle_add() and makes it a region that have to be
|
||||
* repainted.
|
||||
* This function removes all the rectangles from the obscured regions
|
||||
* list of the canvas @p e. It takes obscured areas added with
|
||||
* evas_obscured_rectangle_add() and make them again a regions that
|
||||
* <b>have</b> to be repainted on rendering updates.
|
||||
*
|
||||
* @note This is a <b>very low level function</b>, which most of
|
||||
* Evas' users wouldn't care about.
|
||||
*
|
||||
* @see evas_obscured_rectangle_add()
|
||||
* @see evas_render_updates()
|
||||
*
|
||||
* @ingroup Evas_Canvas
|
||||
*/
|
||||
EAPI void evas_obscured_clear (Evas *e) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Force immediate renderization of the given canvas.
|
||||
* Force immediate renderization of the given Evas canvas.
|
||||
*
|
||||
* @param e The given canvas pointer.
|
||||
* @return A newly allocated list of updated rectangles of the canvas.
|
||||
* Free this list with evas_render_updates_free().
|
||||
* @return A newly allocated list of updated rectangles of the canvas
|
||||
* (@c Eina_Rectangle structs). Free this list with
|
||||
* evas_render_updates_free().
|
||||
*
|
||||
* This function forces an immediate renderization update of the given
|
||||
* given canvas.
|
||||
* canvas @e.
|
||||
*
|
||||
* @note This is a <b>very low level function</b>, which most of
|
||||
* Evas' users wouldn't care about. One would use it, for example, to
|
||||
* grab an Evas' canvas update regions and paint them back, using the
|
||||
* canvas' pixmap, on a displaying system working below Evas.
|
||||
*
|
||||
* @ingroup Evas_Canvas
|
||||
*/
|
||||
|
@ -1505,11 +1551,12 @@ EAPI void evas_render_method_list_free (Eina_List *list);
|
|||
* will be ignored. The value for @p render_method can be found using
|
||||
* @ref evas_render_method_lookup .
|
||||
*
|
||||
* @param e The given evas.
|
||||
* @param render_method The numeric engine value to use.
|
||||
*
|
||||
* @attention it is mandatory that one calls evas_init() before
|
||||
* setting the output method.
|
||||
*
|
||||
* @param e The given evas.
|
||||
* @param render_method The numeric engine value to use.
|
||||
* @ingroup Evas_Output_Method
|
||||
*/
|
||||
EAPI void evas_output_method_set (Evas *e, int render_method) EINA_ARG_NONNULL(1);
|
||||
|
@ -1883,7 +1930,8 @@ EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WA
|
|||
/**
|
||||
* @defgroup Evas_Canvas_Events Canvas Events
|
||||
*
|
||||
* Canvas generates some events
|
||||
* Functions relating to canvas events, be they input (mice,
|
||||
* keyboards, etc) or output ones (internal states changing, etc).
|
||||
*
|
||||
* @ingroup Evas_Canvas
|
||||
*/
|
||||
|
@ -1894,41 +1942,42 @@ EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WA
|
|||
*/
|
||||
|
||||
/**
|
||||
* Add a callback function to the canvas.
|
||||
* 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 function to be called when the event is triggered
|
||||
* @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 when the event
|
||||
* of type @p type occurs on canvas @p e. The function is @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 addition of the
|
||||
* callback to the canvas, evas_alloc_error() should be used to
|
||||
* 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.
|
||||
*
|
||||
* The function will be passed the pointer @p data when it is
|
||||
* called. A callback function must look like this:
|
||||
*
|
||||
* @code
|
||||
* void callback (void *data, Evas *e, void *event_info);
|
||||
* @endcode
|
||||
*
|
||||
* The first parameter @p data in this function will be the same value
|
||||
* passed to evas_event_callback_add() as the @p data parameter. The
|
||||
* second parameter @p e is the canvas handle 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.
|
||||
* 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.
|
||||
* This determines the kind of event that will trigger the callback to
|
||||
* be called. So far none of the event types provide useful data, so
|
||||
* in all of them @p event_info pointer is @c NULL.
|
||||
* #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:
|
||||
* @code
|
||||
|
@ -1937,19 +1986,27 @@ EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WA
|
|||
* void focus_in_callback(void *data, Evas *e, void *event_info);
|
||||
* void focus_out_callback(void *data, Evas *e, void *event_info);
|
||||
*
|
||||
* evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data);
|
||||
* evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback,
|
||||
* my_data);
|
||||
* if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
|
||||
* {
|
||||
* fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
|
||||
* exit(-1);
|
||||
* }
|
||||
* evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, focus_out_callback, my_data);
|
||||
* evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT,
|
||||
* focus_out_callback, my_data);
|
||||
* if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
|
||||
* {
|
||||
* fprintf(stderr, "ERROR: Callback registering failed! Abort!\n");
|
||||
* exit(-1);
|
||||
* }
|
||||
* @endcode
|
||||
*
|
||||
* @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);
|
||||
|
||||
|
@ -1980,21 +2037,24 @@ EAPI void evas_event_callback_add (Evas *e, Evas_Callb
|
|||
EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3);
|
||||
|
||||
/**
|
||||
* Delete a callback function from the canvas.
|
||||
* Delete (unregister) a callback function registered to a given
|
||||
* canvas event.
|
||||
*
|
||||
* @param e Canvas to remove a callback from
|
||||
* @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 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
|
||||
* canvas @p e which was triggered by the event type @p type and was
|
||||
* calling the function @p func with data @p data when triggered. If
|
||||
* 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 was added to the canvas. If not
|
||||
* successful NULL will be returned.
|
||||
* 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:
|
||||
* @code
|
||||
|
@ -2002,8 +2062,12 @@ EAPI void *evas_event_callback_del (Evas *e, Evas_Callb
|
|||
* void *my_data;
|
||||
* void focus_in_callback(void *data, Evas *e, void *event_info);
|
||||
*
|
||||
* my_data = evas_event_callback_del_full(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data);
|
||||
* my_data = evas_event_callback_del_full(object, EVAS_CALLBACK_CANVAS_FOCUS_IN,
|
||||
* focus_in_callback, my_data);
|
||||
* @endcode
|
||||
*
|
||||
* @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);
|
||||
|
||||
|
@ -2060,10 +2124,19 @@ EAPI void evas_post_event_callback_remove (Evas *e, Evas_Objec
|
|||
EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data);
|
||||
|
||||
/**
|
||||
* @defgroup Evas_Event_Freezing_Group Event Freezing Functions
|
||||
* @defgroup Evas_Event_Freezing_Group Input Events Freezing Functions
|
||||
*
|
||||
* Functions that deal with the freezing of event processing of an
|
||||
* evas.
|
||||
* Functions that deal with the freezing of input event processing of
|
||||
* an Evas canvas.
|
||||
*
|
||||
* There might be scenarios during a graphical user interface
|
||||
* program's use when the developer whishes the users wouldn't be able
|
||||
* to deliver input events to this application. It may, for example,
|
||||
* be the time for it to populate a view or to change some
|
||||
* layout. Assuming proper behavior with user interaction during this
|
||||
* exact time would be hard, as things are in a changing state. The
|
||||
* programmer can then tell the canvas to ignore input events,
|
||||
* bringing it back to normal behavior when he/she wants.
|
||||
*
|
||||
* @ingroup Evas_Canvas_Events
|
||||
*/
|
||||
|
@ -2074,13 +2147,18 @@ EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Objec
|
|||
*/
|
||||
|
||||
/**
|
||||
* Freeze all event processing.
|
||||
* @param e The canvas to freeze event processing on.
|
||||
* Freeze all input events processing.
|
||||
*
|
||||
* This function will indicate to evas that the canvas @p e is to have
|
||||
* all event processing frozen until a matching evas_event_thaw()
|
||||
* function is called on the same canvas. Every freeze call must be
|
||||
* matched by a thaw call in order to completely thaw out a canvas.
|
||||
* @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</b>. 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 interect with your user
|
||||
* interface when you're populating a view or changing the layout.
|
||||
*
|
||||
* Example:
|
||||
* @code
|
||||
|
@ -2090,34 +2168,37 @@ EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Objec
|
|||
* evas_event_freeze(evas);
|
||||
* evas_object_move(object, 50, 100);
|
||||
* evas_object_resize(object, 200, 200);
|
||||
* // more realistic code would be a toolkit or Edje doing some UI changes here
|
||||
* evas_event_thaw(evas);
|
||||
* @endcode
|
||||
*/
|
||||
EAPI void evas_event_freeze (Evas *e) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Thaw a canvas out after freezing.
|
||||
* 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, events will start
|
||||
* being processed again after this call, but this call will not
|
||||
* invole any "missed" events to be evaluated.
|
||||
* 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</b> be
|
||||
* evaluated.
|
||||
*
|
||||
* See evas_event_freeze() for an example.
|
||||
*/
|
||||
EAPI void evas_event_thaw (Evas *e) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* Return the freeze count of a given canvas.
|
||||
* 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
|
||||
* 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
|
||||
* 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:
|
||||
|
@ -2146,15 +2227,16 @@ EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONN
|
|||
*/
|
||||
|
||||
/**
|
||||
* @defgroup Evas_Event_Feeding_Group Event Feeding Functions
|
||||
* @defgroup Evas_Event_Feeding_Group Input Events Feeding Functions
|
||||
*
|
||||
* Functions to tell Evas that events happened and should be
|
||||
* Functions to tell Evas that input events happened and should be
|
||||
* processed.
|
||||
*
|
||||
* As explained in @ref intro_not_evas, Evas does not know how to poll
|
||||
* for events, so the developer should do it and then feed such events
|
||||
* to the canvas to be processed. This is only required if operating
|
||||
* Evas directly as modules such as Ecore_Evas does that for you.
|
||||
* for input events, so the developer should do it and then feed such
|
||||
* events to the canvas to be processed. This is only required if
|
||||
* operating Evas directly. Modules such as Ecore_Evas do that for
|
||||
* you.
|
||||
*
|
||||
* @ingroup Evas_Canvas_Events
|
||||
*/
|
||||
|
@ -4274,16 +4356,27 @@ EAPI Evas_Render_Op evas_object_render_op_get (const Evas_Obje
|
|||
/**
|
||||
* Retrieve the object that currently has focus.
|
||||
*
|
||||
* @param e The @c Evas canvas to query focus on.
|
||||
* @param e The Evas canvas to query for focused object on.
|
||||
*
|
||||
* Returns the object that currently has focus, NULL otherwise.
|
||||
* Evas can have (at most) one of its objects focused at a time.
|
||||
* Focused objects will be the ones having <b>key events</b> delivered
|
||||
* to, which the programmer can act upon by means of
|
||||
* evas_object_event_callback_add() usage.
|
||||
*
|
||||
* @note Most users wouldn't be dealing directly with Evas' focused
|
||||
* objects. Instead, they would be using a higher level library for
|
||||
* that (like a toolkit, as Elementary) to handle focus and who's
|
||||
* receiving input for them.
|
||||
*
|
||||
* This call returns the object that currently has focus on the canvas
|
||||
* @p e or @c NULL, if none.
|
||||
*
|
||||
* @see evas_object_focus_set
|
||||
* @see evas_object_focus_get
|
||||
* @see evas_object_key_grab
|
||||
* @see evas_object_key_ungrab
|
||||
*
|
||||
* @return The object that has focus or NULL is there is not one.
|
||||
* @return The object that has focus or NULL if there is not one.
|
||||
*
|
||||
* @ingroup Evas_Object_Group_Find
|
||||
*/
|
||||
|
@ -8499,8 +8592,28 @@ EAPI int evas_string_char_len_get (const char *str) EINA_
|
|||
/**
|
||||
* @defgroup Evas_Keys Key Input Functions
|
||||
*
|
||||
* Functions which feed key events to the canvas.
|
||||
*
|
||||
* As explained in @ref intro_not_evas, Evas is <b>not</b> aware of
|
||||
* input systems at all. Then, the user, if using it crudely
|
||||
* (evas_new()), will have to feed it with input events, so that it
|
||||
* can react somehow. If, however, the user creates a canvas by means
|
||||
* of the Ecore_Evas wrapper, it will automatically bind the chosen
|
||||
* display engine's input events to the canvas, for you.
|
||||
*
|
||||
* This group presents the functions dealing with the feeding of key
|
||||
* events to the canvas. On most of them, one has to reference a given
|
||||
* key by a name (<code>keyname</code> argument). Those are
|
||||
* <b>platform dependent</b> symbolic names for the keys. Sometimes
|
||||
* you'll get the right <code>keyname</code> by simply using an ASCII
|
||||
* value of the key name, but it won't be like that always.
|
||||
*
|
||||
* Typical platforms are Linux frame buffer (Ecore_FB) and X server
|
||||
* (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer
|
||||
* to your display engine's documentation when using evas through an
|
||||
* Ecore helper wrapper when you need the <code>keyname</code>s.
|
||||
*
|
||||
* @ingroup Evas_Canvas
|
||||
* @todo Finish proper documentation of this group.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
@ -8509,9 +8622,11 @@ EAPI int evas_string_char_len_get (const char *str) EINA_
|
|||
*/
|
||||
|
||||
/**
|
||||
* Returns a handle to the modifiers available in the system. This is required to check
|
||||
* for modifiers with the evas_key_modifier_is_set function.
|
||||
* Returns a handle to the list of modifier keys registered in the
|
||||
* canvas @p e. This is required to check for which modifiers are set
|
||||
* at a given time with the evas_key_modifier_is_set() function.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_del
|
||||
|
@ -8519,73 +8634,88 @@ EAPI int evas_string_char_len_get (const char *str) EINA_
|
|||
* @see evas_key_modifier_off
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
*
|
||||
* @return An Evas_Modifier handle to query the modifier subsystem with
|
||||
* evas_key_modifier_is_set, or NULL on error.
|
||||
* @return An ::Evas_Modifier handle to query Evas' keys subsystem
|
||||
* with evas_key_modifier_is_set(), or @c NULL on error.
|
||||
*/
|
||||
EAPI const Evas_Modifier *evas_key_modifier_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
|
||||
|
||||
/**
|
||||
* Returns a handle to the locks available in the system. This is required to check for
|
||||
* locks with the evas_key_lock_is_set function.
|
||||
* Returns a handle to the list of lock keys registered in the canvas
|
||||
* @p e. This is required to check for which locks are set at a given
|
||||
* time with the evas_key_lock_is_set() function.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
*
|
||||
* @see evas_key_lock_add
|
||||
* @see evas_key_lock_del
|
||||
* @see evas_key_lock_on
|
||||
* @see evas_key_lock_off
|
||||
*
|
||||
* @see evas_key_lock_is_set
|
||||
* @param e The pointer to the Evas Canvas
|
||||
*
|
||||
* @return An Evas_Lock handle to query the lock subsystem with
|
||||
* evas_key_lock_is_set, or NULL on error.
|
||||
* @return An ::Evas_Lock handle to query Evas' keys subsystem with
|
||||
* evas_key_lock_is_set(), or @c NULL on error.
|
||||
*/
|
||||
EAPI const Evas_Lock *evas_key_lock_get (const Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE;
|
||||
|
||||
|
||||
/**
|
||||
* Checks the state of a given modifier. If the modifier is set, such as shift being pressed
|
||||
* this function returns true.
|
||||
* Checks the state of a given modifier key, at the time of the
|
||||
* call. If the modifier is set, such as shift being pressed, this
|
||||
* function returns @c Eina_True.
|
||||
*
|
||||
* @param m The current modifiers set, as returned by
|
||||
* evas_key_modifier_get().
|
||||
* @param keyname The name of the modifier key to check status for.
|
||||
*
|
||||
* @return @c Eina_True if the modifier key named @p keyname is on, @c
|
||||
* Eina_False otherwise.
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_del
|
||||
* @see evas_key_modifier_get
|
||||
* @see evas_key_modifier_on
|
||||
* @see evas_key_modifier_off
|
||||
*
|
||||
* @param m The current modifier set as returned by evas_key_modifier_get.
|
||||
* @param keyname The name of the key to check its status.
|
||||
*
|
||||
* @return 1 if the @p keyname is on, 0 otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
|
||||
|
||||
|
||||
/**
|
||||
* Checks the state of a given lock. If the lock is set, such as caps lock, this function
|
||||
* returns true.
|
||||
* Checks the state of a given lock key, at the time of the call. If
|
||||
* the lock is set, such as caps lock, this function returns @c
|
||||
* Eina_True.
|
||||
*
|
||||
* @param l The current locks set, as returned by evas_key_lock_get().
|
||||
* @param keyname The name of the lock key to check status for.
|
||||
*
|
||||
* @return @c Eina_True if the @p keyname lock key is set, @c
|
||||
* Eina_False otherwise.
|
||||
*
|
||||
* @see evas_key_lock_get
|
||||
* @see evas_key_lock_add
|
||||
* @see evas_key_lock_del
|
||||
* @see evas_key_lock_on
|
||||
* @see evas_key_lock_off
|
||||
*
|
||||
* @param l The current lock set as returned by evas_key_lock_get.
|
||||
* @param keyname The name of the lock to add the the list.
|
||||
*
|
||||
* @param 1 if the @p keyname kock is set, 0 otherwise.
|
||||
*/
|
||||
EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
|
||||
|
||||
|
||||
/**
|
||||
* Adds the @p keyname to the current list of modifiers.
|
||||
* Adds the @p keyname key to the current list of modifier keys.
|
||||
*
|
||||
* Modifiers can be keys like shift, alt and ctrl, as well as user defined. This allows
|
||||
* custom modifiers to be added to the evas system as run time. It is then possible to set
|
||||
* and unset the modifier for other parts of the program to check and act on.
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the modifier key to add to the list of
|
||||
* Evas modifiers.
|
||||
*
|
||||
* Modifiers are keys like shift, alt and ctrl, i.e., keys which are
|
||||
* meant to be pressed together with others, altering the behavior of
|
||||
* the secondly pressed keys somehow. Evas is so that these keys can
|
||||
* be user defined.
|
||||
*
|
||||
* This call allows custom modifiers to be added to the Evas system at
|
||||
* run time. It is then possible to set and unset modifier keys
|
||||
* programmatically for other parts of the program to check and act
|
||||
* on. Programmers using Evas would check for modifier keys on key
|
||||
* event callbacks using evas_key_modifier_is_set().
|
||||
*
|
||||
* @see evas_key_modifier_del
|
||||
* @see evas_key_modifier_get
|
||||
|
@ -8593,122 +8723,162 @@ EAPI Eina_Bool evas_key_lock_is_set (const Evas_Lock *l, co
|
|||
* @see evas_key_modifier_off
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the modifier to add to the list.
|
||||
* @note If the programmer instantiates the canvas by means of the
|
||||
* ecore_evas_new() family of helper functions, Ecore will take
|
||||
* care of registering on it all standard modifiers: "Shift",
|
||||
* "Control", "Alt", "Meta", "Hyper", "Super".
|
||||
*/
|
||||
EAPI void evas_key_modifier_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Removes the @p keyname from the current list of modifiers.
|
||||
* Removes the @p keyname key from the current list of modifier keys
|
||||
* on canvas @e.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the key to remove from the modifiers list.
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_get
|
||||
* @see evas_key_modifier_on
|
||||
* @see evas_key_modifier_off
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the key to remove from the modifiers list.
|
||||
*/
|
||||
EAPI void evas_key_modifier_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Adds the @p keyname to the current list of locks.
|
||||
* Adds the @p keyname key to the current list of lock keys.
|
||||
*
|
||||
* Locks can be keys like caps lock, num lock or scroll lock, as well as user defined. This
|
||||
* allows custom locks to be added to the evas system at run time. It is then possible to
|
||||
* set and unset the lock for other parts of the program to check and act on.
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the key to add to the locks list.
|
||||
*
|
||||
* Locks are keys like caps lock, num lock or scroll lock, i.e., keys
|
||||
* which are meant to be pressed once -- toggling a binary state which
|
||||
* is bound to it -- and thus altering the behavior of all
|
||||
* subsequently pressed keys somehow, depending on its state. Evas is
|
||||
* so that these keys can be defined by the user.
|
||||
*
|
||||
* This allows custom locks to be added to the evas system at run
|
||||
* time. It is then possible to set and unset lock keys
|
||||
* programmatically for other parts of the program to check and act
|
||||
* on. Programmers using Evas would check for lock keys on key event
|
||||
* callbacks using evas_key_lock_is_set().
|
||||
*
|
||||
* @see evas_key_lock_get
|
||||
* @see evas_key_lock_del
|
||||
* @see evas_key_lock_on
|
||||
* @see evas_key_lock_off
|
||||
* @see evas_key_lock_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the key to remove from the modifier list.
|
||||
* @note If the programmer instantiates the canvas by means of the
|
||||
* ecore_evas_new() family of helper functions, Ecore will take
|
||||
* care of registering on it all standard lock keys: "Caps_Lock",
|
||||
* "Num_Lock", "Scroll_Lock".
|
||||
*/
|
||||
EAPI void evas_key_lock_add (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Removes The @p keyname from the current list of locks.
|
||||
* Removes the @p keyname key from the current list of lock keys on
|
||||
* canvas @e.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the key to remove from the locks list.
|
||||
*
|
||||
* @see evas_key_lock_get
|
||||
* @see evas_key_lock_add
|
||||
* @see evas_key_lock_on
|
||||
* @see evas_key_lock_off
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the key to remove from the lock list.
|
||||
*/
|
||||
EAPI void evas_key_lock_del (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
|
||||
/**
|
||||
* Enables or turns on the modifier with name @p keyname.
|
||||
* Enables or turns on programmatically the modifier key with name @p
|
||||
* keyname.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the modifier to enable.
|
||||
*
|
||||
* The effect will be as if the key was pressed for the whole time
|
||||
* between this call and a matching evas_key_modifier_off().
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_get
|
||||
* @see evas_key_modifier_off
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the modifier to set.
|
||||
*/
|
||||
EAPI void evas_key_modifier_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Disables or turns off the modifier with name @p keyname.
|
||||
* Disables or turns off programmatically the modifier key with name
|
||||
* @p keyname.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the modifier to disable.
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_get
|
||||
* @see evas_key_modifier_on
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the modifier to un-set.
|
||||
*/
|
||||
EAPI void evas_key_modifier_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Enables or turns on the lock with name @p keyname.
|
||||
* Enables or turns on programmatically the lock key with name @p
|
||||
* keyname.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the lock to enable.
|
||||
*
|
||||
* The effect will be as if the key was put on its active state after
|
||||
* this call.
|
||||
*
|
||||
* @see evas_key_lock_get
|
||||
* @see evas_key_lock_add
|
||||
* @see evas_key_lock_del
|
||||
* @see evas_key_lock_off
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the lock to set.
|
||||
*/
|
||||
EAPI void evas_key_lock_on (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* Disables or turns off the lock with name @p keyname.
|
||||
* Disables or turns off programmatically the lock key with name @p
|
||||
* keyname.
|
||||
*
|
||||
* @param e The pointer to the Evas canvas
|
||||
* @param keyname The name of the lock to disable.
|
||||
*
|
||||
* The effect will be as if the key was put on its inactive state
|
||||
* after this call.
|
||||
*
|
||||
* @see evas_key_lock_get
|
||||
* @see evas_key_lock_add
|
||||
* @see evas_key_lock_del
|
||||
* @see evas_key_lock_on
|
||||
*
|
||||
* @param e The pointer to the Evas Canvas
|
||||
* @param keyname The name of the lock to un-set.
|
||||
*/
|
||||
EAPI void evas_key_lock_off (Evas *e, const char *keyname) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
|
||||
/**
|
||||
* Creates a bit mask from the @p keyname for use with events to check for the presence
|
||||
* of the @p keyname modifier.
|
||||
* Creates a bit mask from the @p keyname <b>modifier</b> key.
|
||||
* Values returned from different calls to it may be ORed together,
|
||||
* naturally.
|
||||
*
|
||||
* @param e The canvas whom to query the bit mask from.
|
||||
* @param keyname The name of the modifier key to create the mask for.
|
||||
*
|
||||
* @returns the bit mask or 0 if the @p keyname key wasn't registered as a
|
||||
* modifier for canvas @p e.
|
||||
*
|
||||
* This function is meant to be using in conjunction with
|
||||
* evas_object_key_grab()/evas_object_key_ungrab(). Go check their
|
||||
* documentation for more information.
|
||||
*
|
||||
* @see evas_key_modifier_add
|
||||
* @see evas_key_modifier_get
|
||||
* @see evas_key_modifier_on
|
||||
* @see evas_key_modifier_off
|
||||
* @see evas_key_modifier_is_set
|
||||
*
|
||||
* @param keyname The name of the modifier to create the mask for.
|
||||
*
|
||||
* @returns the bit mask or 0 if the @p keyname wasn't registered as a modifier.
|
||||
* @see evas_object_key_grab
|
||||
* @see evas_object_key_ungrab
|
||||
*/
|
||||
EAPI Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas *e, const char *keyname) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1, 2) EINA_PURE;
|
||||
|
||||
|
|
Loading…
Reference in New Issue