Tizen Native API
Key Input Functions

Functions

const Evas_Lockevas_key_lock_get (const Evas_Canvas *obj)
 Returns a handle to the list of lock keys registered in the canvas.
const Evas_Modifierevas_key_modifier_get (const Evas_Canvas *obj)
 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.
void evas_key_lock_on (Evas_Canvas *obj, const char *keyname)
 Enables or turns on programmatically the lock key with name keyname.
Evas_Modifier_Mask evas_key_modifier_mask_get (const Evas_Canvas *obj, const char *keyname)
 Creates a bit mask from the keyname modifier key. Values returned from different calls to it may be ORed together, naturally.
void evas_key_modifier_add (Evas_Canvas *obj, const char *keyname)
 Adds the keyname key to the current list of modifier keys.
void evas_key_modifier_off (Evas_Canvas *obj, const char *keyname)
 Disables or turns off programmatically the modifier key with name.
void evas_key_lock_off (Evas_Canvas *obj, const char *keyname)
 Disables or turns off programmatically the lock key with name keyname.
void evas_key_modifier_on (Evas_Canvas *obj, const char *keyname)
 Enables or turns on programmatically the modifier key with name keyname.
void evas_key_lock_del (Evas_Canvas *obj, const char *keyname)
 Removes the keyname key from the current list of lock keys on canvas e.
void evas_key_modifier_del (Evas_Canvas *obj, const char *keyname)
 Removes the keyname key from the current list of modifier keys on canvas e.
void evas_key_lock_add (Evas_Canvas *obj, const char *keyname)
 Adds the keyname key to the current list of lock keys.
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.
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.
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.
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.

Functions which feed key events to the canvas.

As explained in intro_not_evas, Evas is not aware of input systems at all. Then, the user, if using it crudely (evas_new()), will have to feed it with input events, so that it can react somehow. If, however, the user creates a canvas by means of the Ecore_Evas wrapper, it will automatically bind the chosen display engine's input events to the canvas, for you.

This group presents the functions dealing with the feeding of key events to the canvas. On most of them, one has to reference a given key by a name (keyname argument). Those are platform dependent symbolic names for the keys. Sometimes you'll get the right keyname by simply using an ASCII value of the key name, but it won't be like that always.

Typical platforms are Linux frame buffer (Ecore_FB) and X server (Ecore_X) when using Evas with Ecore and Ecore_Evas. Please refer to your display engine's documentation when using evas through an Ecore helper wrapper when you need the keynames.

Example:

All the other evas_key functions behave on the same manner. See the full Evas events (canvas and object ones) and some canvas operations example example.


Function Documentation

void evas_key_lock_add ( Evas_Canvas *  obj,
const char *  keyname 
)

Adds the keyname key to the current list of lock keys.

Since :
2.3
Remarks:
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 also:
evas_key_lock_get
evas_key_lock_del
evas_key_lock_on
evas_key_lock_off
evas_key_lock_is_set
Remarks:
If the programmer instantiates the canvas by means of the Ecore Evas New function family of helper functions, Ecore will take care of registering on it all standard lock keys: "Caps_Lock", "Num_Lock", "Scroll_Lock".
Parameters:
[in]objThe canvas object
[in]keynameThe name of the key to add to the locks list.
void evas_key_lock_del ( Evas_Canvas *  obj,
const char *  keyname 
)

Removes the keyname key from the current list of lock keys on canvas e.

Since :
2.3
See also:
evas_key_lock_get
evas_key_lock_add
evas_key_lock_on
evas_key_lock_off
Parameters:
[in]objThe canvas object
[in]keynameThe name of the key to remove from the locks list.
const Evas_Lock* evas_key_lock_get ( const Evas_Canvas *  obj)

Returns a handle to the list of lock keys registered in the canvas.

Since :
2.3

e. This is required to check for which locks are set at a given

Remarks:
time with the evas_key_lock_is_set() function.
See also:
evas_key_lock_add
evas_key_lock_del
evas_key_lock_on
evas_key_lock_off
evas_key_lock_is_set
Returns:
An .Evas_Lock handle to query Evas' keys subsystem with evas_key_lock_is_set(), or NULL on error.
Parameters:
[in]objThe canvas object
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.

Since :
2.3
Parameters:
[in]lThe current locks set, as returned by evas_key_lock_get().
[in]keynameThe name of the lock key to check status for.
Returns:
Eina_True if the keyname lock key is set, Eina_False otherwise.
See also:
evas_key_lock_get
evas_key_lock_add
evas_key_lock_del
evas_key_lock_on
evas_key_lock_off
void evas_key_lock_off ( Evas_Canvas *  obj,
const char *  keyname 
)

Disables or turns off programmatically the lock key with name keyname.

