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