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     @class wxRegionIterator
  11     @wxheader{region.h}
  12
  13     This class is used to iterate through the rectangles in a region,
  14     typically when examining the damaged regions of a window within an OnPaint call.
  15
  16     To use it, construct an iterator object on the stack and loop through the
  17     regions, testing the object and incrementing the iterator at the end of the
  18     loop.
  19
  20     See wxPaintEvent for an example of use.
  21
  22     @library{wxcore}
  23     @category{gdi}
  24
  25     @stdobjects
  26     ::wxNullRegion
  27
  28     @see wxPaintEvent
  29 */
  30 class wxRegionIterator : public wxObject
  31 {
  32 public:
  33     //@{
  34     /**
  35         Creates an iterator object given a region.
  36     */
  37     wxRegionIterator();
  38     wxRegionIterator(const wxRegion& region);
  39     //@}
  40
  41     /**
  42         An alias for GetHeight.
  43     */
  44     wxCoord GetH() const;
  45
  46     /**
  47         Returns the height value for the current region.
  48     */
  49     wxCoord GetHeight() const;
  50
  51     /**
  52         Returns the current rectangle.
  53     */
  54     wxRect GetRect() const;
  55
  56     /**
  57         An alias for GetWidth.
  58     */
  59     wxCoord GetW() const;
  60
  61     /**
  62         Returns the width value for the current region.
  63     */
  64     wxCoord GetWidth() const;
  65
  66     /**
  67         Returns the x value for the current region.
  68     */
  69     wxCoord GetX() const;
  70
  71     /**
  72         Returns the y value for the current region.
  73     */
  74     wxCoord GetY() const;
  75
  76     /**
  77         Returns @true if there are still some rectangles; otherwise returns @false.
  78     */
  79     bool HaveRects() const;
  80
  81     //@{
  82     /**
  83         Resets the iterator to the given region.
  84     */
  85     void Reset();
  86     void Reset(const wxRegion& region);
  87     //@}
  88
  89     /**
  90         Increment operator. Increments the iterator to the next region.
  91     */
  92     void operator ++();
  93
  94     /**
  95         Returns @true if there are still some rectangles; otherwise returns @false.
  96         You can use this to test the iterator object as if it were of type bool.
  97     */
  98     operator bool() const;
  99 };
 100
 101
 102
 103 /**
 104     @class wxRegion
 105     @wxheader{region.h}
 106
 107     A wxRegion represents a simple or complex region on a device context or window.
 108
 109     This class uses @ref overview_trefcount "reference counting and copy-on-write"
 110     internally so that assignments between two instances of this class are very
 111     cheap. You can therefore use actual objects instead of pointers without
 112     efficiency problems. If an instance of this class is changed it will create
 113     its own data internally so that other instances, which previously shared the
 114     data using the reference counting, are not affected.
 115
 116     @library{wxcore}
 117     @category{data,gdi}
 118
 119     @see wxRegionIterator
 120 */
 121 class wxRegion : public wxGDIObject
 122 {
 123 public:
 124     //@{
 125     /**
 126         Constructs a region using the non-transparent pixels of a bitmap.  See
 127         Union() for more details.
 128     */
 129     wxRegion();
 130     wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 131     wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
 132     wxRegion(const wxRect& rect);
 133     wxRegion(const wxRegion& region);
 134     wxRegion(size_t n, const wxPoint points,
 135              int fillStyle = wxWINDING_RULE);
 136     wxRegion(const wxBitmap& bmp);
 137     wxRegion(const wxBitmap& bmp, const wxColour& transColour,
 138              int tolerance = 0);
 139     //@}
 140
 141     /**
 142         Destructor.
 143         See @ref overview_refcountdestruct "reference-counted object destruction" for
 144         more info.
 145     */
 146     ~wxRegion();
 147
 148     /**
 149         Clears the current region.
 150     */
 151     void Clear();
 152
 153     //@{
 154     /**
 155         Returns a value indicating whether the given rectangle is contained within the
 156         region.
 157
 158         @returns The return value is one of wxOutRegion, wxPartRegion and
 159                  wxInRegion.
 160     */
 161     wxRegionContain Contains(long& x, long& y) const;
 162     const wxRegionContain Contains(const wxPoint& pt) const;
 163     const wxRegionContain Contains(long& x, long& y,
 164                                    long& width,
 165                                    long& height) const;
 166     const wxRegionContain Contains(const wxRect& rect) const;
 167     //@}
 168
 169     /**
 170         Convert the region to a black and white bitmap with the white pixels
 171         being inside the region.
 172     */
 173     wxBitmap ConvertToBitmap() const;
 174
 175     //@{
 176     /**
 177         Returns the outer bounds of the region.
 178     */
 179     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
 180                 wxCoord& height) const;
 181     const wxRect  GetBox() const;
 182     //@}
 183
 184     //@{
 185     /**
 186         Finds the intersection of this region and another region.
 187
 188         @returns @true if successful, @false otherwise.
 189
 190         @remarks Creates the intersection of the two regions, that is, the parts
 191                  which are in both regions. The result is stored in this
 192                  region.
 193     */
 194     bool Intersect(wxCoord x, wxCoord y, wxCoord width,
 195                    wxCoord height);
 196     bool Intersect(const wxRect& rect);
 197     bool Intersect(const wxRegion& region);
 198     //@}
 199
 200     /**
 201         Returns @true if the region is empty, @false otherwise.
 202     */
 203     bool IsEmpty() const;
 204
 205     /**
 206         Returns @true if the region is equal to, i.e. covers the same area as,
 207         another one. Note that if both this region and @a region are invalid, they
 208         are considered to be equal.
 209     */
 210     bool IsEqual(const wxRegion& region) const;
 211
 212     //@{
 213     /**
 214         Moves the region by the specified offsets in horizontal and vertical
 215         directions.
 216
 217         @returns @true if successful, @false otherwise (the region is unchanged
 218                  then).
 219     */
 220     bool Offset(wxCoord x, wxCoord y);
 221     bool Offset(const wxPoint& pt);
 222     //@}
 223
 224     //@{
 225     /**
 226         Subtracts a region from this region.
 227
 228         @returns @true if successful, @false otherwise.
 229
 230         @remarks This operation combines the parts of 'this' region that are not
 231                  part of the second region. The result is stored in this
 232                  region.
 233     */
 234     bool Subtract(const wxRect& rect);
 235     bool Subtract(const wxRegion& region);
 236     //@}
 237
 238     //@{
 239     /**
 240         Finds the union of this region and the non-transparent pixels of a
 241         bitmap. Colour to be treated as transparent is specified in the
 242         @a transColour argument, along with an
 243         optional colour tolerance value.
 244
 245         @returns @true if successful, @false otherwise.
 246
 247         @remarks This operation creates a region that combines all of this region
 248                  and the second region. The result is stored in this
 249                  region.
 250     */
 251     bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 252     bool Union(const wxRect& rect);
 253     bool Union(const wxRegion& region);
 254     bool Union(const wxBitmap& bmp);
 255     bool Union(const wxBitmap& bmp, const wxColour& transColour,
 256                int tolerance = 0);
 257     //@}
 258
 259     //@{
 260     /**
 261         Finds the Xor of this region and another region.
 262
 263         @returns @true if successful, @false otherwise.
 264
 265         @remarks This operation creates a region that combines all of this region
 266                  and the second region, except for any overlapping
 267                  areas. The result is stored in this region.
 268     */
 269     bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 270     bool Xor(const wxRect& rect);
 271     bool Xor(const wxRegion& region);
 272     //@}
 273
 274     /**
 275         Assignment operator, using @ref overview_trefcount "reference counting".
 276     */
 277     void operator =(const wxRegion& region);
 278 };
 279