Screen API session properties are the properties of a session API object; some session properties are only applicable to certain session types.
Similar to other Screen API objects, session properties are accessed through the get (screen_get_session_property_*() )and set (screen_set_session_property_*()) functions.
The following are specific session properties that are used to control when and how events are received:
These properties, together, help you control what events you want to receive. See Screen property types for more information on each specific property.
A session's SCREEN_PROPERTY_VISIBLE property indicates whether the session is active or not. This property is inherited from the window it's associated with. If a session isn't directly associated with a window, it depends on your working context. Privileged contexts (e.g., SCREEN_WINDOW_MANAGER_CONTEXT) can maintain windowless sessions that are active all the time. Windowless sessions can be created within non-privileged contexts (e.g., SCREEN_APPLICATION_CONTEXT), but their active state is dependent on the visibility of the windows that are in the context. Sessions in non-privileged contexts are only active if at least one window in those contexts is visible.
Set the SCREEN_PROPERTY_WINDOW session property when you want to restrict a session to a particular window, or to specify an input region that's relative to a window.
Events that are a result of indirect input devices must have an associated window (i.e., the SCREEN_PROPERTY_WINDOW property is set for the session). Events that are focus-based (from indirect input) are:
That being said, this implies that the only sessions that don't need a window association are pointer (SCREEN_EVENT_POINTER) and touch (SCREEN_EVENT_MTOUCH_TOUCH) sessions.
Several sessions of the same or different types can be associated with a single window. When there are multiple sessions of the same type associated with the same window, then the z-order (SCREEN_PROPERTY_ZORDER) of the sessions come into play in the decision of who gets the input event of that type. The session with the highest z-order receives the input event. Should there be a tie in the z-order, the most recently created session receives the event.
The input region is a well-defined region where the focus of the input event is targeted. The size of this region is constrained to the size of the associated window or the display. The region's size and position are always relative to those of the window. This input region can be specified by setting the following pair of properties:
Set the SCREEN_PROPERTY_DISPLAY session property when you want to explicitly associate a session with a display.
Sessions are indirectly associated with a display through their associated window. By default, the session display is set to be the same as its associated window display; if there isn't an associated window, a default display is assigned. It is an error to set this property if your session is associated with a window.