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
  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 Assignment operator, using \helpref{reference counting}{trefcount}.
 264
 265
 266
 267 \section{\class{wxRegionIterator}}\label{wxregioniterator}
 268
 269 This class is used to iterate through the rectangles in a region,
 270 typically when examining the damaged regions of a window within an OnPaint call.
 271
 272 To use it, construct an iterator object on the stack and loop through the
 273 regions, testing the object and incrementing the iterator at the end of the loop.
 274
 275 See \helpref{wxPaintEvent}{wxpaintevent} for an example of use.
 276
 277 \wxheading{Derived from}
 278
 279 \helpref{wxObject}{wxobject}
 280
 281 \wxheading{Include files}
 282
 283 <wx/region.h>
 284
 285 \wxheading{See also}
 286
 287 \helpref{wxPaintEvent}{wxpaintevent}
 288
 289 \latexignore{\rtfignore{\wxheading{Members}}}
 290
 291
 292 \membersection{wxRegionIterator::wxRegionIterator}\label{wxregioniteratorctor}
 293
 294 \func{}{wxRegionIterator}{\void}
 295
 296 Default constructor.
 297
 298 \func{}{wxRegionIterator}{\param{const wxRegion\&}{ region}}
 299
 300 Creates an iterator object given a region.
 301
 302
 303 \membersection{wxRegionIterator::GetX}\label{wxregioniteratorgetx}
 304
 305 \constfunc{wxCoord}{GetX}{\void}
 306
 307 Returns the x value for the current region.
 308
 309
 310 \membersection{wxRegionIterator::GetY}\label{wxregioniteratorgety}
 311
 312 \constfunc{wxCoord}{GetY}{\void}
 313
 314 Returns the y value for the current region.
 315
 316
 317 \membersection{wxRegionIterator::GetW}\label{wxregioniteratorgetw}
 318
 319 \constfunc{wxCoord}{GetW}{\void}
 320
 321 An alias for GetWidth.
 322
 323
 324 \membersection{wxRegionIterator::GetHeight}\label{wxregioniteratorgetheight}
 325
 326 \constfunc{wxCoord}{GetHeight}{\void}
 327
 328 Returns the height value for the current region.
 329
 330
 331 \membersection{wxRegionIterator::GetH}\label{wxregioniteratorgeth}
 332
 333 \constfunc{wxCoord}{GetH}{\void}
 334
 335 An alias for GetHeight.
 336
 337
 338 \membersection{wxRegionIterator::GetRect}\label{wxregioniteratorgetrect}
 339
 340 \constfunc{wxRect}{GetRect}{\void}
 341
 342 Returns the current rectangle.
 343
 344
 345 \membersection{wxRegionIterator::GetWidth}\label{wxregioniteratorgetwidth}
 346
 347 \constfunc{wxCoord}{GetWidth}{\void}
 348
 349 Returns the width value for the current region.
 350
 351
 352 \membersection{wxRegionIterator::HaveRects}\label{wxregioniteratorhaverects}
 353
 354 \constfunc{bool}{HaveRects}{\void}
 355
 356 Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.
 357
 358
 359 \membersection{wxRegionIterator::Reset}\label{wxregioniteratorreset}
 360
 361 \func{void}{Reset}{\void}
 362
 363 Resets the iterator to the beginning of the rectangles.
 364
 365 \func{void}{Reset}{\param{const wxRegion\&}{ region}}
 366
 367 Resets the iterator to the given region.
 368
 369
 370 \membersection{wxRegionIterator::operator $++$}\label{wxregioniteratorinc}
 371
 372 \func{void}{operator $++$}{\void}
 373
 374 Increment operator. Increments the iterator to the next region.
 375
 376 \pythonnote{A wxPython alias for this operator is called {\tt Next}.}
 377
 378
 379 \membersection{wxRegionIterator::operator bool}\label{wxregioniteratorbool}
 380
 381 \constfunc{}{operator bool}{\void}
 382
 383 Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.
 384
 385 You can use this to test the iterator object as if it were of type bool.
 386