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.

Note: Before you can call screen_notify(), you must call screen_register_event() to register a sigevent that screen_notify() uses.

When you are no longer using asynchronous notifications, you need to disable the notifications and then remove the event registration. We recommend that you call screen_unregister_event() only after you've disabled asynchronous notifications that are using the event you're unregistering. If you remove the event registration while you still have asynchronous notifications using that event enabled, you may not receive any notifications. To disable asynchronous notifications, call screen_notify() with the event argument set to NULL, or its type set to SIGEV_NONE for those notifications that were enabled.

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.

You can enable notifications for different notification types, or for 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.

screen_notify(screen_ctx, SCREEN_NOTIFY_INPUT, keyboard, &event);
screen_notify(screen_ctx, SCREEN_NOTIFY_INPUT, mouse, &event);
        

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.

You'll still receive SCREEN_EVENT_POST events in your context's event queue when applicable.

An input event from a device

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 context'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

Register for notifications of type SCREEN_NOTIFY_EVENT with a NULL object (i.e., passing NULL as the obj parameter in screen_notify()) when you want to receive notifications that there are events in your context's event queue. You receive one notification for each event that's residing in your context's event queue (i.e., one notification for each event that you can call screen_get_event() to retrieve).

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.