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