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:

• If errno is ENOMSG, Photon had no messages enqueued to your application at the time you emitted the event.
• If errno isn't ENOMSG, an error occurred.

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

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.