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