PhEventEmit()

Emit an event

Synopsis:

int PhEventEmit( PhEvent_t const *event,
                 PhRect_t const *rects,
                 void const *data );

Library:

ph

Description:

This function emits the event described by the given PhEvent_t structure. PhEmit() does the same things as PhEventEmit(), but provides a cleaner API.

The rects argument points to an array of PhRect_t structures that define the rectangles associated with the event. If event->num_rects isn't 0, then rects must point to an array of event->num_rects valid rectangles.

The data argument points to variable-length event-specific data. If event->data_len isn't 0, then data must point to a buffer of at least event->data_len bytes.

If you set the collector ID (event->collector.rid) to zero, the event is enqueued to every appropriately sensitive region that intersects with the event. If you set collector.rid to a region ID, only that region notices the event.

The Photon library fills in the collector and translation fields in the PhEvent_t structure after a copy of the event is enqueued to an application.

Returns:

0
Success
-1
An error occurred, or no further events are pending. Check the value of errno:

These return codes are useful for applications that spend most of their time emitting events and want to retrieve an event only if there's one pending for them.

Examples:

The following example emits an expose event from the device region. Because the event covers the entire event space, any visible part of the event space is refreshed:

#include <stdio.h>
#include <time.h>
#include <Ph.h>

int main( int argc, char *argv[] )
{
     PhEvent_t event = { 0 };
     PhRect_t rect;

     if( NULL == PhAttach( NULL, NULL ) ) {
          fprintf( stderr,
                 "Couldn't attach Photon channel.\n");
          exit( EXIT_FAILURE );
     }
     event.type = Ph_EV_EXPOSE;
     event.subtype = 0;
     event.flags = 0;
     event.num_rects = 1;
     event.data_len = 0;
     event.emitter.rid = Ph_DEV_RID;
     rect.ul.x = rect.ul.y = SHRT_MIN;
     rect.lr.x = rect.lr.y = SHRT_MAX;
     PhEventEmit( &event, &rect, NULL );

     return EXIT_SUCCESS;
}

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PhEmit(), PhEmitmx(), PhEvent_t, PhEventEmitmx(), PhEventNext(), PhEventPeek(), PhEventRead(), PhRect_t, PtSendEventToWidget()

Emitting events in the Events chapter of the Photon Programmer's Guide.