X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..e4097f77c440b1f31a80fe273cc732c14d606096:/interface/wx/region.h diff --git a/interface/wx/region.h b/interface/wx/region.h index ac00b3a9ce..f528b79789 100644 --- a/interface/wx/region.h +++ b/interface/wx/region.h @@ -2,8 +2,7 @@ // Name: region.h // Purpose: interface of wxRegionIterator // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -115,12 +114,8 @@ public: /** Increment operator. Increments the iterator to the next region. - - @beginWxPythonOnly - A wxPython alias for this operator is called Next. - @endWxPythonOnly */ - void operator ++(); + wxRegionIterator& operator ++(); /** Returns @true if there are still some rectangles; otherwise returns @false. @@ -157,6 +152,9 @@ class wxRegion : public wxGDIObject public: /** Default constructor. + + This constructor creates an invalid, or null, object, i.e. calling + IsOk() on it returns @false and IsEmpty() returns @true. */ wxRegion(); /** @@ -181,7 +179,7 @@ public: in the provided array. @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE. */ - wxRegion(size_t n, const wxPoint* points, int fillStyle = wxWINDING_RULE); + wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE); /** Constructs a region using a bitmap. See Union() for more details. */ @@ -198,22 +196,30 @@ public: See @ref overview_refcount_destruct "reference-counted object destruction" for more info. */ - ~wxRegion(); + virtual ~wxRegion(); /** Clears the current region. + + The object becomes invalid, or null, after being cleared. */ - void Clear(); + virtual void Clear(); /** Returns a value indicating whether the given point is contained within the region. + This method always returns @c wxOutRegion for an invalid region but + may, nevertheless, be safely called in this case. + @return The return value is one of @c wxOutRegion and @c wxInRegion. */ - wxRegionContain Contains(long& x, long& y) const; + wxRegionContain Contains(wxCoord x, wxCoord y) const; /** Returns a value indicating whether the given point is contained within the region. + This method always returns @c wxOutRegion for an invalid region but + may, nevertheless, be safely called in this case. + @return The return value is one of @c wxOutRegion and @c wxInRegion. */ wxRegionContain Contains(const wxPoint& pt) const; @@ -221,17 +227,23 @@ public: Returns a value indicating whether the given rectangle is contained within the region. + This method always returns @c wxOutRegion for an invalid region but + may, nevertheless, be safely called in this case. + @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value ::wxInRegion then indicates that all or some part of the region is contained in this region. */ - wxRegionContain Contains(long& x, long& y, long& width, long& height) const; + wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const; /** Returns a value indicating whether the given rectangle is contained within the region. + This method always returns @c wxOutRegion for an invalid region but + may, nevertheless, be safely called in this case. + @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion. @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value @@ -243,22 +255,29 @@ public: /** Convert the region to a black and white bitmap with the white pixels being inside the region. + + This method can't be used for invalid region. */ wxBitmap ConvertToBitmap() const; //@{ /** Returns the outer bounds of the region. + + This method returns 0-sized bounding box for invalid regions. */ void GetBox(wxCoord& x, wxCoord& y, wxCoord& width, wxCoord& height) const; - const wxRect GetBox() const; + wxRect GetBox() const; //@} /** Finds the intersection of this region and another, rectangular region, specified using position and size. + This method always fails, i.e. returns @false, if this region is + invalid but may nevertheless be safely used even in this case. + @return @true if successful, @false otherwise. @remarks Creates the intersection of the two regions, that is, the parts @@ -270,6 +289,9 @@ public: /** Finds the intersection of this region and another, rectangular region. + This method always fails, i.e. returns @false, if this region is + invalid but may nevertheless be safely used even in this case. + @return @true if successful, @false otherwise. @remarks Creates the intersection of the two regions, that is, the parts @@ -280,6 +302,9 @@ public: /** Finds the intersection of this region and another region. + This method always fails, i.e. returns @false, if this region is + invalid but may nevertheless be safely used even in this case. + @return @true if successful, @false otherwise. @remarks Creates the intersection of the two regions, that is, the parts @@ -290,15 +315,17 @@ public: /** Returns @true if the region is empty, @false otherwise. + + Always returns @true if the region is invalid. */ - bool IsEmpty() const; + virtual bool IsEmpty() const; /** - Returns @true if the region is equal to, i.e. covers the same area as, + Returns @true if the region is equal to, i.e.\ covers the same area as, another one. - @note If both this region and @a region are invalid, they are - considered to be equal. + If both this region and @a region are both invalid, they are considered + to be equal. */ bool IsEqual(const wxRegion& region) const; @@ -307,6 +334,10 @@ public: Moves the region by the specified offsets in horizontal and vertical directions. + This method can't be called if the region is invalid as it doesn't make + sense to offset it then. Attempts to do it will result in assert + failure. + @return @true if successful, @false otherwise (the region is unchanged then). */ @@ -317,6 +348,9 @@ public: /** Subtracts a rectangular region from this region. + This method always fails, i.e. returns @false, if this region is + invalid but may nevertheless be safely used even in this case. + @return @true if successful, @false otherwise. @remarks This operation combines the parts of 'this' region that are not @@ -327,6 +361,9 @@ public: /** Subtracts a region from this region. + This method always fails, i.e. returns @false, if this region is + invalid but may nevertheless be safely used even in this case. + @return @true if successful, @false otherwise. @remarks This operation combines the parts of 'this' region that are not @@ -339,6 +376,10 @@ public: Finds the union of this region and another, rectangular region, specified using position and size. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given rectangle. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -349,6 +390,10 @@ public: /** Finds the union of this region and another, rectangular region. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given rectangle. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -359,6 +404,10 @@ public: /** Finds the union of this region and another region. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given @a region. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -396,6 +445,10 @@ public: Finds the Xor of this region and another, rectangular region, specified using position and size. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given rectangle. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -406,6 +459,10 @@ public: /** Finds the Xor of this region and another, rectangular region. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given rectangle. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -416,6 +473,10 @@ public: /** Finds the Xor of this region and another region. + This method can be used even if this region is invalid and has the + natural behaviour in this case, i.e. makes this region equal to the + given @a region. + @return @true if successful, @false otherwise. @remarks This operation creates a region that combines all of this region @@ -427,7 +488,7 @@ public: /** Assignment operator, using @ref overview_refcount. */ - void operator =(const wxRegion& region); + wxRegion& operator=(const wxRegion& region); }; /**