interface/wx/region.h

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