Input session properties

Session properties are used to control when and how events are generated. Certain properties may only be relevant to some event types, while others are applicable to all types of sessions.

You can use the following functions to set and get session properties:
  • screen_set_session_property_cv()
  • screen_set_session_property_iv()
  • screen_set_session_property_llv()
  • screen_set_session_property_pv()
  • screen_get_session_property_cv()
  • screen_get_session_property_iv()
  • screen_get_session_property_llv()
  • screen_get_session_property_pv()

You must ensure that your session was created successfully before using any of the set/get functions.

The window property

A session indicates an interest in a certain type of input event, which does not need to be associated with a window. For example, an app may not have any windows, or you may want the session to be applicable to any window that the app owns. In either of these cases, the session would not be associated with a particular window.

You may want to restrict a session to a particular window or to specify an input region relative to a window. In these cases, you can set the property SCREEN_PROPERTY_WINDOW for the session.

The following code sample shows how to restrict a session to the window specified by window: 

            screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void **)&window);

Input regions

An input region is an input session that has a well-defined region. The region is a rectangle that is defined by its position and size. You can specify the position either relative to a window or by using absolute display coordinates. The region defines the bounds of where input will be captured within a window. For example, you might create an input region to capture keyboard input in a specific area of a window, such as a text field.

The following code sample demonstrates how to set up an input region: 

            screen_session_t session;
            screen_create_session_type(&session, context, SCREEN_EVENT_KEYBOARD);
            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);