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         @beginWxPythonOnly
 120         A wxPython alias for this operator is called Next.
 121         @endWxPythonOnly
 122     */
 123     wxRegionIterator& operator ++();
 124
 125     /**
 126         Returns @true if there are still some rectangles; otherwise returns @false.
 127
 128         You can use this to test the iterator object as if it were of type @c bool.
 129     */
 130     operator bool() const;
 131 };
 132
 133
 134
 135 /**
 136     @class wxRegion
 137
 138     A wxRegion represents a simple or complex region on a device context or window.
 139
 140     This class uses @ref overview_refcount "reference counting and copy-on-write"
 141     internally so that assignments between two instances of this class are very
 142     cheap. You can therefore use actual objects instead of pointers without
 143     efficiency problems. If an instance of this class is changed it will create
 144     its own data internally so that other instances, which previously shared the
 145     data using the reference counting, are not affected.
 146
 147     @stdobjects
 148     - ::wxNullRegion
 149
 150     @library{wxcore}
 151     @category{data,gdi}
 152
 153     @see wxRegionIterator
 154 */
 155 class wxRegion : public wxGDIObject
 156 {
 157 public:
 158     /**
 159         Default constructor.
 160
 161         This constructor creates an invalid, or null, object, i.e. calling
 162         IsOk() on it returns @false and IsNull() returns @true.
 163     */
 164     wxRegion();
 165     /**
 166         Constructs a rectangular region with the given position and size.
 167     */
 168     wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 169     /**
 170         Constructs a rectangular region from the top left point and the bottom right
 171         point.
 172     */
 173     wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
 174     /**
 175         Constructs a rectangular region a wxRect object.
 176     */
 177     wxRegion(const wxRect& rect);
 178     /**
 179         Copy constructor, uses @ref overview_refcount.
 180     */
 181     wxRegion(const wxRegion& region);
 182     /**
 183         Constructs a region corresponding to the polygon made of @a n points
 184         in the provided array.
 185         @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
 186     */
 187     wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 188     /**
 189         Constructs a region using a bitmap. See Union() for more details.
 190     */
 191     wxRegion(const wxBitmap& bmp);
 192     /**
 193         Constructs a region using the non-transparent pixels of a bitmap.  See
 194         Union() for more details.
 195     */
 196     wxRegion(const wxBitmap& bmp, const wxColour& transColour,
 197              int tolerance = 0);
 198
 199     /**
 200         Destructor.
 201         See @ref overview_refcount_destruct "reference-counted object destruction" for
 202         more info.
 203     */
 204     virtual ~wxRegion();
 205
 206     /**
 207         Clears the current region.
 208
 209         The object becomes invalid, or null, after being cleared.
 210     */
 211     virtual void Clear();
 212
 213     /**
 214         Returns a value indicating whether the given point is contained within the region.
 215
 216         This method always returns @c wxOutRegion for an invalid region but
 217         may, nevertheless, be safely called in this case.
 218
 219         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 220     */
 221     wxRegionContain Contains(wxCoord x, wxCoord y) const;
 222     /**
 223         Returns a value indicating whether the given point is contained within the region.
 224
 225         This method always returns @c wxOutRegion for an invalid region but
 226         may, nevertheless, be safely called in this case.
 227
 228         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 229     */
 230     wxRegionContain Contains(const wxPoint& pt) const;
 231     /**
 232         Returns a value indicating whether the given rectangle is contained within the
 233         region.
 234
 235         This method always returns @c wxOutRegion for an invalid region but
 236         may, nevertheless, be safely called in this case.
 237
 238         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 239
 240         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 241               ::wxInRegion then indicates that all or some part of the region is
 242               contained in this region.
 243     */
 244     wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const;
 245     /**
 246         Returns a value indicating whether the given rectangle is contained within the
 247         region.
 248
 249         This method always returns @c wxOutRegion for an invalid region but
 250         may, nevertheless, be safely called in this case.
 251
 252         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 253
 254         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 255               ::wxInRegion then indicates that all or some part of the region is
 256               contained in this region.
 257     */
 258     wxRegionContain Contains(const wxRect& rect) const;
 259
 260     /**
 261         Convert the region to a black and white bitmap with the white pixels
 262         being inside the region.
 263
 264         This method can't be used for invalid region.
 265     */
 266     wxBitmap ConvertToBitmap() const;
 267
 268     //@{
 269     /**
 270         Returns the outer bounds of the region.
 271
 272         This method returns 0-sized bounding box for invalid regions.
 273     */
 274     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
 275                 wxCoord& height) const;
 276     wxRect GetBox() const;
 277     //@}
 278
 279     /**
 280         Finds the intersection of this region and another, rectangular region,
 281         specified using position and size.
 282
 283         This method always fails, i.e. returns @false, if this region is
 284         invalid but may nevertheless be safely used even in this case.
 285
 286         @return @true if successful, @false otherwise.
 287
 288         @remarks Creates the intersection of the two regions, that is, the parts
 289                  which are in both regions. The result is stored in this
 290                  region.
 291     */
 292     bool Intersect(wxCoord x, wxCoord y, wxCoord width,
 293                    wxCoord height);
 294     /**
 295         Finds the intersection of this region and another, rectangular region.
 296
 297         This method always fails, i.e. returns @false, if this region is
 298         invalid but may nevertheless be safely used even in this case.
 299
 300         @return @true if successful, @false otherwise.
 301
 302         @remarks Creates the intersection of the two regions, that is, the parts
 303                  which are in both regions. The result is stored in this
 304                  region.
 305     */
 306     bool Intersect(const wxRect& rect);
 307     /**
 308         Finds the intersection of this region and another region.
 309
 310         This method always fails, i.e. returns @false, if this region is
 311         invalid but may nevertheless be safely used even in this case.
 312
 313         @return @true if successful, @false otherwise.
 314
 315         @remarks Creates the intersection of the two regions, that is, the parts
 316                  which are in both regions. The result is stored in this
 317                  region.
 318     */
 319     bool Intersect(const wxRegion& region);
 320
 321     /**
 322         Returns @true if the region is empty, @false otherwise.
 323
 324         Always returns @true if the region is invalid.
 325     */
 326     virtual bool IsEmpty() const;
 327
 328     /**
 329         Returns @true if the region is equal to, i.e. covers the same area as,
 330         another one.
 331
 332         If both this region and @a region are both invalid, they are considered
 333         to be equal.
 334     */
 335     bool IsEqual(const wxRegion& region) const;
 336
 337     //@{
 338     /**
 339         Moves the region by the specified offsets in horizontal and vertical
 340         directions.
 341
 342         This method can't be called if the region is invalid as it doesn't make
 343         sense to offset it then. Attempts to do it will result in assert
 344         failure.
 345
 346         @return @true if successful, @false otherwise (the region is unchanged
 347                  then).
 348     */
 349     bool Offset(wxCoord x, wxCoord y);
 350     bool Offset(const wxPoint& pt);
 351     //@}
 352
 353     /**
 354         Subtracts a rectangular region from this region.
 355
 356         This method always fails, i.e. returns @false, if this region is
 357         invalid but may nevertheless be safely used even in this case.
 358
 359         @return @true if successful, @false otherwise.
 360
 361         @remarks This operation combines the parts of 'this' region that are not
 362                  part of the second region. The result is stored in this
 363                  region.
 364     */
 365     bool Subtract(const wxRect& rect);
 366     /**
 367         Subtracts a region from this region.
 368
 369         This method always fails, i.e. returns @false, if this region is
 370         invalid but may nevertheless be safely used even in this case.
 371
 372         @return @true if successful, @false otherwise.
 373
 374         @remarks This operation combines the parts of 'this' region that are not
 375                  part of the second region. The result is stored in this
 376                  region.
 377     */
 378     bool Subtract(const wxRegion& region);
 379
 380     /**
 381         Finds the union of this region and another, rectangular region, specified using
 382         position and size.
 383
 384         This method can be used even if this region is invalid and has the
 385         natural behaviour in this case, i.e. makes this region equal to the
 386         given rectangle.
 387
 388         @return @true if successful, @false otherwise.
 389
 390         @remarks This operation creates a region that combines all of this region
 391                  and the second region. The result is stored in this
 392                  region.
 393     */
 394     bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 395     /**
 396         Finds the union of this region and another, rectangular region.
 397
 398         This method can be used even if this region is invalid and has the
 399         natural behaviour in this case, i.e. makes this region equal to the
 400         given rectangle.
 401
 402         @return @true if successful, @false otherwise.
 403
 404         @remarks This operation creates a region that combines all of this region
 405                  and the second region. The result is stored in this
 406                  region.
 407     */
 408     bool Union(const wxRect& rect);
 409     /**
 410         Finds the union of this region and another region.
 411
 412         This method can be used even if this region is invalid and has the
 413         natural behaviour in this case, i.e. makes this region equal to the
 414         given @a region.
 415
 416         @return @true if successful, @false otherwise.
 417
 418         @remarks This operation creates a region that combines all of this region
 419                  and the second region. The result is stored in this
 420                  region.
 421     */
 422     bool Union(const wxRegion& region);
 423     /**
 424         Finds the union of this region and the non-transparent pixels of a
 425         bitmap. The bitmap's mask is used to determine transparency. If the
 426         bitmap doesn't have a mask, the bitmap's full dimensions are used.
 427
 428         @return @true if successful, @false otherwise.
 429
 430         @remarks This operation creates a region that combines all of this region
 431                  and the second region. The result is stored in this
 432                  region.
 433     */
 434     bool Union(const wxBitmap& bmp);
 435     /**
 436         Finds the union of this region and the non-transparent pixels of a
 437         bitmap. Colour to be treated as transparent is specified in the
 438         @a transColour argument, along with an optional colour tolerance value.
 439
 440         @return @true if successful, @false otherwise.
 441
 442         @remarks This operation creates a region that combines all of this region
 443                  and the second region. The result is stored in this
 444                  region.
 445     */
 446     bool Union(const wxBitmap& bmp, const wxColour& transColour,
 447                int tolerance = 0);
 448
 449     /**
 450         Finds the Xor of this region and another, rectangular region, specified using
 451         position and size.
 452
 453         This method can be used even if this region is invalid and has the
 454         natural behaviour in this case, i.e. makes this region equal to the
 455         given rectangle.
 456
 457         @return @true if successful, @false otherwise.
 458
 459         @remarks This operation creates a region that combines all of this region
 460                  and the second region, except for any overlapping
 461                  areas. The result is stored in this region.
 462     */
 463     bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 464     /**
 465         Finds the Xor of this region and another, rectangular region.
 466
 467         This method can be used even if this region is invalid and has the
 468         natural behaviour in this case, i.e. makes this region equal to the
 469         given rectangle.
 470
 471         @return @true if successful, @false otherwise.
 472
 473         @remarks This operation creates a region that combines all of this region
 474                  and the second region, except for any overlapping
 475                  areas. The result is stored in this region.
 476     */
 477     bool Xor(const wxRect& rect);
 478     /**
 479         Finds the Xor of this region and another region.
 480
 481         This method can be used even if this region is invalid and has the
 482         natural behaviour in this case, i.e. makes this region equal to the
 483         given @a region.
 484
 485         @return @true if successful, @false otherwise.
 486
 487         @remarks This operation creates a region that combines all of this region
 488                  and the second region, except for any overlapping
 489                  areas. The result is stored in this region.
 490     */
 491     bool Xor(const wxRegion& region);
 492
 493     /**
 494         Assignment operator, using @ref overview_refcount.
 495     */
 496     wxRegion& operator=(const wxRegion& region);
 497 };
 498
 499 /**
 500     An empty region.
 501 */
 502 wxRegion wxNullRegion;