This group provides functions which feed key events to the canvas.

Evas is not aware of input systems at all. Then, the user, if using it crudely (evas_new()), has 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 automatically binds 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 get the right keyname by simply using an ASCII value of the key name, but it is not 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.

Functions
const Evas_Modifier *	evas_key_modifier_get (const Evas *e)
	Gets a handle to the list of modifier keys registered in the canvas e.
const Evas_Lock *	evas_key_lock_get (const Evas *e)
	Gets a handle to the list of lock keys registered in the canvas e.
Eina_Bool	evas_key_modifier_is_set (const Evas_Modifier m, const char keyname)
	Checks whether a given modifier key is set at the time of the call.
Eina_Bool	evas_key_lock_is_set (const Evas_Lock l, const char keyname)
	Checks whether the given lock key is set at the time of the call.
void	evas_key_modifier_add (Evas e, const char keyname)
	Adds the keyname key to the current list of modifier keys.
void	evas_key_modifier_del (Evas e, const char keyname)
	Removes the keyname key from the current list of modifier keys on canvas e.
void	evas_key_lock_add (Evas e, const char keyname)
	Adds the keyname key to the current list of lock keys.
void	evas_key_lock_del (Evas e, const char keyname)
	Removes the keyname key from the current list of lock keys on canvas e.
void	evas_key_modifier_on (Evas e, const char keyname)
	Enables or turns on programmatically the modifier key with name keyname.
void	evas_key_modifier_off (Evas e, const char keyname)
	Disables or turns off programmatically the modifier key with name keyname.
void	evas_key_lock_on (Evas e, const char keyname)
	Enables or turns on programmatically the lock key with name keyname.
void	evas_key_lock_off (Evas e, const char keyname)
	Disables or turns off programmatically the lock key with name keyname.
Evas_Modifier_Mask	evas_key_modifier_mask_get (const Evas e, const char keyname)
	Creates a bit mask from the keyname modifier key.
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.

Function Documentation

void evas_key_lock_add	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Remarks:: Locks are keys like caps lock, num lock or scroll lock, that is, 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().

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the key to add to the locks list

See also:: evas_key_lock_get; evas_key_lock_del; evas_key_lock_on; evas_key_lock_off; evas_key_lock_is_set

void evas_key_lock_del	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the key to remove from the locks list

See also:: evas_key_lock_get; evas_key_lock_add; evas_key_lock_on; evas_key_lock_off

const Evas_Lock* evas_key_lock_get ( const Evas * e )

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

Since :: 2.3.1

Remarks:: This is required to check for which locks are set at a given time with the evas_key_lock_is_set() function.

Parameters:

[in] e The pointer to the Evas canvas

Returns:: An Evas_Lock handle to query Evas' keys subsystem with evas_key_lock_is_set(),
otherwise NULL on error

See also:: evas_key_lock_add; evas_key_lock_del; evas_key_lock_on; evas_key_lock_off; evas_key_lock_is_set

Eina_Bool evas_key_lock_is_set	(	const Evas_Lock *	l,
		const char *	keyname
	)

Checks whether the given lock key is set at the time of the call.

Since :: 2.3.1

Remarks:: If the lock is set, such as caps lock, this function returns Eina_True.

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,
otherwise Eina_False if the lock key is not set

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 *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Remarks:: The effect is as if the key is put on its inactive state after this call.

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the lock to disable

See also:: evas_key_lock_get; evas_key_lock_add; evas_key_lock_del; evas_key_lock_on

void evas_key_lock_on	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Remarks:: The effect is as if the key is put on its active state after this call.

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the lock to enable

See also:: evas_key_lock_get; evas_key_lock_add; evas_key_lock_del; evas_key_lock_off

void evas_key_modifier_add	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Remarks:: Modifiers are keys like shift, alt and ctrl, that is, keys which are meant to be pressed together with others, altering the behavior of the secondly pressed keys somehow. Evas allows these keys to 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().

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the modifier key to add to the list of Evas modifiers

See also:: evas_key_modifier_del; evas_key_modifier_get; evas_key_modifier_on; evas_key_modifier_off; evas_key_modifier_is_set

void evas_key_modifier_del	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	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

const Evas_Modifier* evas_key_modifier_get ( const Evas * e )

Gets a handle to the list of modifier keys registered in the canvas e.

Since :: 2.3.1

Remarks:: This is required to check for which modifiers are set at a given time with the evas_key_modifier_is_set() function.

Parameters:

[in] e The pointer to the Evas canvas

Returns:: An Evas_Modifier handle to query Evas' keys subsystem with evas_key_modifier_is_set(),
otherwise NULL on error

See also:: evas_key_modifier_add; evas_key_modifier_del; evas_key_modifier_on; evas_key_modifier_off; evas_key_modifier_is_set

Eina_Bool evas_key_modifier_is_set	(	const Evas_Modifier *	m,
		const char *	keyname
	)

Checks whether a given modifier key is set at the time of the call.

Since :: 2.3.1

Remarks:: If the modifier is set, such as shift being pressed, this function returns Eina_True.

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,
otherwise EINA_FALSE if the modifier key is not on

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 *	e,
		const char *	keyname
	)

Creates a bit mask from the keyname modifier key.

Since :: 2.3.1

Remarks:: Values returned from different calls to it may be ORed together, naturally.; This function is meant to be used in conjunction with evas_object_key_grab()/evas_object_key_ungrab(). See their documentation for more information.

Parameters:

[in]	e	The canvas to query the bit mask from
[in]	keyname	The name of the modifier key to create the mask for

Returns:: The bit mask or 0 if the keyname key is not registered as a modifier for canvas e

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

void evas_key_modifier_off	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the modifier to disable

See also:: evas_key_modifier_add; evas_key_modifier_get; evas_key_modifier_on; evas_key_modifier_is_set

void evas_key_modifier_on	(	Evas *	e,
		const char *	keyname
	)

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

Since :: 2.3.1

Remarks:: The effect is as if the key is pressed for the whole time between this call and a matching evas_key_modifier_off().

Parameters:

[in]	e	The pointer to the Evas canvas
[in]	keyname	The name of the modifier to enable

See also:: evas_key_modifier_add; evas_key_modifier_get; evas_key_modifier_off; evas_key_modifier_is_set

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.1

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 gets 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 must not, 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 makes 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 it fails, unless the key is ungrabbed again.; Providing impossible modifier sets creates undefined behavior.

Parameters:

[in]	obj	The object to direct keyname events to
[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	Set EINA_TRUE to request that the obj is the only object receiving the keyname events, otherwise set EINA_FALSE

Returns:: EINA_TRUE if the call succeeded,
otherwise EINA_FALSE on failure

See also:: evas_object_key_ungrab; evas_object_focus_set; evas_object_focus_get; evas_key_modifier_add

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.1

Remarks:: Removes a key grab on obj if keyname, modifiers, and not_modifiers match.

Parameters:

[in]	obj	The object that has an existing key grab
[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 be present to trigger the event

See also:: evas_object_key_grab; evas_object_focus_set; evas_object_focus_get

Functions

Function Documentation