Input sessions

Sessions allow apps to control how raw events are processed into higher-level events. A session allows your app to capture events that are specific to a certain region, device, or screen event type. For example, you can create a session when a text field receives input focus in order to capture text entry in that field, and then destroy the session upon losing input focus. Sessions aren't restricted to on-screen events. You can create sessions to capture off-screen events from joystick, gamepad, keyboard, mouse (or other pointing device), or off-screen touch inputs.

Input session types

You must specify a type when you create a session. Each session type corresponds to a screen event type.

The following are valid session types:
  • SCREEN_EVENT_GAMEPAD
  • SCREEN_EVENT_JOYSTICK (trackpad)
  • SCREEN_EVENT_KEYBOARD (physical keyboard and touch-screen keyboard)
  • SCREEN_EVENT_MTOUCH_TOUCH (touch-sensitive keyboard)
  • SCREEN_EVENT_POINTER

Create input sessions dynamically

One of the most straightforward ways to work with text input is to rely on input focus events, where you create a session when the following are true:

  • A click in a window is detected.
  • The click is in an area that has a text field.
  • Input focus is to the window.

With input sessions, you can either create and destroy the input sessions dynamically, or you can keep the session active all the time and change its mode if you want to start or stop directing input to it.

You create a session by calling screen_create_session_type(). For example, to create a session to capture keyboard events from the window specified by window, you use the following code:

screen_session_t session;
            
if (screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD) == 0)
{              
    if (screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void **)&window) == 0)
    {
        // Successfully set property
        ...
    } else {
       // Handle failure to set property
       ...
    }
} else {
    // Handle situation where session failed to be created
    ...
}

A session may be needed for the lifetime of the app, or it may be needed only for a brief period while input is captured in a field. In either case, once a session is no longer active, you must destroy it by calling screen_destroy_session().

if ((session_destroy_context(session) != 0)
{
    // Handle situation where session could not be destroyed
}

Similarly, you can destroy the session when a click is detected outside of the text field or an event is received indicating that the window has lost input focus.

Alternatively, you can create an input region that matches the text field:

screen_session_t session;
screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
screen_set_property_pv(session, SCREEN_PROPERTY_WINDOW, (void **)&window);
screen_set_property_iv(session, SCREEN_PROPERTY_POSITION, pos);
screen_set_property_iv(session, SCREEN_PROPERTY_SIZE, size);

Change session mode

Rather than creating and destroying sessions as fields gain and lose focus, you may instead want to create a session and keep it active at all times, changing the session's mode upon entering and leaving text fields.

Create a session the same way as when dynamically creating your sessions:

screen_session_t session;
screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW,

Upon entering a text field, set the input mode to text:

int mode = SCREEN_INPUT_MODE_TEXT_ENTRY;
screen_set_session_property_iv(session, SCREEN_PROPERTY_MODE, &mode);

Upon leaving a text field, set the input mode to navigation:

int mode = SCREEN_INPUT_MODE_NAVIGATION;
screen_set_session_property_iv(session, SCREEN_PROPERTY_MODE, &mode);

Last modified: 2015-03-31



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus