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 license
   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     wxRegion();
 162     /**
 163         Constructs a rectangular region with the given position and size.
 164     */
 165     wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 166     /**
 167         Constructs a rectangular region from the top left point and the bottom right
 168         point.
 169     */
 170     wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
 171     /**
 172         Constructs a rectangular region a wxRect object.
 173     */
 174     wxRegion(const wxRect& rect);
 175     /**
 176         Copy constructor, uses @ref overview_refcount.
 177     */
 178     wxRegion(const wxRegion& region);
 179     /**
 180         Constructs a region corresponding to the polygon made of @a n points
 181         in the provided array.
 182         @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
 183     */
 184     wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
 185     /**
 186         Constructs a region using a bitmap. See Union() for more details.
 187     */
 188     wxRegion(const wxBitmap& bmp);
 189     /**
 190         Constructs a region using the non-transparent pixels of a bitmap.  See
 191         Union() for more details.
 192     */
 193     wxRegion(const wxBitmap& bmp, const wxColour& transColour,
 194              int tolerance = 0);
 195
 196     /**
 197         Destructor.
 198         See @ref overview_refcount_destruct "reference-counted object destruction" for
 199         more info.
 200     */
 201     virtual ~wxRegion();
 202
 203     /**
 204         Clears the current region.
 205     */
 206     virtual void Clear();
 207
 208     /**
 209         Returns a value indicating whether the given point is contained within the region.
 210
 211         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 212     */
 213     wxRegionContain Contains(wxCoord x, wxCoord y) const;
 214     /**
 215         Returns a value indicating whether the given point is contained within the region.
 216
 217         @return The return value is one of @c wxOutRegion and @c wxInRegion.
 218     */
 219     wxRegionContain Contains(const wxPoint& pt) const;
 220     /**
 221         Returns a value indicating whether the given rectangle is contained within the
 222         region.
 223
 224         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 225
 226         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 227               ::wxInRegion then indicates that all or some part of the region is
 228               contained in this region.
 229     */
 230     wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const;
 231     /**
 232         Returns a value indicating whether the given rectangle is contained within the
 233         region.
 234
 235         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 236
 237         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
 238               ::wxInRegion then indicates that all or some part of the region is
 239               contained in this region.
 240     */
 241     wxRegionContain Contains(const wxRect& rect) const;
 242
 243     /**
 244         Convert the region to a black and white bitmap with the white pixels
 245         being inside the region.
 246     */
 247     wxBitmap ConvertToBitmap() const;
 248
 249     //@{
 250     /**
 251         Returns the outer bounds of the region.
 252     */
 253     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
 254                 wxCoord& height) const;
 255     wxRect GetBox() const;
 256     //@}
 257
 258     /**
 259         Finds the intersection of this region and another, rectangular region,
 260         specified using position and size.
 261
 262         @return @true if successful, @false otherwise.
 263
 264         @remarks Creates the intersection of the two regions, that is, the parts
 265                  which are in both regions. The result is stored in this
 266                  region.
 267     */
 268     bool Intersect(wxCoord x, wxCoord y, wxCoord width,
 269                    wxCoord height);
 270     /**
 271         Finds the intersection of this region and another, rectangular region.
 272
 273         @return @true if successful, @false otherwise.
 274
 275         @remarks Creates the intersection of the two regions, that is, the parts
 276                  which are in both regions. The result is stored in this
 277                  region.
 278     */
 279     bool Intersect(const wxRect& rect);
 280     /**
 281         Finds the intersection of this region and another region.
 282
 283         @return @true if successful, @false otherwise.
 284
 285         @remarks Creates the intersection of the two regions, that is, the parts
 286                  which are in both regions. The result is stored in this
 287                  region.
 288     */
 289     bool Intersect(const wxRegion& region);
 290
 291     /**
 292         Returns @true if the region is empty, @false otherwise.
 293     */
 294     virtual bool IsEmpty() const;
 295
 296     /**
 297         Returns @true if the region is equal to, i.e. covers the same area as,
 298         another one.
 299
 300         @note If both this region and @a region are invalid, they are
 301               considered to be equal.
 302     */
 303     bool IsEqual(const wxRegion& region) const;
 304
 305     //@{
 306     /**
 307         Moves the region by the specified offsets in horizontal and vertical
 308         directions.
 309
 310         @return @true if successful, @false otherwise (the region is unchanged
 311                  then).
 312     */
 313     bool Offset(wxCoord x, wxCoord y);
 314     bool Offset(const wxPoint& pt);
 315     //@}
 316
 317     /**
 318         Subtracts a rectangular region from this region.
 319
 320         @return @true if successful, @false otherwise.
 321
 322         @remarks This operation combines the parts of 'this' region that are not
 323                  part of the second region. The result is stored in this
 324                  region.
 325     */
 326     bool Subtract(const wxRect& rect);
 327     /**
 328         Subtracts a region from this region.
 329
 330         @return @true if successful, @false otherwise.
 331
 332         @remarks This operation combines the parts of 'this' region that are not
 333                  part of the second region. The result is stored in this
 334                  region.
 335     */
 336     bool Subtract(const wxRegion& region);
 337
 338     /**
 339         Finds the union of this region and another, rectangular region, specified using
 340         position and size.
 341
 342         @return @true if successful, @false otherwise.
 343
 344         @remarks This operation creates a region that combines all of this region
 345                  and the second region. The result is stored in this
 346                  region.
 347     */
 348     bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 349     /**
 350         Finds the union of this region and another, rectangular region.
 351
 352         @return @true if successful, @false otherwise.
 353
 354         @remarks This operation creates a region that combines all of this region
 355                  and the second region. The result is stored in this
 356                  region.
 357     */
 358     bool Union(const wxRect& rect);
 359     /**
 360         Finds the union of this region and another region.
 361
 362         @return @true if successful, @false otherwise.
 363
 364         @remarks This operation creates a region that combines all of this region
 365                  and the second region. The result is stored in this
 366                  region.
 367     */
 368     bool Union(const wxRegion& region);
 369     /**
 370         Finds the union of this region and the non-transparent pixels of a
 371         bitmap. The bitmap's mask is used to determine transparency. If the
 372         bitmap doesn't have a mask, the bitmap's full dimensions are used.
 373
 374         @return @true if successful, @false otherwise.
 375
 376         @remarks This operation creates a region that combines all of this region
 377                  and the second region. The result is stored in this
 378                  region.
 379     */
 380     bool Union(const wxBitmap& bmp);
 381     /**
 382         Finds the union of this region and the non-transparent pixels of a
 383         bitmap. Colour to be treated as transparent is specified in the
 384         @a transColour argument, along with an optional colour tolerance value.
 385
 386         @return @true if successful, @false otherwise.
 387
 388         @remarks This operation creates a region that combines all of this region
 389                  and the second region. The result is stored in this
 390                  region.
 391     */
 392     bool Union(const wxBitmap& bmp, const wxColour& transColour,
 393                int tolerance = 0);
 394
 395     /**
 396         Finds the Xor of this region and another, rectangular region, specified using
 397         position and size.
 398
 399         @return @true if successful, @false otherwise.
 400
 401         @remarks This operation creates a region that combines all of this region
 402                  and the second region, except for any overlapping
 403                  areas. The result is stored in this region.
 404     */
 405     bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 406     /**
 407         Finds the Xor of this region and another, rectangular region.
 408
 409         @return @true if successful, @false otherwise.
 410
 411         @remarks This operation creates a region that combines all of this region
 412                  and the second region, except for any overlapping
 413                  areas. The result is stored in this region.
 414     */
 415     bool Xor(const wxRect& rect);
 416     /**
 417         Finds the Xor of this region and another region.
 418
 419         @return @true if successful, @false otherwise.
 420
 421         @remarks This operation creates a region that combines all of this region
 422                  and the second region, except for any overlapping
 423                  areas. The result is stored in this region.
 424     */
 425     bool Xor(const wxRegion& region);
 426
 427     /**
 428         Assignment operator, using @ref overview_refcount.
 429     */
 430     wxRegion& operator=(const wxRegion& region);
 431 };
 432
 433 /**
 434     An empty region.
 435 */
 436 wxRegion wxNullRegion;