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