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.
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.
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:
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.
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. |
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.
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:
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.