Tutorial: Using screen_notify()

Graphics and Screen4.0 (8.x)Screen Graphics Subsystem Developer's GuideAPIProgrammingUtilities

The following procedure describes how an application can request an asynchronous notification from Screen for keyboard events.

You will learn to:

create a native context
establish a connection between your application and Screen
use a specific Screen object to filter for specific events
receive and handle a notification from Screen
disarm notification and release resources

Define your pulse code:

#define MY_PULSE_CODE _PULSE_CODE_MINAVAIL

Create variables for your Screen and a keyboard device:

screen_context_t screen_ctx = NULL;
screen_device_t  keyboard   = NULL;
screen_device_t* devices    = NULL;

Create a native context:

screen_create_context(&screen_ctx, SCREEN_APPLICATION_CONTEXT);

Set up your device object as a keyboard type:

int devcnt;
screen_get_context_property_iv(screen_ctx, SCREEN_PROPERTY_DEVICE_COUNT, &devcnt);
devices = malloc(devcnt*sizeof(void*));

screen_get_context_property_pv(screen_ctx, SCREEN_PROPERTY_DEVICES, (void**)devices);

int i=0;
int type;
for(; i<devcnt; i++)
{
   screen_get_device_property_iv(devices[i], SCREEN_PROPERTY_TYPE, &type);
   if (type == SCREEN_EVENT_KEYBOARD)
   {
      keyboard = devices[i];
   }
}

if (keyboard == NULL)
{
   printf("FATAL: Couldn't get keyboard device\n");
   exit(EXIT_FAILURE);
}

Events specific to a keyboard can be detected by passing the appropriate screen_device_t handle in the obj argument of screen_notify().

Establish a connection:

int chid = -1;
chid = ChannelCreate(0);
int coid = -1;
coid = ConnectAttach(0, 0, chid, _NTO_SIDE_CHANNEL, 0);

Request notification from Screen:

struct sigevent event;
SIGEV_PULSE_INIT(&event, coid, SIGEV_PULSE_PRIO_INHERIT, MY_PULSE_CODE, 0);
screen_register_event(screen_ctx, &event);
screen_notify(screen_ctx, SCREEN_NOTIFY_INPUT, keyboard, &event);

Check for receipt of notification:

while (1) {
   struct _pulse pulse;
   int rcvid = MsgReceivePulse(chid, &pulse, sizeof(pulse), NULL);
   if (rcvid == 0) {
      printf("keyboard input detected...\n");
   }
   ...
}

Disarm any further notifications of keyboard events from Screen in this context:
```
SIGEV_NONE_INIT(&event);
screen_notify(screen_ctx, SCREEN_NOTIFY_INPUT, keyboard, &event);
screen_unregister_event(&event);
free(devices);
```
Passing NULL or an event with the type of SIGEV_NONE disables notifications that were enabled with the same combination of arguments: ctx, flags, and obj.

Clean up your resources:

ConnectDetach(coid);
ChannelDestroy(chid);
screen_destroy_context(screen_ctx);

Page updated: March 05, 2025