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