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