Regions

Creating and Painting Regions

A region is a combination of rectangles. Regions may be used to approximate complex objects, not unlike integration uses rectangles to calculate the area under a curve. For example, an arbitrary path may be converted to a region. Like pens and brushes, regions are separate graphics objects.

The following functions may be used to create a region.

create_rectangular_region	Creates a rectangular region.
create_elliptic_region	Creates an elliptic region.
create_rounded_rectangular_region	Creates a region consisting of an elliptically rounded rectangle.
create_polygonal_region	Creates a region consisting of a polygon.
create_polypolygonal_region	Creates a region consisting of a sequence of polygons.
path_to_region	Constructs a region from the path of a device context.
extended_create_region	Creates a region given explicit region data.

Regions may be destroyed using the function delete_object

The function combine_region is a powerful function by virtue of its variety. It gives rise to a number of operations including union, intersection, symmetric difference and subtraction.

Functions that render regions are:

fill_region	Fills a region.
frame_region	Frames a region.
invert_region	Inverts a region.
paint_region	Paints a region using the current brush.

Clipping With Rectangles and Regions

Regions are also used for clipping. Selecting a region into a device context with the function select_clipping_region causes the region to become the current clipping region. The operating system takes a copy of the region, so that the region used may be subsequently deleted. When a region is made the clipping region, all graphics sent to the device context is clipped to that region (where, portions of the graphics that lie outside the region are not displayed). Three functions that affect the clipping region are:

• exclude_clipping_rectangle,
• intersect_clipping_rectangle and
• offset_clipping_region.

A region may be used to invalidate a portion of a window via the function invalidate_region. Invalidating a region causes the generation of a paint message. A region of a window may be validated via function validate_region.

The Clover Program

The clover program demonstrates the use of regions and its output is shown below.

The clover program forms a region using four ellipses. A series of lines is then rendered, subject to the given region being the clipping region. The clipping region is formed as shown below.

handle region_array[6];

region_array[0] = create_elliptic_region(0,
                                      height_of_client/3,
                                      width_of_client/2,
                                      2*height_of_client/3);

region_array[1] = create_elliptic_region(width_of_client/2,
                                      height_of_client/3,
                                      width_of_client,
                                      2*height_of_client/3);

region_array[2] = create_elliptic_region(width_of_client/3,
                                      0,
                                      2*width_of_client/3,
                                      height_of_client/2);

region_array[3] = create_elliptic_region(width_of_client/3,
                                      height_of_client/2,
                                      2*width_of_client/3,
                                      height_of_client);

region_array[4] = create_rectangular_region(0,0,1,1);
region_array[5] = create_rectangular_region(0,0,1,1);

data->clipping_region = create_rectangular_region(0,0,1,1);

combine_region(region_array[4],region_array[0],region_array[1],region_combine::or);
combine_region(region_array[5],region_array[2],region_array[3],region_combine::or);
combine_region(clipping_region,region_array[4],region_array[5],region_combine::exclusive_or);

Once the clipping region has been set, the statement

for (double angle=0; angle<TwoPi; angle+=TwoPi/360)
 {
  move_to(device_context,0,0);
  draw_line_to(device_context,(int)( radius * cos(angle) + 0.5),
                           (int)(-radius * sin(angle) + 0.5));
 }

draws lines from the center of the client (at 1 degree intervals) subject to the clipping region.