PhEventEmit()

Emit an event

Synopsis:

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

Description:

This function emits an event. The event argument points to the PhEvent_t structure, rects points to an array of rectangles, and data points to variable-length event-specific data.

If event->num_rects isn't 0, then rects must point to an array of event->num_rects valid rectangles.

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 will cover the entire event space, any visible part of the event space will be 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:

PhEventEmitmx(), PhEventNext(), PhEventPeek(), PhEventRead(), PtSendEventToWidget()

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