Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document and test behaviour of wxRegion methods when it is invalid.

Browse Source 
Document which wxRegion methods can and can't be used when the region itself
is invalid.

Apply the minor changes to wxGTK (Xor() didn't do the right thing, Offset()
didn't assert) and wxOSX (Offset() crashed) to make their behaviour consistent
with wxMSW.

Add a (trivial, so far, but to be extended later) wxRegion unit test checking
that the methods do indeed behave as documented.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@69461 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
2011-10-18 21:56:48 +00:00
parent caab08ee9b
commit dd4eefcb29
14 changed files with 230 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
interface/wx/region.h
View File

@@ -157,6 +157,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 IsNull() returns @true.
*/
wxRegion();
/**
@@ -202,18 +205,26 @@ public:
/**
Clears the current region.
The object becomes invalid, or null, after being cleared.
*/
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(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,6 +232,9 @@ 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
@@ -232,6 +246,9 @@ 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
@@ -243,12 +260,16 @@ 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;
@@ -259,6 +280,9 @@ public:
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 +294,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 +307,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,6 +320,8 @@ public:
/**
Returns @true if the region is empty, @false otherwise.
Always returns @true if the region is invalid.
*/
virtual bool IsEmpty() const;
@@ -297,8 +329,8 @@ public:
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 +339,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 +353,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 +366,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 +381,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 +395,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 +409,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 +450,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 +464,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 +478,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