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