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.

The collector and translation fields in the PhEvent_t structure are filled in only 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>

main( int argc, char *argv[] )
{
     PhEvent_t event;
     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;
     rect.ul.x = rect.ul.y = SHRT_MIN;
     rect.lr.x = rect.lr.y = SHRT_MAX;
     PhEventEmit( &event, &rect, NULL );
}

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.