GDK Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# Points, Rectangles and Regions

## Name

Points, Rectangles and Regions -- simple graphical data types.

## Synopsis

    #include <gdk/gdk.h>

    struct      GdkPoint;

    struct      GdkRectangle;
    gint        gdk_rectangle_intersect         (GdkRectangle *src1,
                                                 GdkRectangle *src2,
                                                 GdkRectangle *dest);
    void        gdk_rectangle_union             (GdkRectangle *src1,
                                                 GdkRectangle *src2,
                                                 GdkRectangle *dest);

    struct      GdkRegion;
    GdkRegion*  gdk_region_new                  (void);
    GdkRegion*  gdk_region_polygon              (GdkPoint *points,
                                                 gint npoints,
                                                 GdkFillRule fill_rule);
    enum        GdkFillRule;
    void        gdk_region_destroy              (GdkRegion *region);

    GdkRegion*  gdk_regions_intersect           (GdkRegion *source1,
                                                 GdkRegion *source2);
    GdkRegion*  gdk_regions_union               (GdkRegion *source1,
                                                 GdkRegion *source2);
    GdkRegion*  gdk_regions_subtract            (GdkRegion *source1,
                                                 GdkRegion *source2);
    GdkRegion*  gdk_regions_xor                 (GdkRegion *source1,
                                                 GdkRegion *source2);
    GdkRegion*  gdk_region_union_with_rect      (GdkRegion *region,
                                                 GdkRectangle *rect);
    void        gdk_region_offset               (GdkRegion *region,
                                                 gint dx,
                                                 gint dy);
    void        gdk_region_shrink               (GdkRegion *region,
                                                 gint dx,
                                                 gint dy);

    gboolean    gdk_region_empty                (GdkRegion *region);
    gboolean    gdk_region_equal                (GdkRegion *region1,
                                                 GdkRegion *region2);
    gboolean    gdk_region_point_in             (GdkRegion *region,
                                                 int x,
                                                 int y);
    GdkOverlapType gdk_region_rect_in           (GdkRegion *region,
                                                 GdkRectangle *rect);
    enum        GdkOverlapType;
    void        gdk_region_get_clipbox          (GdkRegion *region,
                                                 GdkRectangle *rectangle);

## Description

GDK provides the GdkPoint, GdkRectangle and GdkRegion data types for representing pixels and sets of pixels on the screen.

GdkPoint is a simple structure containing an x and y coordinate of a point.

GdkRectangle is a structure holding the position and size of a rectangle. The intersection of two rectangles can be computed with gdk_rectangle_intersect(). To find the union of two rectangles use gdk_rectangle_union().

GdkRegion is an opaque data type holding a set of arbitrary pixels, and is usually used for clipping graphical operations (see gdk_gc_set_clip_region()).

## Details

### struct GdkPoint

    struct GdkPoint
    {
      gint16 x;
      gint16 y;
    };

Defines the x and y coordinates of a point. Note that both are defined as gint16 values, so the coordinates are limited to between -32,768 and 32,767.

gint16 `x` | the x coordinate of the point.
gint16 `y` | the y coordinate of the point.

### struct GdkRectangle

    struct GdkRectangle
    {
      gint16 x;
      gint16 y;
      guint16 width;
      guint16 height;
    };

Defines the position and size of a rectangle.

gint16 `x` | the x coordinate of the left edge of the rectangle.
gint16 `y` | the y coordinate of the top of the rectangle.
guint16 `width` | the width of the rectangle.
guint16 `height` | the height of the rectangle.

### gdk_rectangle_intersect ()

    gint        gdk_rectangle_intersect         (GdkRectangle *src1,
                                                 GdkRectangle *src2,
                                                 GdkRectangle *dest);

Calculates the intersection of two rectangles.

`src1` : | a GdkRectangle.
`src2` : | a GdkRectangle.
`dest` : | the intersection of `src1` and `src2`.
Returns : | TRUE if the rectangles intersect.

### gdk_rectangle_union ()

    void        gdk_rectangle_union             (GdkRectangle *src1,
                                                 GdkRectangle *src2,
                                                 GdkRectangle *dest);

Calculates the union of two rectangles. The union of rectangles `src1` and `src2` is the smallest rectangle which includes both `src1` and `src2` within it.

`src1` : | a GdkRectangle.
`src2` : | a GdkRectangle.
`dest` : | the union of `src1` and `src2`.

### struct GdkRegion

    struct GdkRegion
    {
      gpointer user_data;
    };

A GdkRegion represents a set of pixels on the screen. The only user-visible field of the structure is the user_data member, which can be used to attach arbitrary data to the GdkRegion.

gpointer `user_data` | arbitrary data attached to the GdkRegion.

### gdk_region_new ()

    GdkRegion*  gdk_region_new                  (void);

Creates a new empty GdkRegion.

Returns : | a new empty GdkRegion.

### gdk_region_polygon ()

    GdkRegion*  gdk_region_polygon              (GdkPoint *points,
                                                 gint npoints,
                                                 GdkFillRule fill_rule);

Creates a new GdkRegion using the polygon defined by a number of points.

`points` : | an array of GdkPoint structs.
`npoints` : | the number of elements in the `points` array.
`fill_rule` : | specifies which pixels are included in the region when the polygon overlaps itself.
Returns : | a new GdkRegion based on the given polygon.

