Functions which feed key events to the canvas. More...
Functions | |
const Evas_Modifier * | evas_key_modifier_get (const Evas *e) |
Returns a handle to the list of modifier keys registered in the canvas e . More... | |
const Evas_Lock * | evas_key_lock_get (const Evas *e) |
Returns a handle to the list of lock keys registered in the canvas e . More... | |
Eina_Bool | evas_key_modifier_is_set (const Evas_Modifier *m, const char *keyname) |
Checks the state of a given modifier key, at the time of the call. More... | |
Eina_Bool | evas_key_lock_is_set (const Evas_Lock *l, const char *keyname) |
Checks the state of a given lock key, at the time of the call. More... | |
void | evas_key_modifier_add (Evas *e, const char *keyname) |
Adds the keyname key to the current list of modifier keys. More... | |
void | evas_key_modifier_del (Evas *e, const char *keyname) |
Removes the keyname key from the current list of modifier keys on canvas e . More... | |
void | evas_key_lock_add (Evas *e, const char *keyname) |
Adds the keyname key to the current list of lock keys. More... | |
void | evas_key_lock_del (Evas *e, const char *keyname) |
Removes the keyname key from the current list of lock keys on canvas e . More... | |
void | evas_key_modifier_on (Evas *e, const char *keyname) |
Enables or turns on programmatically the modifier key with name keyname . More... | |
void | evas_key_modifier_off (Evas *e, const char *keyname) |
Disables or turns off programmatically the modifier key with name keyname . More... | |
void | evas_key_lock_on (Evas *e, const char *keyname) |
Enables or turns on programmatically the lock key with name keyname . More... | |
void | evas_key_lock_off (Evas *e, const char *keyname) |
Disables or turns off programmatically the lock key with name keyname . More... | |
Evas_Modifier_Mask | evas_key_modifier_mask_get (const Evas *e, const char *keyname) |
Creates a bit mask from the keyname modifier key. More... | |
Eina_Bool | evas_object_key_grab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers, Eina_Bool exclusive) |
Requests keyname key events be directed to obj . More... | |
void | evas_object_key_ungrab (Evas_Object *obj, const char *keyname, Evas_Modifier_Mask modifiers, Evas_Modifier_Mask not_modifiers) |
Removes the grab on keyname key events by obj . More... | |
Detailed Description
Functions which feed key events to the canvas.
As explained in What Evas is not?, Evas is not aware of input systems at all. Then, the user, if using it crudely (evas_new()), will have to feed it with input events, so that it can react somehow. If, however, the user creates a canvas by means of the Ecore_Evas wrapper, it will automatically bind the chosen display engine's input events to the canvas, for you.
This group presents the functions dealing with the feeding of key events to the canvas. On most of them, one has to reference a given key by a name (keyname
argument). Those are platform dependent symbolic names for the keys. Sometimes you'll get the right keyname
by simply using an ASCII value of the key name, but it won't be like that always.
Typical platforms are Linux frame buffer (Ecore_FB) and X server (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer to your display engine's documentation when using evas through an Ecore helper wrapper when you need the keyname
s.
Example:
All the other evas_key
functions behave on the same manner. See the full example.
Function Documentation
void evas_key_lock_add | ( | Evas * | e, |
const char * | keyname | ||
) |
Adds the keyname
key to the current list of lock keys.
- Parameters
-
e The pointer to the Evas canvas 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().
- 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".
References evas_key_lock_del().
void evas_key_lock_del | ( | Evas * | e, |
const char * | keyname | ||
) |
Removes the keyname
key from the current list of lock keys on canvas e
.
- Parameters
-
e The pointer to the Evas canvas keyname The name of the key to remove from the locks list.
Referenced by evas_key_lock_add().
Returns a handle to the list of lock keys registered in the canvas e
.
This is required to check for which locks are set at a given time with the evas_key_lock_is_set() function.
- Parameters
-
e The pointer to the Evas canvas
- Returns
- An Evas_Lock handle to query Evas' keys subsystem with evas_key_lock_is_set(), or
NULL
on error.
Eina_Bool evas_key_lock_is_set | ( | const Evas_Lock * | l, |
const char * | keyname | ||
) |
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 Eina_True
.
- Parameters
-
l The current locks set, as returned by evas_key_lock_get(). keyname The name of the lock key to check status for.
- Returns
Eina_True
if thekeyname
lock key is set,Eina_False
otherwise.
void evas_key_lock_off | ( | Evas * | e, |
const char * | keyname | ||
) |
Disables or turns off programmatically the lock key with name keyname
.
- Parameters
-
e The pointer to the Evas canvas 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.
void evas_key_lock_on | ( | Evas * | e, |
const char * | keyname | ||
) |
Enables or turns on programmatically the lock key with name keyname
.
- Parameters
-
e The pointer to the Evas canvas 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.
void evas_key_modifier_add | ( | Evas * | e, |
const char * | keyname | ||
) |
Adds the keyname
key to the current list of modifier keys.
- Parameters
-
e The pointer to the Evas canvas 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 Also
- evas_key_modifier_del
- evas_key_modifier_get
- evas_key_modifier_on
- evas_key_modifier_off
- evas_key_modifier_is_set
- Note
- If the programmer instantiates the canvas by means of the ecore_evas_new() family of helper functions, Ecore will take care of registering on it all standard modifiers: "Shift", "Control", "Alt", "Meta", "Hyper", "Super".
References evas_key_modifier_del().
void evas_key_modifier_del | ( | Evas * | e, |
const char * | keyname | ||
) |
Removes the keyname
key from the current list of modifier keys on canvas e
.
- Parameters
-
e The pointer to the Evas canvas keyname The name of the key to remove from the modifiers list.
- See Also
- evas_key_modifier_add
- evas_key_modifier_get
- evas_key_modifier_on
- evas_key_modifier_off
- evas_key_modifier_is_set
Referenced by evas_key_modifier_add().
const Evas_Modifier* evas_key_modifier_get | ( | const Evas * | e) |
Returns a handle to the list of modifier keys registered in the canvas e
.
This is required to check for which modifiers are set at a given time with the evas_key_modifier_is_set() function.
- Parameters
-
e The pointer to the Evas canvas
- See Also
- evas_key_modifier_add
- evas_key_modifier_del
- evas_key_modifier_on
- evas_key_modifier_off
- evas_key_modifier_is_set
- Returns
- An Evas_Modifier handle to query Evas' keys subsystem with evas_key_modifier_is_set(), or
NULL
on error.
Eina_Bool evas_key_modifier_is_set | ( | const Evas_Modifier * | m, |
const char * | keyname | ||
) |
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 Eina_True
.
- Parameters
-
m The current modifiers set, as returned by evas_key_modifier_get(). keyname The name of the modifier key to check status for.
- Returns
Eina_True
if the modifier key namedkeyname
is on,Eina_False
otherwise.
Evas_Modifier_Mask evas_key_modifier_mask_get | ( | const Evas * | e, |
const char * | keyname | ||
) |
Creates a bit mask from the keyname
modifier key.
Values returned from different calls to it may be ORed together, naturally.
- Parameters
-
e The canvas whom to query the bit mask from. keyname The name of the modifier key to create the mask for.
- Returns
- the bit mask or 0 if the
keyname
key wasn't registered as a modifier for canvase
.
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.
void evas_key_modifier_off | ( | Evas * | e, |
const char * | keyname | ||
) |
Disables or turns off programmatically the modifier key with name keyname
.
- Parameters
-
e The pointer to the Evas canvas keyname The name of the modifier to disable.
void evas_key_modifier_on | ( | Evas * | e, |
const char * | keyname | ||
) |
Enables or turns on programmatically the modifier key with name keyname
.
- Parameters
-
e The pointer to the Evas canvas 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().
Eina_Bool evas_object_key_grab | ( | Evas_Object * | obj, |
const char * | keyname, | ||
Evas_Modifier_Mask | modifiers, | ||
Evas_Modifier_Mask | not_modifiers, | ||
Eina_Bool | exclusive | ||
) |
Requests keyname
key events be directed to obj
.
- Parameters
-
obj the object to direct keyname
events to.keyname the key to request events for. modifiers a mask of modifiers that must be present to trigger the event. not_modifiers a mask of modifiers that must not be present to trigger the event. exclusive request that the obj
is the only object receiving thekeyname
events.
- Returns
EINA_TRUE
, if the call succeeded,EINA_FALSE
otherwise.
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.
keyname
is a platform dependent symbolic name for the key pressed (see Key Input Functions for more information).
modifiers
and not_modifiers
are bit masks of all the modifiers that must and mustn't, respectively, be pressed along with 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 evas_key_modifier_add(). Retrieve them with evas_key_modifier_mask_get() or use 0
for empty masks.
exclusive
will make the given object the only one permitted to grab the given key. If given EINA_TRUE
, subsequent calls on this function with different obj
arguments will fail, unless the key is ungrabbed again.
Example code follows.
See the full example here.
void evas_object_key_ungrab | ( | Evas_Object * | obj, |
const char * | keyname, | ||
Evas_Modifier_Mask | modifiers, | ||
Evas_Modifier_Mask | not_modifiers | ||
) |
Removes the grab on keyname
key events by obj
.
- Parameters
-
obj the object that has an existing key grab. keyname the key the grab is set for. modifiers a mask of modifiers that must be present to trigger the event. not_modifiers a mask of modifiers that must not not be present to trigger the event.
Removes a key grab on obj
if keyname
, modifiers
, and not_modifiers
match.
Example code follows.
See the full example here.