This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PhRegionOpen()

Open a region

Synopsis:

PhRid_t PhRegionOpen( unsigned fields,
                      PhRegion_t const *info,
                      PhRect_t const *rect,
                      void const *data );

Library:

ph

Description:

This function opens a new region. The fields argument describes which members specified by info will be used. If some fields aren't specified, the function sets the corresponding members of the new region to their defaults.

The info argument points to a PhRegion_t structure that defines a template region used when opening the new region. You must set the parent member of info; Photon fills in the other family members.

The rect argument points to a PhRect_t structure that defined the rectangle associated with the region, and data points to the data associated with the region.

Returns:

A positive region ID, or -1 if an error occurred.

Examples:

The following example opens a region out of the root region. The new region will sense any mouse motion events that pass through it, and draw a rectangle at the current position of the pointer. If the user clicks in the region, the program will terminate. If a window manager is running, this region will be in front of the window manager. The window manager won't be aware of the region.

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

PhRid_t open_region( void )
{
    PhRegion_t region;
    PhRect_t rect;
    PhRid_t rid;

    memset(&region, 0, sizeof(region));
    /* Wish to have pointer motion
     * events enqueued to us.
     */
    region.events_sense = Ph_EV_PTR_MOTION | 
                          Ph_EV_BUT_RELEASE;

    /* Wish to be opaque to all pointer-type
     * events and be visually opaque.
     */
    region.events_opaque = Ph_EV_PTR_ALL | Ph_EV_DRAW | 
                           Ph_EV_EXPOSE;
    /* Origin at (100,100) relative to root */
    region.origin.x = region.origin.y = 100;
    region.parent = Ph_ROOT_RID;
    /* Open region from (absolute) (100,100) 
       to (300,300) */
    rect.ul.x = rect.ul.y = 0;
    rect.lr.x = rect.lr.y = 200;

    rid = PhRegionOpen( Ph_REGION_PARENT |
                        Ph_REGION_EV_SENSE |
                        Ph_REGION_EV_OPAQUE |
                        Ph_REGION_ORIGIN |
                        Ph_REGION_RECT,
                        &region, &rect, NULL );

    /* If open was successful, black out the region */
    if( rid != -1 ) {
        PgSetRegion( rid );
        PgSetFillColor( Pg_BLACK );
        PgDrawRect( &rect, Pg_DRAW_FILL );
        PgFlush();
    }
    return( rid );
}

void draw_at_cursor( PhPoint_t *pos )
{
    PhRect_t rect;
    static int count = 0;

    rect.ul.x = pos->x - 10;
    rect.ul.y = pos->y - 10;
    rect.lr.x = pos->x + 10;
    rect.lr.y = pos->y + 10;
    switch( ++ count % 3 ) {
    case 0:
        PgSetFillColor( Pg_RED );
        break;
    case 1:
        PgSetFillColor( Pg_GREEN );
        break;
    default:
        PgSetFillColor( Pg_BLUE );
    }
    PgDrawRect( &rect, Pg_DRAW_FILL );
    PgFlush();
}

int main( int argc, char *argv[] )
{
    PhEvent_t *event;
    int go = 1;

    if( NULL == PhAttach( NULL, NULL ) ) {
        fprintf( stderr, "Couldn't attach a "
                         "Photon channel.\n" );
        exit( EXIT_FAILURE );
    }

    if( -1 == open_region() ) {
        fprintf( stderr, "Couldn't open region.\n" );
        exit( EXIT_FAILURE );
    }
    event = (PhEvent_t *)malloc( sizeof( PhEvent_t ) 
                                 + 1000 );
    if( event == NULL ) {
        fprintf( stderr,
                 "Couldn't allocate event buffer.\n" );
        exit( EXIT_FAILURE );
    }
    while( go ) {
        if( PhEventNext( event, sizeof( PhEvent_t )
                   + 1000 ) == Ph_EVENT_MSG ) {
            if( (event->type & Ph_EV_PTR_MOTION) != 0 )
                draw_at_cursor(
                   (PhPoint_t *)PhGetRects( event ) );
            else
                go = 0;
        } else
            fprintf( stderr, "Error.\n" );
    }

    return 0;
}

Classification:

Photon

See also:

PgGetRegion(), PgSetRegion(), PhAttach(), PhRect_t, PhRegion_t, PhRegionChange(), PhRegionClose()

Regions chapter of the Photon Programmer's Guide