Keyboard sessions

Keyboard input sessions are created with the type SCREEN_EVENT_KEYBOARD and can be associated with none, one, or multiple devices that potentially generate these types of input events.

Modes

A keyboard session's SCREEN_PROPERTY_MODE can be set to one of the following:

SCREEN_INPUT_MODE_TEXT_ENTRY
Used for text entry. For example, you can specify a keyboard mapping based on input locale for a particular text field.
SCREEN_INPUT_MODE_NAVIGATION
Used to navigate. For example, some of letters can be remapped to be used as directional arrows, or used as shortcuts.
SCREEN_INPUT_MODE_SELECTION
For a physical keyboard, this mode is similar to the navigation mode. For a virtual keyboard, it may show selection handles which can then be handled with this specific mode.

The purpose of the mode is to be propagated to the input manager through the SCREEN_EVENT_PROPERTY. The mode doesn't really affect the way key events are sent. It ultimately won't do anything unless your application has privileged context. After having said that, the SCREEN_PROPERTY_MODE property of a window is equivalent to the mode of a keyboard session. This means that, depending on your application, you don't really need to create a separate keyboard session because you can just rely on the window's mode. However, if you're using a virtual keyboard, one reason for creating a keyboard session is to control the color of the virtual keyboard. For example: 

...
int color = dark ? 0 : ~0;
screen_set_session_property_iv(session, SCREEN_PROPERTY_COLOR, &color);
...

Setting the color of the keyboard session changes the look of the virtual keyboard. For example, if your application is predominately white, you can use a darker color for the virtual keyboard to provide better contrast.

Text entry

A keyboard session can be created and its input mode can be changed to indicate whether the input events from the keyboard are being used for text entry or for another purpose. The following code snippets show how a keyboard session can be used for text entry:

  1. Create a keyboard session and associate it with the window where the input focus is to be directed: 
    ...
screen_session_t session;
screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void**) &window);
...
  2. Set the session's input mode to be for text entry: 
                    ...
int mode = SCREEN_INPUT_MODE_TEXT_ENTRY;
screen_set_session_property_iv(session, SCREEN_PROPERTY_MODE, &mode);
                ...
  3. Reset the session's input mode when leaving text entry: 
    ...
int mode = SCREEN_INPUT_MODE_NAVIGATION;
screen_set_session_property_iv(session, SCREEN_PROPERTY_MODE, &mode);
...

You can also specify a specific input region in your window that matches the text field: 

...
screen_session_t session;
int mode = SCREEN_INPUT_MODE_TEXT_ENTRY;
screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
screen_set_session_property_iv(session, SCREEN_PROPERTY_MODE, &mode);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void**) &window);
screen_set_session_property_iv(session, SCREEN_PROPERTY_POSITION, pos);
screen_set_session_property_iv(session, SCREEN_PROPERTY_SIZE, size);
...