### enum GdkFillRule

    typedef enum
    {
      GDK_EVEN_ODD_RULE,
      GDK_WINDING_RULE
    } GdkFillRule;

The method for determining which pixels are included in a region, when creating a GdkRegion from a polygon. The fill rule is only relevant for polygons which overlap themselves.

`GDK_EVEN_ODD_RULE` | areas which are overlapped an odd number of times are included in the region, while areas overlapped an even number of times are not.
`GDK_WINDING_RULE` | overlapping areas are always included.

### gdk_region_destroy ()

    void        gdk_region_destroy              (GdkRegion *region);

Destroys a GdkRegion.

`region` : | a GdkRegion.

### gdk_regions_intersect ()

    GdkRegion*  gdk_regions_intersect           (GdkRegion *source1,
                                                 GdkRegion *source2);

Returns the intersection of two regions.

`source1` : | a GdkRegion.
`source2` : | a GdkRegion.
Returns : | the intersection of `source1` and `source2`.

### gdk_regions_union ()

    GdkRegion*  gdk_regions_union               (GdkRegion *source1,
                                                 GdkRegion *source2);

Returns the union of two regions. This is all pixels in either of `source1` or `source2`.

`source1` : | a GdkRegion.
`source2` : | a GdkRegion.
Returns : | the union of `source1` and `source2`.

### gdk_regions_subtract ()

    GdkRegion*  gdk_regions_subtract            (GdkRegion *source1,
                                                 GdkRegion *source2);

Subtracts one region from another. The result is a region containing all the pixels which are in `source1`, but which are not in `source2`.

`source1` : | a GdkRegion.
`source2` : | a GdkRegion to subtract from `source1`.
Returns : | `source1` - `source2`.

### gdk_regions_xor ()

    GdkRegion*  gdk_regions_xor                 (GdkRegion *source1,
                                                 GdkRegion *source2);

Returns the difference between the union and the intersection of two regions. This is a region containing the pixels that are in one of the source regions, but which are not in both.

`source1` : | a GdkRegion.
`source2` : | a GdkRegion.
Returns : | the difference between the union and the intersection of `source1` and `source2`.

### gdk_region_union_with_rect ()

    GdkRegion*  gdk_region_union_with_rect      (GdkRegion *region,
                                                 GdkRectangle *rect);

Returns the union of a region and a rectangle.

`region` : | a GdkRegion.
`rect` : | a GdkRectangle.
Returns : | the union of `region` and `rect`.

### gdk_region_offset ()

    void        gdk_region_offset               (GdkRegion *region,
                                                 gint dx,
                                                 gint dy);

Moves a region the specified distance.

`region` : | a GdkRegion.
`dx` : | the distance to move the region horizontally.
`dy` : | the distance to move the region vertically.

### gdk_region_shrink ()

    void        gdk_region_shrink               (GdkRegion *region,
                                                 gint dx,
                                                 gint dy);

Resizes a region by the specified amount. Positive values shrink the region. Negative values expand it.

`region` : | a GdkRegion.
`dx` : | the number of pixels to shrink the region horizontally.
`dy` : | the number of pixels to shrink the region vertically.

### gdk_region_empty ()

    gboolean    gdk_region_empty                (GdkRegion *region);

Returns TRUE if the GdkRegion is empty.

`region` : | a GdkRegion.
Returns : | TRUE if `region` is empty.

### gdk_region_equal ()

    gboolean    gdk_region_equal                (GdkRegion *region1,
                                                 GdkRegion *region2);

Returns TRUE if the two regions are the same.

`region1` : | a GdkRegion.
`region2` : | a GdkRegion.
Returns : | TRUE if `region1` and `region2` are equal.

### gdk_region_point_in ()

    gboolean    gdk_region_point_in             (GdkRegion *region,
                                                 int x,
                                                 int y);

Returns TRUE if a point is in a region.

`region` : | a GdkRegion.
`x` : | the x coordinate of a point.
`y` : | the y coordinate of a point.
Returns : | TRUE if the point is in `region`.

### gdk_region_rect_in ()

    GdkOverlapType gdk_region_rect_in           (GdkRegion *region,
                                                 GdkRectangle *rect);

Tests whether a rectangle is within a region.

`region` : | a GdkRegion.
`rect` : | a GdkRectangle.
Returns : | GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside, outside, or partly inside the GdkRegion, respectively.

### enum GdkOverlapType

    typedef enum
    {
      GDK_OVERLAP_RECTANGLE_IN,
      GDK_OVERLAP_RECTANGLE_OUT,
      GDK_OVERLAP_RECTANGLE_PART
    } GdkOverlapType;

Specifies the possible values returned by gdk_region_rect_in().

`GDK_OVERLAP_RECTANGLE_IN` | if the rectangle is inside the GdkRegion.
`GDK_OVERLAP_RECTANGLE_OUT` | if the rectangle is outside the GdkRegion.
`GDK_OVERLAP_RECTANGLE_PART` | if the rectangle is partly inside the GdkRegion.

### gdk_region_get_clipbox ()

    void        gdk_region_get_clipbox          (GdkRegion *region,
                                                 GdkRectangle *rectangle);

Returns the smallest rectangle which includes the entire GdkRegion.

`region` : | a GdkRegion.
`rectangle` : | returns the smallest rectangle which includes all of `region`.

<<< Previous Page | Home | Up | Next Page >>>
General | Graphics Contexts