PhRegionChange()

Change the definition of a region

Synopsis:

int PhRegionChange( unsigned long fields,
                    unsigned long flags,
                    PhRegion_t const *info,
                    PhRect_t const *rect,
                    void const *data );

Library:

ph

Description:

This function changes the definition of the region specified by info->rid. The fields argument describes which fields in the info structure are to be changed — for more information, see PhRegionOpen().

The rect argument points to a PhRect_t structure that defines the rectangle associated with the region, and data points to data associated with the region. If you don't specify the region's rectangle and data in the fields argument, you can set rect and data to NULL.

The data consists of one or more PhRegionDataHdr_t structures, each followed immediately by the appropriate type of data. This data is merged into any existing region data, replacing the blocks of the same types as given in data.

The flags argument controls whether or not an expose event will be emitted to this region, when necessary. You can OR the following into flags:

Ph_EXPOSE_REGION

If part of the region becomes exposed, send a Ph_EV_EXPOSE event to the region.

Ph_EXPOSE_FAMILY

If part of the region becomes exposed, send a Ph_EV_EXPOSE event to the region's descendants.

Returns:

A nonnegative value

Successful completion.

-1

An error occurred.

Examples:

#include <Pt.h>

typedef struct my_data_thing {
    PhRegionDataHdr_t hdr;
    char my_string[20];
    }MyData_t;

static void display_data( unsigned short type,
  PhRegion_t *region, PhRegionDataHdr_t *data)
{
  PhRegionDataHdr_t *data_hdr;
  if ((data_hdr = PhRegionDataFindType( region,
                                       data, type) )){
    MyData_t *regdata = (void *)data_hdr;
    printf ("data len: %d, content: %s\n",
            data_hdr->len, regdata->my_string);
  } else 
    printf ("No region data matching type found\n");
}
    
int main() {
  PtWidget_t *win;
  PhRegion_t region;
  char data[1000];
  MyData_t region_data;
  PhRid_t rid;    
    
  /* Initialize the photon widget library */
  PtInit (NULL);

  /* Create a nondescript window */
  win = PtCreateWidget (PtWindow, Pt_NO_PARENT, 0,
                        NULL);

  /* Realize it so it has a region */
  PtRealizeWidget (win);
  rid = PtWidgetRid (win);
    
  /* Populate the region_data struct */
  region_data.hdr.type = Ph_RDATA_USER;
  region_data.hdr.len = sizeof(region_data);  
  strcpy (region_data.my_string, "This is some data");

  region.data_len = region_data.hdr.len;
  region.rid = rid;
  PhRegionQuery (rid, &region, NULL,
                 (PhRegionDataHdr_t *)&data,
                 sizeof(data));

  /* Add the data to the region */
  region.data_len = region_data.hdr.len;
  region.rid = rid;
  PhRegionChange (Ph_REGION_DATA, 0, &region, NULL,
                  &region_data);

  /* Retrieve the data from the region */
  PhRegionQuery (rid, &region, NULL,
                 (PhRegionDataHdr_t *)&data,
                 sizeof(data));
  display_data (Ph_RDATA_USER, &region,
                (PhRegionDataHdr_t *)&data);

  /* Remove the data from the region */
  region_data.hdr.len = 0;
  PhRegionChange (Ph_REGION_DATA, 0, &region, NULL,
                  &region_data);

  /* Retrieve the data from the region */
  PhRegionQuery (rid, &region, NULL,
                 (PhRegionDataHdr_t *)&data,
                 sizeof(data));
  display_data (Ph_RDATA_USER, &region,
                (PhRegionDataHdr_t *)&data);
  return EXIT_SUCCESS;
}

Classification:

Photon

See also:

PhRect_t, PhRegion_t, PhRegionClose(), PhRegionDataHdr_t, PhRegionOpen(), PhRegionQuery()

Regions chapter of the Photon Programmer's Guide