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.

fields bit Argument Default
Ph_REGION_OWNER info->owner (you)
Ph_REGION_HANDLE info->handle 0
Ph_REGION_FLAGS info->flags 0
Ph_REGION_EV_OPAQUE info->events_opaque 0
Ph_REGION_EV_SENSE info->events_sense 0
Ph_REGION_ORIGIN info->origin {0, 0}
Ph_REGION_PARENT info->parent Ph_ROOT_RID
Ph_REGION_BEHIND info->bro_behind See PhRegion_t
Ph_REGION_IN_FRONT info->bro_in_front See PhRegion_t
Ph_REGION_RECT rect {{0, 0}, {0, 0}}
Ph_REGION_DATA info->data_len, data {0, 0}
Ph_REGION_CURSOR info->cursor_type, cursor_color 0 to inherit

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

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

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

Regions chapter of the Photon Programmer's Guide