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