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