Pileus Git - ~andy/gtk/blob - docs/reference/gdk/tmpl/regions.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Points, Rectangles and Regions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Simple graphical data types
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
  10 for representing pixels and sets of pixels on the screen.
  11 </para>
  12 <para>
  13 #GdkPoint is a simple structure containing an x and y coordinate of a point.
  14 </para>
  15 <para>
  16 #GdkRectangle is a structure holding the position and size of a rectangle.
  17 The intersection of two rectangles can be computed with
  18 gdk_rectangle_intersect(). To find the union of two rectangles use
  19 gdk_rectangle_union().
  20 </para>
  21 <para>
  22 #GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
  23 usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
  24 </para>
  25 <para>
  26 #GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
  27 is one pixel wide. It is mainly used when rasterizing other graphics primitives.
  28 It can be intersected to regions by using gdk_region_spans_intersect_foreach().
  29 </para>
  30
  31 <!-- ##### SECTION See_Also ##### -->
  32 <para>
  33
  34 </para>
  35
  36 <!-- ##### SECTION Stability_Level ##### -->
  37
  38
  39 <!-- ##### STRUCT GdkPoint ##### -->
  40 <para>
  41 Defines the x and y coordinates of a point.
  42 </para>
  43
  44 @x: the x coordinate of the point.
  45 @y: the y coordinate of the point.
  46
  47 <!-- ##### STRUCT GdkRectangle ##### -->
  48 <para>
  49 Defines the position and size of a rectangle.
  50 </para>
  51
  52 @x: the x coordinate of the left edge of the rectangle.
  53 @y: the y coordinate of the top of the rectangle.
  54 @width: the width of the rectangle.
  55 @height: the height of the rectangle.
  56
  57 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
  58 <para>
  59 Calculates the intersection of two rectangles.
  60 </para>
  61
  62 @src1: a #GdkRectangle.
  63 @src2: a #GdkRectangle.
  64 @dest: the intersection of @src1 and @src2.
  65 @Returns: %TRUE if the rectangles intersect.
  66
  67
  68 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
  69 <para>
  70 Calculates the union of two rectangles.
  71 The union of rectangles @src1 and @src2 is the smallest rectangle which
  72 includes both @src1 and @src2 within it.
  73 </para>
  74
  75 @src1: a #GdkRectangle.
  76 @src2: a #GdkRectangle.
  77 @dest: the union of @src1 and @src2.
  78
  79
  80 <!-- ##### STRUCT GdkRegion ##### -->
  81 <para>
  82 A GdkRegion represents a set of pixels on the screen.
  83 The only user-visible field of the structure is the user_data member, which
  84 can be used to attach arbitrary data to the #GdkRegion.
  85 </para>
  86
  87
  88 <!-- ##### FUNCTION gdk_region_new ##### -->
  89 <para>
  90 Creates a new empty #GdkRegion.
  91 </para>
  92
  93 @Returns: a new empty #GdkRegion.
  94
  95
  96 <!-- ##### FUNCTION gdk_region_polygon ##### -->
  97 <para>
  98 Creates a new #GdkRegion using the polygon defined by a number of points.
  99
 100 </para>
 101
 102 @points: an array of #GdkPoint structs.
 103 @npoints: the number of elements in the @points array.
 104 @fill_rule: specifies which pixels are included in the region when the polygon
 105 overlaps itself.
 106 @Returns: a new #GdkRegion based on the given polygon.
 107
 108
 109 <!-- ##### ENUM GdkFillRule ##### -->
 110 <para>
 111 The method for determining which pixels are included in a region, when
 112 creating a #GdkRegion from a polygon.
 113 The fill rule is only relevant for polygons which overlap themselves.
 114 </para>
 115
 116 @GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
 117 included in the region, while areas overlapped an even number of times are not.
 118 @GDK_WINDING_RULE: overlapping areas are always included.
 119
 120 <!-- ##### FUNCTION gdk_region_copy ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @region:
 126 @Returns:
 127
 128
 129 <!-- ##### FUNCTION gdk_region_rectangle ##### -->
 130 <para>
 131
 132 </para>
 133
 134 @rectangle:
 135 @Returns:
 136
 137
 138 <!-- ##### FUNCTION gdk_region_destroy ##### -->
 139 <para>
 140 Destroys a #GdkRegion.
 141 </para>
 142
 143 @region: a #GdkRegion.
 144
 145
 146 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
 147 <para>
 148 Returns the smallest rectangle which includes the entire #GdkRegion.
 149 </para>
 150
 151 @region: a #GdkRegion.
 152 @rectangle: returns the smallest rectangle which includes all of @region.
 153
 154
 155 <!-- ##### FUNCTION gdk_region_get_rectangles ##### -->
 156 <para>
 157
 158 </para>
 159
 160 @region:
 161 @rectangles:
 162 @n_rectangles:
 163
 164
 165 <!-- ##### FUNCTION gdk_region_empty ##### -->
 166 <para>
 167 Returns %TRUE if the #GdkRegion is empty.
 168 </para>
 169
 170 @region: a #GdkRegion.
 171 @Returns: %TRUE if @region is empty.
 172
 173
 174 <!-- ##### FUNCTION gdk_region_equal ##### -->
 175 <para>
 176 Returns %TRUE if the two regions are the same.
 177 </para>
 178
 179 @region1: a #GdkRegion.
 180 @region2: a #GdkRegion.
 181 @Returns: %TRUE if @region1 and @region2 are equal.
 182
 183
 184 <!-- ##### FUNCTION gdk_region_point_in ##### -->
 185 <para>
 186 Returns %TRUE if a point is in a region.
 187 </para>
 188
 189 @region: a #GdkRegion.
 190 @x: the x coordinate of a point.
 191 @y: the y coordinate of a point.
 192 @Returns: %TRUE if the point is in @region.
 193
 194
 195 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
 196 <para>
 197 Tests whether a rectangle is within a region.
 198 </para>
 199
 200 @region: a #GdkRegion.
 201 @rect: a #GdkRectangle.
 202 @Returns: %GDK_OVERLAP_RECTANGLE_IN, %GDK_OVERLAP_RECTANGLE_OUT, or
 203 %GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
 204 outside, or partly inside the #GdkRegion, respectively.
 205
 206
 207 <!-- ##### ENUM GdkOverlapType ##### -->
 208 <para>
 209 Specifies the possible values returned by gdk_region_rect_in().
 210 </para>
 211
 212 @GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
 213 @GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
 214 @GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
 215
 216 <!-- ##### FUNCTION gdk_region_offset ##### -->
 217 <para>
 218 Moves a region the specified distance.
 219 </para>
 220
 221 @region: a #GdkRegion.
 222 @dx: the distance to move the region horizontally.
 223 @dy: the distance to move the region vertically.
 224
 225
 226 <!-- ##### FUNCTION gdk_region_shrink ##### -->
 227 <para>
 228 Resizes a region by the specified amount.
 229 Positive values shrink the region. Negative values expand it.
 230 </para>
 231
 232 @region: a #GdkRegion.
 233 @dx: the number of pixels to shrink the region horizontally.
 234 @dy: the number of pixels to shrink the region vertically.
 235
 236
 237 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @region:
 243 @rect:
 244
 245
 246 <!-- ##### FUNCTION gdk_region_intersect ##### -->
 247 <para>
 248 </para>
 249
 250 @source1:
 251 @source2:
 252
 253
 254 <!-- ##### FUNCTION gdk_region_union ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @source1:
 260 @source2:
 261
 262
 263 <!-- ##### FUNCTION gdk_region_subtract ##### -->
 264 <para>
 265 </para>
 266
 267 @source1:
 268 @source2:
 269
 270
 271 <!-- ##### FUNCTION gdk_region_xor ##### -->
 272 <para>
 273 </para>
 274
 275 @source1:
 276 @source2:
 277
 278
 279 <!-- ##### STRUCT GdkSpan ##### -->
 280 <para>
 281 A GdkSpan represents a horizontal line of pixels starting
 282 at the pixel with coordinates @x, @y and ending before @x + @width, @y.
 283 </para>
 284
 285 @x: x coordinate of the first pixel.
 286 @y: y coordinate of the first pixel.
 287 @width: number of pixels in the span.
 288
 289 <!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
 290 <para>
 291 This defines the type of the function passed to
 292 gdk_region_spans_intersect_foreach().
 293 </para>
 294
 295 @span: a #GdkSpan.
 296 @data: the user data passed to gdk_region_spans_intersect_foreach().
 297
 298
 299 <!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->
 300 <para>
 301 Calls a function on each span in the intersection of @region and
 302 @spans.
 303 </para>
 304
 305 @region: a #GdkRegion.
 306 @spans: an array of #GdkSpans.
 307 @n_spans: the length of @spans.
 308 @sorted: %TRUE if @spans is sorted wrt. the y coordinate.
 309 @function: function to call on each span in the intersection.
 310 @data: data to pass to @function.
 311
 312