Updated: April 19, 2023

Sessions are recipients of one specific type of input events.

Unlike windows, sessions don't produce any graphical content and can't be placed into groups. The only grouping that could be considered for a session is the one that's been established for the window that the session is associated with.

Input sessions (sessions) allow applications to control who gets what types of input events and how these input events are delivered. For each type of input event, there is a corresponding session type. Session types are defined by Screen session types. A session is created by calling screen_create_session_type() with the session type that you want to create. For example, here's how you'd create a keyboard session:

screen_session_t session;
screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
Sessions can be used to:

Logical input events are encapsulated by input sessions. An example of such input is text entry in a text field. A session could be created upon getting input focus in a text field and then destroyed when input focus is lost. Conversely, sessions can be created once and last for the lifetime of the application.

Simply creating a session is enough to affect how input events are delivered to your application. Sessions are created within a Screen API context. Sessions must be associated with a display, either through a window association, or through setting session's SCREEN_PROPERTY_DISPLAY property. When created, sessions receive, by default, all input events of the session's type. Your application can further refine a session's input events by specifying the input mode (SCREEN_PROPERTY_MODE) for the session. Refer to Screen input mode types for valid session modes.