Functions
const Evas_Lock *	evas_key_lock_get (const Evas_Canvas *obj)
	Returns a handle to the list of lock keys registered in the canvas.
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.
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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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] obj The 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]	l	The current locks set, as returned by evas_key_lock_get().
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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] obj The 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]	m	The current modifiers set, as returned by evas_key_modifier_get().
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The canvas object
[in]	keyname	The 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]	obj	The evas object
[in]	keyname	the key to request events for.
[in]	modifiers	a mask of modifiers that must be present to trigger the event.
[in]	not_modifiers	a mask of modifiers that must not be present to trigger the event.
[in]	exclusive	request 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]	obj	The evas object
[in]	keyname	the key the grab is set for.
[in]	modifiers	a mask of modifiers that must be present to trigger the event.
[in]	not_modifiers	a mask of modifiers that must not not be present to trigger the event.