Asynchronous Notifications

Applications can request to be asynchronously notified of specific Screen
events by way of a sigevent.

For multithreaded applications, all event handling can be directed to one thread through the use of
asynchronous notifications. When all the event handling for an application is performed by one thread,
it's easier to synchronize tasks and to ensure that certain tasks are performed in the correct order.

Use the function screen_notify() to enable
notifications of specific events from Screen. When you want to
disable notifications, call screen_notify()
a second time in your application for the context, notification type, and object handle that you want to
disable notifications for. Set the event parameter to NULL, or the
sigevent
type to SIGEV_NONE in the call to disable notifications.

Your application can request to receive notifications upon occurrence of the following:

A content update

Use the notification type of SCREEN_NOTIFY_UPDATE when you want to receive
notifications that a framebuffer refresh or a post (e.g., a call to
screen_post_window()) has occurred.

The following table shows the Screen API objects that are valid for this
notification type and when you would receive a notification from Screen:

Screen API object

Screen notifies you when:

Display

Screen completes composition, and a refresh of
the framebuffer is required.

Stream

the function screen_post_stream()
has been called with the stream object that you registered for this notification type.

Window

the function screen_post_window()
has been called with the window object that you registered for this
notification type.

Use the notification type of SCREEN_NOTIFY_INPUT when you want to receive
notifications that an event from a display or an input device has occurred.

The following table shows the Screen API objects that are valid for this
notification type and when you would receive a notification from Screen:

Screen API object

Screen notifies you when:

Device

the specified device is active (i.e., sending input). If desired, you can
filter these notifications so that it receives only notifications that are of
interest to you. Filtering is done by passing the appropriate handle as an
argument to screen_notify().

For example, if you want to receive notifications of events pertaining to a
keyboard, then pass the appropriate screen_device_t handle
(the handle to your keyboard device) to
screen_notify().

Note:
When you receive a notification for input, it's an indication that there's
input activity on the device for Screen to
process. However, it isn't necessarily an indication that there's an event
corresponding to your input device in your context's event queue.

Display

there's input that's being targeted for the specified display.

Note:
When you register for notifications of type SCREEN_NOTIFY_INPUT with a
NULL object (i.e., passing NULL as the obj parameter in
screen_notify()), then you
receive notifications when any input device is active (i.e., sending input).

A property change occurred or an event has been queued

Use the notification type of SCREEN_NOTIFY_EVENT when you want to receive
notifications that an event is available in your contexts's event queue or that a property
of the specified object has been changed.

Property change notifications and events

If you request property change events, note that although notifications are generated
for all property changes, not all properties that change generate an event
(SCREEN_EVENT_PROPERTY). That is, some properties that are changed
cause only a notification to be generated, while some cause both a notification and
an event to be generated. For the latter, once your application receives the
notification of the property change, it can call
screen_get_event() to
get the event from your context's event queue and retrieve the property that's been
changed along with any data that might be associated with it. See
Screen property types
to determine which property triggers Screen to send
a SCREEN_EVENT_PROPERTY event.

The following Screen API objects are valid for registering for
property changes:

Device

Group

Pixmap

Session

Stream

Window

Event(s) queued

When you register for notifications of type SCREEN_NOTIFY_EVENT with a
NULL object (i.e., passing NULL as the obj parameter in
screen_notify()), then you
receive notifications when there's any type of event that's enqueued to your
context's event queue. You may receive any of the event types
(Screen event types
) that's applicable to your context in the event queue.

You can call screen_get_event()
to get the event from the queue and retrieve the property that's been changed along
with any data that might be associated with it.

You can enable notifications for different notifications types, or the same notification type, but for a
different handle. In the following example, the second call to
screen_notify() doesn't affect the first since
it specifies a different object handle.