Since :
2.3
Remarks:
The effect will be as if the key was put on its inactive state after this call.
See also:
evas_key_lock_get
evas_key_lock_add
evas_key_lock_del
evas_key_lock_on
Parameters:
[in]objThe canvas object
[in]keynameThe name of the lock to disable.
void evas_key_lock_on ( Evas_Canvas *  obj,
const char *  keyname 
)

Enables or turns on programmatically the lock key with name keyname.

Since :
2.3
Remarks:
The effect will be as if the key was put on its active state after this call.
See also:
evas_key_lock_get
evas_key_lock_add
evas_key_lock_del
evas_key_lock_off
Parameters:
[in]objThe canvas object
[in]keynameThe name of the lock to enable.
void evas_key_modifier_add ( Evas_Canvas *  obj,
const char *  keyname 
)

Adds the keyname key to the current list of modifier keys.

Since :
2.3
Remarks:
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
Remarks:
If the programmer instantiates the canvas by means of the Ecore Evas New function family of helper functions, Ecore will take care of registering on it all standard modifiers: "Shift", "Control", "Alt", "Meta", "Hyper", "Super".
Parameters:
[in]objThe canvas object
[in]keynameThe name of the modifier key to add to the list of Evas modifiers.
void evas_key_modifier_del ( Evas_Canvas *  obj,
const char *  keyname 
)

Removes the keyname key from the current list of modifier keys on canvas e.

Since :
2.3
See also:
evas_key_modifier_add
evas_key_modifier_get
evas_key_modifier_on
evas_key_modifier_off
evas_key_modifier_is_set
Parameters:
[in]objThe canvas object
[in]keynameThe name of the key to remove from the modifiers list.
const Evas_Modifier* evas_key_modifier_get ( const Evas_Canvas *  obj)

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.

Since :
2.3
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.
Parameters:
[in]objThe canvas object
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.

Since :
2.3
Parameters:
[in]mThe current modifiers set, as returned by evas_key_modifier_get().
[in]keynameThe name of the modifier key to check status for.
Returns:
Eina_True if the modifier key named keyname is on, Eina_False otherwise.
See also:
evas_key_modifier_add
evas_key_modifier_del
evas_key_modifier_get
evas_key_modifier_on
evas_key_modifier_off
Evas_Modifier_Mask evas_key_modifier_mask_get ( const Evas_Canvas *  obj,
const char *  keyname 
)

Creates a bit mask from the keyname modifier key. Values returned from different calls to it may be ORed together, naturally.

Since :
2.3
Returns:
the bit mask or 0 if the keyname key wasn't registered as a modifier for canvas e.
Remarks:
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 also:
evas_key_modifier_add
evas_key_modifier_get
evas_key_modifier_on
evas_key_modifier_off
evas_key_modifier_is_set
evas_object_key_grab
evas_object_key_ungrab
Parameters:
[in]objThe canvas object
[in]keynameThe name of the modifier key to create the mask for.
void evas_key_modifier_off ( Evas_Canvas *  obj,
const char *  keyname 
)

Disables or turns off programmatically the modifier key with name.

Since :
2.3
Remarks:
keyname.
See also:
evas_key_modifier_add
evas_key_modifier_get
evas_key_modifier_on
evas_key_modifier_is_set
Parameters:
[in]objThe canvas object
[in]keynameThe name of the modifier to disable.
void evas_key_modifier_on ( Evas_Canvas *  obj,
const char *  keyname 
)

Enables or turns on programmatically the modifier key with name keyname.

Since :
2.3
Remarks:
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 also:
evas_key_modifier_add
evas_key_modifier_get
evas_key_modifier_off
evas_key_modifier_is_set
Parameters:
[in]objThe canvas object
[in]keynameThe name of the modifier to enable.
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.

Since :
2.3
Returns:
EINA_TRUE, if the call succeeded, EINA_FALSE otherwise.
Remarks:
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

Remarks:
pressed (see Key Input Functions for more information).

modifiers and not_modifiers are bit masks of all the

Remarks:
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

Remarks:
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.
Warning:
Providing impossible modifier sets creates undefined behavior
See also:
evas_object_key_ungrab
evas_object_focus_set
evas_object_focus_get
evas_key_modifier_add
Parameters:
[in]objThe evas object
[in]keynamethe key to request events for.
[in]modifiersa mask of modifiers that must be present to trigger the event.
[in]not_modifiersa mask of modifiers that must not be present to trigger the event.
[in]exclusiverequest that the obj is the only object receiving the keyname events.
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.

Since :
2.3
Remarks:
Removes a key grab on obj if keyname, modifiers, and not_modifiers match.
Example code follows.
See the full example here.
See also:
evas_object_key_grab
evas_object_focus_set
evas_object_focus_get
Parameters:
[in]objThe evas object
[in]keynamethe key the grab is set for.
[in]modifiersa mask of modifiers that must be present to trigger the event.
[in]not_modifiersa mask of modifiers that must not not be present to trigger the event.