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
SCREEN_EVENT_KEYBOARD
SCREEN_EVENT_MTOUCH_TOUCH
SCREEN_EVENT_POINTER

Creating an input session

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

Destroying an input session

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().

Destroy an input session using the following code:

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

Touch device input

Not all input comes from the screen. For example, you might want to receive input from an off-screen device, which is not associated with any window.

You can get input from off-screen devices by using a SCREEN_EVENT_MTOUCH_EVENT session. The following code samples demonstrate how to create such sessions for capturing both off-screen and on-screen touch events.

You can receive touch events from all devices by creating a SCREEN_EVENT_MTOUCH_TOUCH session that's not bound to any window, also known as a windowless session, as follows:

            screen_session_t session;
            screen_create_session_type(&session, context, SCREEN_EVENT_MTOUCH_TOUCH);

Alternatively, if you want your app to receive data only from devices that are on-screen, you can create the session and bind it to a window as follows:

            screen_session_t session;
            screen_create_session_type(&session, context, SCREEN_EVENT_MTOUCH_TOUCH);
            screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void **)&window);

You can use the various screen_get_session_property_*() functions to get information from the SCREEN_EVENT_MTOUCH_TOUCH events. Some properties that may be of interest are:

SCREEN_PROPERTY_TOUCH_ID
SCREEN_PROPERTY_POSITION
SCREEN_PROPERTY_SOURCE_POSITION
SCREEN_PROPERTY_SIZE
SCREEN_PROPERTY_TOUCH_ORIENTATION
SCREEN_PROPERTY_TOUCH_PRESSURE
SCREEN_PROPERTY_TIMESTAMP
SCREEN_PROPERTY_SEQUENCE_ID

Alternatively, you can use the Input Events library to retrieve information from a touch event. You can use screen_get_mtouch_event() to retrieve information from an mtouch_event structure that was populated as the result of a SCREEN_EVENT_MTOUCH_EVENT event.