Text input

There are several ways that you use sessions to handle text input in your app. This section provides an overview of those methods.

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.

Use the following code to create a session when entering a text field:

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

Similarly, 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.

Use the following code to destroy a session when leaving a text field:

            screen_destroy_session(session);

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);