interface/wx/region.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        region.h
   3 // Purpose:     interface of wxRegionIterator
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Types of results returned from a call to wxRegion::Contains().
  10 */
  11 enum wxRegionContain
  12 {
  13     /** The specified value is not contained within this region. */
  14     wxOutRegion = 0,
  15
  16     /**
  17         The specified value is partially contained within this region.
  18
  19         On Windows, this result is not supported. ::wxInRegion will be returned
  20         instead.
  21     */
  22     wxPartRegion = 1,
  23
  24     /**
  25         The specified value is fully contained within this region.
  26
  27         On Windows, this result will be returned even if only part of the specified
  28         value is contained in this region.
  29     */
  30     wxInRegion = 2
  31 };
  32
  33 /**
  34     @class wxRegionIterator
  35
  36     This class is used to iterate through the rectangles in a region,
  37     typically when examining the damaged regions of a window within an OnPaint call.
  38
  39     To use it, construct an iterator object on the stack and loop through the
  40     regions, testing the object and incrementing the iterator at the end of the
  41     loop.
  42
  43     See wxPaintEvent for an example of use.
  44
  45     @library{wxcore}
  46     @category{gdi}
  47
  48     @stdobjects
  49     ::wxNullRegion
  50
  51     @see wxPaintEvent
  52 */
  53 class wxRegionIterator : public wxObject
  54 {
  55 public:
  56     /**
  57         Default constructor.
  58     */
  59     wxRegionIterator();
  60     /**
  61         Creates an iterator object given a region.
  62     */
  63     wxRegionIterator(const wxRegion& region);
  64
  65     /**
  66         An alias for GetHeight().
  67     */
  68     wxCoord GetH() const;
  69
  70     /**
  71         Returns the height value for the current region.
  72     */
  73     wxCoord GetHeight() const;
  74
  75     /**
  76         Returns the current rectangle.
  77     */
  78     wxRect GetRect() const;
  79
  80     /**
  81         An alias for GetWidth().
  82     */
  83     wxCoord GetW() const;
  84
  85     /**
  86         Returns the width value for the current region.
  87     */
  88     wxCoord GetWidth() const;
  89
  90     /**
  91         Returns the x value for the current region.
  92     */
  93     wxCoord GetX() const;
  94
  95     /**
  96         Returns the y value for the current region.
  97     */
  98     wxCoord GetY() const;
  99
 100     /**
 101         Returns @true if there are still some rectangles; otherwise returns @false.
 102     */
 103     bool HaveRects() const;
 104
 105     /**
 106         Resets the iterator to the beginning of the rectangles.
 107     */
 108     void Reset();
 109
 110     /**
 111         Resets the iterator to the given region.
 112     */
 113     void Reset(const wxRegion& region);
 114
 115     /**
 116         Increment operator. Increments the iterator to the next region.
 117     */
 118     wxRegionIterator& operator ++();
 119
 120     /**
 121         Returns @true if there are still some rectangles; otherwise returns @false.
 122
 123         You can use this to test the iterator object as if it were of type @c bool.
 124     */
 125     operator bool() const;
 126 };
 127
 128
 129
 130 /**
 131     @class wxRegion
 132
 133     A wxRegion represents a simple or complex region on a device context or window.
 134
 135     This class uses @ref overview_refcount "reference counting and copy-on-write"
 136     internally so that assignments between two instances of this class are very
 137     cheap. You can therefore use actual objects instead of pointers without
 138     efficiency problems. If an instance of this class is changed it will create
 139     its own data internally so that other instances, which previously shared the
 140     data using the reference counting, are not affected.
 141
 142     @stdobjects
 143     - ::wxNullRegion
 144
 145     @library{wxcore}
 146     @category{data,gdi}
 147
 148     @see wxRegionIterator
 149 */
 150 class wxRegion : public wxGDIObject
 151 {
 152 public:
 153     /**
 154         Default constructor.
 155
 156         This constructor creates an invalid, or null, object, i.e. calling
 157         IsOk() on it returns @false and IsEmpty() returns @true.
 158     */
 159     wxRegion();
 160     /**
 161         Constructs a rectangular region with the given position and size.
 162     */
 163     wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 164     /**
 165         Constructs a rectangular region from the top left point and the bottom right
 166         point.
 167     */
 168     wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
 169     /**
 170         Constructs a rectangular region a wxRect object.
 171     */
 172     wxRegion(const wxRect& rect);
 173     /**
 174         Copy constructor, uses @ref overview_refcount.
 175     */
 176     wxRegion(const wxRegion& region);
 177     /**
 178         Constructs a region corresponding to the polygon made of @a n points
 179         in the provided array.
 180         @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
 181     */
 182     wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 183     /**
 184         Constructs a region using a bitmap. See Union() for more details.
 185     */
 186     wxRegion(const wxBitmap& bmp);
 187     /**
 188         Constructs a region using the non-transparent pixels of a bitmap.  See
 189         Union() for more details.
 190     */
 191     wxRegion(const wxBitmap& bmp, const wxColour& transColour,
 192              int tolerance = 0);
 193
 194     /**
 195         Destructor.
 196         See @ref overview_refcount_destruct "reference-counted object destruction" for
 197         more info.
 198     */
 199     virtual ~wxRegion();
 200
 201     /**
 202         Clears the current region.
 203
 204         The object becomes invalid, or null, after being cleared.
 205     */
 206     virtual void Clear();
 207
 208     /**
 209         Returns a value indicating whether the given point is contained within the region.
 210
 211         This method always returns @c wxOutRegion for an invalid region but
 212         may, nevertheless, be safely called in this case.
 213
 214         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 215     */
 216     wxRegionContain Contains(wxCoord x, wxCoord y) const;
 217     /**
 218         Returns a value indicating whether the given point is contained within the region.
 219
 220         This method always returns @c wxOutRegion for an invalid region but
 221         may, nevertheless, be safely called in this case.
 222
 223         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 224     */
 225     wxRegionContain Contains(const wxPoint& pt) const;
 226     /**
 227         Returns a value indicating whether the given rectangle is contained within the
 228         region.
 229
 230         This method always returns @c wxOutRegion for an invalid region but
 231         may, nevertheless, be safely called in this case.
 232
 233         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 234
 235         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 236               ::wxInRegion then indicates that all or some part of the region is
 237               contained in this region.
 238     */
 239     wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const;
 240     /**
 241         Returns a value indicating whether the given rectangle is contained within the
 242         region.
 243
 244         This method always returns @c wxOutRegion for an invalid region but
 245         may, nevertheless, be safely called in this case.
 246
 247         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 248
 249         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 250               ::wxInRegion then indicates that all or some part of the region is
 251               contained in this region.
 252     */
 253     wxRegionContain Contains(const wxRect& rect) const;
 254
 255     /**
 256         Convert the region to a black and white bitmap with the white pixels
 257         being inside the region.
 258
 259         This method can't be used for invalid region.
 260     */
 261     wxBitmap ConvertToBitmap() const;
 262
 263     //@{
 264     /**
 265         Returns the outer bounds of the region.
 266
 267         This method returns 0-sized bounding box for invalid regions.
 268     */
 269     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
 270                 wxCoord& height) const;
 271     wxRect GetBox() const;
 272     //@}
 273
 274     /**
 275         Finds the intersection of this region and another, rectangular region,
 276         specified using position and size.
 277
 278         This method always fails, i.e. returns @false, if this region is
 279         invalid but may nevertheless be safely used even in this case.
 280
 281         @return @true if successful, @false otherwise.
 282
 283         @remarks Creates the intersection of the two regions, that is, the parts
 284                  which are in both regions. The result is stored in this
 285                  region.
 286     */
 287     bool Intersect(wxCoord x, wxCoord y, wxCoord width,
 288                    wxCoord height);
 289     /**
 290         Finds the intersection of this region and another, rectangular region.
 291
 292         This method always fails, i.e. returns @false, if this region is
 293         invalid but may nevertheless be safely used even in this case.
 294
 295         @return @true if successful, @false otherwise.
 296
 297         @remarks Creates the intersection of the two regions, that is, the parts
 298                  which are in both regions. The result is stored in this
 299                  region.
 300     */
 301     bool Intersect(const wxRect& rect);
 302     /**
 303         Finds the intersection of this region and another region.
 304
 305         This method always fails, i.e. returns @false, if this region is
 306         invalid but may nevertheless be safely used even in this case.
 307
 308         @return @true if successful, @false otherwise.
 309
 310         @remarks Creates the intersection of the two regions, that is, the parts
 311                  which are in both regions. The result is stored in this
 312                  region.
 313     */
 314     bool Intersect(const wxRegion& region);
 315
 316     /**
 317         Returns @true if the region is empty, @false otherwise.
 318
 319         Always returns @true if the region is invalid.
 320     */
 321     virtual bool IsEmpty() const;
 322
 323     /**
 324         Returns @true if the region is equal to, i.e.\ covers the same area as,
 325         another one.
 326
 327         If both this region and @a region are both invalid, they are considered
 328         to be equal.
 329     */
 330     bool IsEqual(const wxRegion& region) const;
 331
 332     //@{
 333     /**
 334         Moves the region by the specified offsets in horizontal and vertical
 335         directions.
 336
 337         This method can't be called if the region is invalid as it doesn't make
 338         sense to offset it then. Attempts to do it will result in assert
 339         failure.
 340
 341         @return @true if successful, @false otherwise (the region is unchanged
 342                  then).
 343     */
 344     bool Offset(wxCoord x, wxCoord y);
 345     bool Offset(const wxPoint& pt);
 346     //@}
 347
 348     /**
 349         Subtracts a rectangular region from this region.
 350
 351         This method always fails, i.e. returns @false, if this region is
 352         invalid but may nevertheless be safely used even in this case.
 353
 354         @return @true if successful, @false otherwise.
 355
 356         @remarks This operation combines the parts of 'this' region that are not
 357                  part of the second region. The result is stored in this
 358                  region.
 359     */
 360     bool Subtract(const wxRect& rect);
 361     /**
 362         Subtracts a region from this region.
 363
 364         This method always fails, i.e. returns @false, if this region is
 365         invalid but may nevertheless be safely used even in this case.
 366
 367         @return @true if successful, @false otherwise.
 368
 369         @remarks This operation combines the parts of 'this' region that are not
 370                  part of the second region. The result is stored in this
 371                  region.
 372     */
 373     bool Subtract(const wxRegion& region);
 374
 375     /**
 376         Finds the union of this region and another, rectangular region, specified using
 377         position and size.
 378
 379         This method can be used even if this region is invalid and has the
 380         natural behaviour in this case, i.e. makes this region equal to the
 381         given rectangle.
 382
 383         @return @true if successful, @false otherwise.
 384
 385         @remarks This operation creates a region that combines all of this region
 386                  and the second region. The result is stored in this
 387                  region.
 388     */
 389     bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 390     /**
 391         Finds the union of this region and another, rectangular region.
 392
 393         This method can be used even if this region is invalid and has the
 394         natural behaviour in this case, i.e. makes this region equal to the
 395         given rectangle.
 396
 397         @return @true if successful, @false otherwise.
 398
 399         @remarks This operation creates a region that combines all of this region
 400                  and the second region. The result is stored in this
 401                  region.
 402     */
 403     bool Union(const wxRect& rect);
 404     /**
 405         Finds the union of this region and another region.
 406
 407         This method can be used even if this region is invalid and has the
 408         natural behaviour in this case, i.e. makes this region equal to the
 409         given @a region.
 410
 411         @return @true if successful, @false otherwise.
 412
 413         @remarks This operation creates a region that combines all of this region
 414                  and the second region. The result is stored in this
 415                  region.
 416     */
 417     bool Union(const wxRegion& region);
 418     /**
 419         Finds the union of this region and the non-transparent pixels of a
 420         bitmap. The bitmap's mask is used to determine transparency. If the
 421         bitmap doesn't have a mask, the bitmap's full dimensions are used.
 422
 423         @return @true if successful, @false otherwise.
 424
 425         @remarks This operation creates a region that combines all of this region
 426                  and the second region. The result is stored in this
 427                  region.
 428     */
 429     bool Union(const wxBitmap& bmp);
 430     /**
 431         Finds the union of this region and the non-transparent pixels of a
 432         bitmap. Colour to be treated as transparent is specified in the
 433         @a transColour argument, along with an optional colour tolerance value.
 434
 435         @return @true if successful, @false otherwise.
 436
 437         @remarks This operation creates a region that combines all of this region
 438                  and the second region. The result is stored in this
 439                  region.
 440     */
 441     bool Union(const wxBitmap& bmp, const wxColour& transColour,
 442                int tolerance = 0);
 443
 444     /**
 445         Finds the Xor of this region and another, rectangular region, specified using
 446         position and size.
 447
 448         This method can be used even if this region is invalid and has the
 449         natural behaviour in this case, i.e. makes this region equal to the
 450         given rectangle.
 451
 452         @return @true if successful, @false otherwise.
 453
 454         @remarks This operation creates a region that combines all of this region
 455                  and the second region, except for any overlapping
 456                  areas. The result is stored in this region.
 457     */
 458     bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 459     /**
 460         Finds the Xor of this region and another, rectangular region.
 461
 462         This method can be used even if this region is invalid and has the
 463         natural behaviour in this case, i.e. makes this region equal to the
 464         given rectangle.
 465
 466         @return @true if successful, @false otherwise.
 467
 468         @remarks This operation creates a region that combines all of this region
 469                  and the second region, except for any overlapping
 470                  areas. The result is stored in this region.
 471     */
 472     bool Xor(const wxRect& rect);
 473     /**
 474         Finds the Xor of this region and another region.
 475
 476         This method can be used even if this region is invalid and has the
 477         natural behaviour in this case, i.e. makes this region equal to the
 478         given @a region.
 479
 480         @return @true if successful, @false otherwise.
 481
 482         @remarks This operation creates a region that combines all of this region
 483                  and the second region, except for any overlapping
 484                  areas. The result is stored in this region.
 485     */
 486     bool Xor(const wxRegion& region);
 487
 488     /**
 489         Assignment operator, using @ref overview_refcount.
 490     */
 491     wxRegion& operator=(const wxRegion& region);
 492 };
 493
 494 /**
 495     An empty region.
 496 */
 497 wxRegion wxNullRegion;