docs/latex/wx/region.tex

   1 \section{\class{wxRegion}}\label{wxregion}
   2
   3 A wxRegion represents a simple or complex region on a device context or window. It uses
   4 reference counting, so copying and assignment operations are fast.
   5
   6 \wxheading{Derived from}
   7
   8 \helpref{wxGDIObject}{wxgdiobject}\\
   9 \helpref{wxObject}{wxobject}
  10
  11 \wxheading{Include files}
  12
  13 <wx/region.h>
  14
  15 \wxheading{See also}
  16
  17 \helpref{wxRegionIterator}{wxregioniterator}
  18
  19 \latexignore{\rtfignore{\wxheading{Members}}}
  20
  21
  22 \membersection{wxRegion::wxRegion}\label{wxregionctor}
  23
  24 \func{}{wxRegion}{\void}
  25
  26 Default constructor.
  27
  28 \func{}{wxRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
  29
  30 Constructs a rectangular region with the given position and size.
  31
  32 \func{}{wxRegion}{\param{const wxPoint\&}{ topLeft}, \param{const wxPoint\&}{ bottomRight}}
  33
  34 Constructs a rectangular region from the top left point and the bottom right point.
  35
  36 \func{}{wxRegion}{\param{const wxRect\&}{ rect}}
  37
  38 Constructs a rectangular region a wxRect object.
  39
  40 \func{}{wxRegion}{\param{const wxRegion\&}{ region}}
  41
  42 Copy constructor, uses \helpref{reference counting}{trefcount}.
  43
  44 \func{}{wxRegion}{\param{size\_t}{ n}, \param{const wxPoint }{*points}, \param{int }{fillStyle = wxWINDING\_RULE}}
  45
  46 Constructs a region corresponding to the polygon made of {\it n} points in the
  47 provided array. {\it fillStyle} parameter may have values
  48 {\tt wxWINDING\_RULE} or {\tt wxODDEVEN\_RULE}.
  49
  50 {\bf NB:} This constructor is only implemented for Win32 and GTK+ wxWidgets ports.
  51
  52 \func{}{wxRegion}{\param{const wxBitmap\&}{ bmp}}
  53
  54 \func{}{wxRegion}{\param{const wxBitmap\&}{ bmp},
  55                   \param{const wxColour\&}{ transColour},
  56                   \param{int}{ tolerance = 0}}
  57
  58 Constructs a region using the non-transparent pixels of a bitmap.  See
  59 \helpref{Union}{wxregionunion} for more details.
  60
  61
  62
  63 \membersection{wxRegion::\destruct{wxRegion}}\label{wxregiondtor}
  64
  65 \func{}{\destruct{wxRegion}}{\void}
  66
  67 Destructor.
  68 See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
  69
  70
  71 \membersection{wxRegion::Clear}\label{wxregionclear}
  72
  73 \func{void}{Clear}{\void}
  74
  75 Clears the current region.
  76
  77
  78 \membersection{wxRegion::Contains}\label{wxregioncontains}
  79
  80 \constfunc{wxRegionContain}{Contains}{\param{long\& }{x}, \param{long\& }{y}}
  81
  82 Returns a value indicating whether the given point is contained within the region.
  83
  84 \constfunc{wxRegionContain}{Contains}{\param{const wxPoint\&}{ pt}}
  85
  86 Returns a value indicating whether the given point is contained within the region.
  87
  88 \constfunc{wxRegionContain}{Contains}{\param{long\& }{x}, \param{long\& }{y}, \param{long\& }{width}, \param{long\& }{height}}
  89
  90 Returns a value indicating whether the given rectangle is contained within the region.
  91
  92 \constfunc{wxRegionContain}{Contains}{\param{const wxRect\& }{rect}}
  93
  94 Returns a value indicating whether the given rectangle is contained within the region.
  95
  96 \wxheading{Return value}
  97
  98 The return value is one of wxOutRegion, wxPartRegion and wxInRegion.
  99
 100 On Windows, only wxOutRegion and wxInRegion are returned; a value wxInRegion then indicates that
 101 all or some part of the region is contained in this region.
 102
 103
 104 \membersection{wxRegion::ConvertToBitmap}\label{wxregionconverttobitmap}
 105
 106 \constfunc{wxBitmap}{ConvertToBitmap}{}
 107
 108 Convert the region to a black and white bitmap with the white pixels
 109 being inside the region.
 110
 111
 112 \membersection{wxRegion::GetBox}\label{wxregiongetbox}
 113
 114 \constfunc{void}{GetBox}{\param{wxCoord\& }{x}, \param{wxCoord\& }{y}, \param{wxCoord\& }{width}, \param{wxCoord\& }{height}}
 115
 116 Returns the outer bounds of the region.
 117
 118 \constfunc{wxRect}{GetBox}{\void}
 119
 120 Returns the outer bounds of the region.
 121
 122
 123 \membersection{wxRegion::Intersect}\label{wxregionintersect}
 124
 125 \func{bool}{Intersect}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
 126
 127 Finds the intersection of this region and another, rectangular region, specified using position and size.
 128
 129 \func{bool}{Intersect}{\param{const wxRect\&}{ rect}}
 130
 131 Finds the intersection of this region and another, rectangular region.
 132
 133 \func{bool}{Intersect}{\param{const wxRegion\&}{ region}}
 134
 135 Finds the intersection of this region and another region.
 136
 137 \wxheading{Return value}
 138
 139 {\tt true} if successful, {\tt false} otherwise.
 140
 141 \wxheading{Remarks}
 142
 143 Creates the intersection of the two regions, that is, the parts which are in both regions. The result
 144 is stored in this region.
 145
 146
 147 \membersection{wxRegion::IsEmpty}\label{wxregionisempty}
 148
 149 \constfunc{bool}{IsEmpty}{\void}
 150
 151 Returns {\tt true} if the region is empty, {\tt false} otherwise.
 152
 153
 154 \membersection{wxRegion::IsEqual}\label{wxregionisequal}
 155
 156 \constfunc{bool}{IsEqual}{\param{const wxRegion\& }{region}}
 157
 158 Returns {\tt true} if the region is equal to, i.e. covers the same area as,
 159 another one. Note that if both this region and \arg{region} are invalid, they
 160 are considered to be equal.
 161
 162
 163 \membersection{wxRegion::Subtract}\label{wxregionsubtract}
 164
 165 \func{bool}{Subtract}{\param{const wxRect\&}{ rect}}
 166
 167 Subtracts a rectangular region from this region.
 168
 169 \func{bool}{Subtract}{\param{const wxRegion\&}{ region}}
 170
 171 Subtracts a region from this region.
 172
 173 \wxheading{Return value}
 174
 175 {\tt true} if successful, {\tt false} otherwise.
 176
 177 \wxheading{Remarks}
 178
 179 This operation combines the parts of 'this' region that are not part of the second region.
 180 The result is stored in this region.
 181
 182
 183 \membersection{wxRegion::Offset}\label{wxregionoffset}
 184
 185 \func{bool}{Offset}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
 186
 187 \func{bool}{Offset}{\param{const wxPoint\& }{ pt}}
 188
 189 Moves the region by the specified offsets in horizontal and vertical
 190 directions.
 191
 192 \wxheading{Return value}
 193
 194 {\tt true} if successful, {\tt false} otherwise (the region is unchanged then).
 195
 196
 197 \membersection{wxRegion::Union}\label{wxregionunion}
 198
 199 \func{bool}{Union}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
 200
 201 Finds the union of this region and another, rectangular region, specified using position and size.
 202
 203 \func{bool}{Union}{\param{const wxRect\&}{ rect}}
 204
 205 Finds the union of this region and another, rectangular region.
 206
 207 \func{bool}{Union}{\param{const wxRegion\&}{ region}}
 208
 209 Finds the union of this region and another region.
 210
 211 \func{bool}{Union}{\param{const wxBitmap\&}{ bmp}}
 212
 213 Finds the union of this region and the non-transparent pixels of a
 214 bitmap. Bitmap's mask is used to determine transparency. If the bitmap doesn't
 215 have a mask, solid rectangle of bitmap's dimensions is used.
 216
 217 \func{bool}{Union}{\param{const wxBitmap\&}{ bmp},
 218                   \param{const wxColour\&}{ transColour},
 219                   \param{int}{ tolerance = 0}}
 220
 221 Finds the union of this region and the non-transparent pixels of a
 222 bitmap. Colour to be treated as transparent is specified in the
 223 \arg{transColour} argument, along with an
 224 optional colour tolerance value.
 225
 226 \wxheading{Return value}
 227
 228 {\tt true} if successful, {\tt false} otherwise.
 229
 230 \wxheading{Remarks}
 231
 232 This operation creates a region that combines all of this region and the second region.
 233 The result is stored in this region.
 234
 235
 236 \membersection{wxRegion::Xor}\label{wxregionxor}
 237
 238 \func{bool}{Xor}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
 239
 240 Finds the Xor of this region and another, rectangular region, specified using position and size.
 241
 242 \func{bool}{Xor}{\param{const wxRect\&}{ rect}}
 243
 244 Finds the Xor of this region and another, rectangular region.
 245
 246 \func{bool}{Xor}{\param{const wxRegion\&}{ region}}
 247
 248 Finds the Xor of this region and another region.
 249
 250 \wxheading{Return value}
 251
 252 {\tt true} if successful, {\tt false} otherwise.
 253
 254 \wxheading{Remarks}
 255
 256 This operation creates a region that combines all of this region and the second region, except
 257 for any overlapping areas. The result is stored in this region.
 258
 259
 260 \membersection{wxRegion::operator $=$}\label{wxregionassign}
 261
 262 \func{void}{operator $=$}{\param{const wxRegion\&}{ region}}
 263
 264 Assignment operator, using \helpref{reference counting}{trefcount}.
 265
 266
 267
 268 \section{\class{wxRegionIterator}}\label{wxregioniterator}
 269
 270 This class is used to iterate through the rectangles in a region,
 271 typically when examining the damaged regions of a window within an OnPaint call.
 272
 273 To use it, construct an iterator object on the stack and loop through the
 274 regions, testing the object and incrementing the iterator at the end of the loop.
 275
 276 See \helpref{wxPaintEvent}{wxpaintevent} for an example of use.
 277
 278 \wxheading{Derived from}
 279
 280 \helpref{wxObject}{wxobject}
 281
 282 \wxheading{Include files}
 283
 284 <wx/region.h>
 285
 286 \wxheading{See also}
 287
 288 \helpref{wxPaintEvent}{wxpaintevent}
 289
 290 \latexignore{\rtfignore{\wxheading{Members}}}
 291
 292
 293 \membersection{wxRegionIterator::wxRegionIterator}\label{wxregioniteratorctor}
 294
 295 \func{}{wxRegionIterator}{\void}
 296
 297 Default constructor.
 298
 299 \func{}{wxRegionIterator}{\param{const wxRegion\&}{ region}}
 300
 301 Creates an iterator object given a region.
 302
 303
 304 \membersection{wxRegionIterator::GetX}\label{wxregioniteratorgetx}
 305
 306 \constfunc{wxCoord}{GetX}{\void}
 307
 308 Returns the x value for the current region.
 309
 310
 311 \membersection{wxRegionIterator::GetY}\label{wxregioniteratorgety}
 312
 313 \constfunc{wxCoord}{GetY}{\void}
 314
 315 Returns the y value for the current region.
 316
 317
 318 \membersection{wxRegionIterator::GetW}\label{wxregioniteratorgetw}
 319
 320 \constfunc{wxCoord}{GetW}{\void}
 321
 322 An alias for GetWidth.
 323
 324
 325 \membersection{wxRegionIterator::GetHeight}\label{wxregioniteratorgetheight}
 326
 327 \constfunc{wxCoord}{GetHeight}{\void}
 328
 329 Returns the height value for the current region.
 330
 331
 332 \membersection{wxRegionIterator::GetH}\label{wxregioniteratorgeth}
 333
 334 \constfunc{wxCoord}{GetH}{\void}
 335
 336 An alias for GetHeight.
 337
 338
 339 \membersection{wxRegionIterator::GetRect}\label{wxregioniteratorgetrect}
 340
 341 \constfunc{wxRect}{GetRect}{\void}
 342
 343 Returns the current rectangle.
 344
 345
 346 \membersection{wxRegionIterator::GetWidth}\label{wxregioniteratorgetwidth}
 347
 348 \constfunc{wxCoord}{GetWidth}{\void}
 349
 350 Returns the width value for the current region.
 351
 352
 353 \membersection{wxRegionIterator::HaveRects}\label{wxregioniteratorhaverects}
 354
 355 \constfunc{bool}{HaveRects}{\void}
 356
 357 Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.
 358
 359
 360 \membersection{wxRegionIterator::Reset}\label{wxregioniteratorreset}
 361
 362 \func{void}{Reset}{\void}
 363
 364 Resets the iterator to the beginning of the rectangles.
 365
 366 \func{void}{Reset}{\param{const wxRegion\&}{ region}}
 367
 368 Resets the iterator to the given region.
 369
 370
 371 \membersection{wxRegionIterator::operator $++$}\label{wxregioniteratorinc}
 372
 373 \func{void}{operator $++$}{\void}
 374
 375 Increment operator. Increments the iterator to the next region.
 376
 377 \pythonnote{A wxPython alias for this operator is called {\tt Next}.}
 378
 379
 380 \membersection{wxRegionIterator::operator bool}\label{wxregioniteratorbool}
 381
 382 \constfunc{}{operator bool}{\void}
 383
 384 Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.
 385
 386 You can use this to test the iterator object as if it were of type bool.
 387