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     @wxheader{region.h}
 103
 104     A wxRegion represents a simple or complex region on a device context or window.
 105
 106     This class uses @ref overview_trefcount "reference counting and copy-on-write"
 107     internally so that assignments between two instances of this class are very
 108     cheap. You can therefore use actual objects instead of pointers without
 109     efficiency problems. If an instance of this class is changed it will create
 110     its own data internally so that other instances, which previously shared the
 111     data using the reference counting, are not affected.
 112
 113     @library{wxcore}
 114     @category{data,gdi}
 115
 116     @see wxRegionIterator
 117 */
 118 class wxRegion : public wxGDIObject
 119 {
 120 public:
 121     //@{
 122     /**
 123         Constructs a region using the non-transparent pixels of a bitmap.  See
 124         Union() for more details.
 125     */
 126     wxRegion();
 127     wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 128     wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
 129     wxRegion(const wxRect& rect);
 130     wxRegion(const wxRegion& region);
 131     wxRegion(size_t n, const wxPoint points,
 132              int fillStyle = wxWINDING_RULE);
 133     wxRegion(const wxBitmap& bmp);
 134     wxRegion(const wxBitmap& bmp, const wxColour& transColour,
 135              int tolerance = 0);
 136     //@}
 137
 138     /**
 139         Destructor.
 140         See @ref overview_refcountdestruct "reference-counted object destruction" for
 141         more info.
 142     */
 143     ~wxRegion();
 144
 145     /**
 146         Clears the current region.
 147     */
 148     void Clear();
 149
 150     //@{
 151     /**
 152         Returns a value indicating whether the given rectangle is contained within the
 153         region.
 154
 155         @returns The return value is one of wxOutRegion, wxPartRegion and
 156                  wxInRegion.
 157     */
 158     wxRegionContain Contains(long& x, long& y) const;
 159     const wxRegionContain Contains(const wxPoint& pt) const;
 160     const wxRegionContain Contains(long& x, long& y,
 161                                    long& width,
 162                                    long& height) const;
 163     const wxRegionContain Contains(const wxRect& rect) const;
 164     //@}
 165
 166     /**
 167         Convert the region to a black and white bitmap with the white pixels
 168         being inside the region.
 169     */
 170     wxBitmap ConvertToBitmap() const;
 171
 172     //@{
 173     /**
 174         Returns the outer bounds of the region.
 175     */
 176     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
 177                 wxCoord& height) const;
 178     const wxRect  GetBox() const;
 179     //@}
 180
 181     //@{
 182     /**
 183         Finds the intersection of this region and another region.
 184
 185         @returns @true if successful, @false otherwise.
 186
 187         @remarks Creates the intersection of the two regions, that is, the parts
 188                  which are in both regions. The result is stored in this
 189                  region.
 190     */
 191     bool Intersect(wxCoord x, wxCoord y, wxCoord width,
 192                    wxCoord height);
 193     bool Intersect(const wxRect& rect);
 194     bool Intersect(const wxRegion& region);
 195     //@}
 196
 197     /**
 198         Returns @true if the region is empty, @false otherwise.
 199     */
 200     bool IsEmpty() const;
 201
 202     /**
 203         Returns @true if the region is equal to, i.e. covers the same area as,
 204         another one. Note that if both this region and @a region are invalid, they
 205         are considered to be equal.
 206     */
 207     bool IsEqual(const wxRegion& region) const;
 208
 209     //@{
 210     /**
 211         Moves the region by the specified offsets in horizontal and vertical
 212         directions.
 213
 214         @returns @true if successful, @false otherwise (the region is unchanged
 215                  then).
 216     */
 217     bool Offset(wxCoord x, wxCoord y);
 218     bool Offset(const wxPoint& pt);
 219     //@}
 220
 221     //@{
 222     /**
 223         Subtracts a region from this region.
 224
 225         @returns @true if successful, @false otherwise.
 226
 227         @remarks This operation combines the parts of 'this' region that are not
 228                  part of the second region. The result is stored in this
 229                  region.
 230     */
 231     bool Subtract(const wxRect& rect);
 232     bool Subtract(const wxRegion& region);
 233     //@}
 234
 235     //@{
 236     /**
 237         Finds the union of this region and the non-transparent pixels of a
 238         bitmap. Colour to be treated as transparent is specified in the
 239         @a transColour argument, along with an
 240         optional colour tolerance value.
 241
 242         @returns @true if successful, @false otherwise.
 243
 244         @remarks This operation creates a region that combines all of this region
 245                  and the second region. The result is stored in this
 246                  region.
 247     */
 248     bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 249     bool Union(const wxRect& rect);
 250     bool Union(const wxRegion& region);
 251     bool Union(const wxBitmap& bmp);
 252     bool Union(const wxBitmap& bmp, const wxColour& transColour,
 253                int tolerance = 0);
 254     //@}
 255
 256     //@{
 257     /**
 258         Finds the Xor of this region and another region.
 259
 260         @returns @true if successful, @false otherwise.
 261
 262         @remarks This operation creates a region that combines all of this region
 263                  and the second region, except for any overlapping
 264                  areas. The result is stored in this region.
 265     */
 266     bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 267     bool Xor(const wxRect& rect);
 268     bool Xor(const wxRegion& region);
 269     //@}
 270
 271     /**
 272         Assignment operator, using @ref overview_trefcount "reference counting".
 273     */
 274     void operator =(const wxRegion& region);
 275 };
 276