Key Input Functions

Functions which feed key events to the canvas. More...

Functions

const Evas_Modifierevas_key_modifier_get (const Evas *e)
 Returns a handle to the list of modifier keys registered in the canvas e.
const Evas_Lockevas_key_lock_get (const Evas *e)
 Returns 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 the state of a given modifier key, at the time of the call.
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.
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.

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

Example:

   mods = evas_key_modifier_get(evas);
   if (evas_key_modifier_is_set(mods, "Control") &&
       (strcmp(ev->keyname, "o") == 0)) /* add an obscured
                                        * rectangle to the middle
                                        * of the canvas */
     {

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:
eThe pointer to the Evas canvas
keynameThe 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 also:
evas_key_lock_get
evas_key_lock_del
evas_key_lock_on
evas_key_lock_off
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:
eThe pointer to the Evas canvas
keynameThe 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

Referenced by evas_key_lock_add().

const Evas_Lock* evas_key_lock_get ( const Evas e)

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:
eThe pointer to the Evas canvas
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.
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:
lThe current locks set, as returned by evas_key_lock_get().
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 e,
const char *  keyname 
)

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

Parameters:
eThe pointer to the Evas canvas
keynameThe name of the lock to disable.

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
void evas_key_lock_on ( Evas e,
const char *  keyname 
)

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

Parameters:
eThe pointer to the Evas canvas
keynameThe name of the lock to enable.

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
void evas_key_modifier_add ( Evas e,
const char *  keyname 
)

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

Parameters:
eThe pointer to the Evas canvas
keynameThe 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:
eThe pointer to the Evas canvas
keynameThe 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:
eThe 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:
mThe current modifiers set, as returned by evas_key_modifier_get().
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 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:
eThe canvas whom to query the bit mask from.
keynameThe 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 canvas 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 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.

Parameters:
eThe pointer to the Evas canvas
keynameThe 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.

Parameters:
eThe pointer to the Evas canvas
keynameThe 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 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.

Parameters:
objthe object to direct keyname events to.
keynamethe key to request events for.
modifiersa mask of modifiers that must be present to trigger the event.
not_modifiersa mask of modifiers that must not be present to trigger the event.
exclusiverequest that the obj is the only object receiving the keyname 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.

        if (d.focus)
          {
             evas_object_focus_set(d.bg, EINA_FALSE);
             fprintf(stdout, "Focused object is now %s\n",
                     evas_focus_get(d.canvas) ?
                     "still valid! Something went wrong." : "none.");

             ret = evas_object_key_grab(d.bg, "a", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "c", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "d", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "f", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "p", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "o", mask, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
             ret = evas_object_key_grab(d.bg, "h", 0, 0, EINA_TRUE);
             if (!ret)
               {
                  fprintf(stdout, "Something went wrong with key grabs.\n");
                  goto c_end;
               }
          }
        else /* got here by key grabs */

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

Parameters:
objthe object that has an existing key grab.
keynamethe key the grab is set for.
modifiersa mask of modifiers that must be present to trigger the event.
not_modifiersa 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.

        else /* got here by key grabs */
          {
             evas_object_key_ungrab(d.bg, "a", 0, 0);
             evas_object_key_ungrab(d.bg, "c", 0, 0);
             evas_object_key_ungrab(d.bg, "d", 0, 0);
             evas_object_key_ungrab(d.bg, "f", 0, 0);
             evas_object_key_ungrab(d.bg, "p", 0, 0);
             evas_object_key_ungrab(d.bg, "o", mask, 0);
             evas_object_key_ungrab(d.bg, "h", 0, 0);

             evas_object_focus_set(d.bg, EINA_TRUE);
          }

See the full example here.

See also:
evas_object_key_grab
evas_object_focus_set
evas_object_focus_get
evas_focus_get