interface/region.h

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