docs/latex/wx/region.tex

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