Version: 3.0.2

#include <wx/region.h>

+ Inheritance diagram for wxRegion:

Detailed Description

A wxRegion represents a simple or complex region on a device context or window.

This class uses reference counting and copy-on-write internally so that assignments between two instances of this class are very cheap. You can therefore use actual objects instead of pointers without efficiency problems. If an instance of this class is changed it will create its own data internally so that other instances, which previously shared the data using the reference counting, are not affected.

Predefined objects/pointers:

Library:  wxCore
Category:  Data Structures, Graphics Device Interface (GDI)
See Also
wxRegionIterator

Public Member Functions

 wxRegion ()
 Default constructor.
 
 wxRegion (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
 Constructs a rectangular region with the given position and size.
 
 wxRegion (const wxPoint &topLeft, const wxPoint &bottomRight)
 Constructs a rectangular region from the top left point and the bottom right point.
 
 wxRegion (const wxRect &rect)
 Constructs a rectangular region a wxRect object.
 
 wxRegion (const wxRegion &region)
 Copy constructor, uses Reference Counting.
 
 wxRegion (size_t n, const wxPoint *points, wxPolygonFillMode fillStyle=wxODDEVEN_RULE)
 Constructs a region corresponding to the polygon made of n points in the provided array.
 
 wxRegion (const wxBitmap &bmp)
 Constructs a region using a bitmap.
 
 wxRegion (const wxBitmap &bmp, const wxColour &transColour, int tolerance=0)
 Constructs a region using the non-transparent pixels of a bitmap.
 
virtual ~wxRegion ()
 Destructor.
 
virtual void Clear ()
 Clears the current region.
 
wxRegionContain Contains (wxCoord x, wxCoord y) const
 Returns a value indicating whether the given point is contained within the region.
 
wxRegionContain Contains (const wxPoint &pt) const
 Returns a value indicating whether the given point is contained within the region.
 
wxRegionContain Contains (wxCoord x, wxCoord y, wxCoord width, wxCoord height) const
 Returns a value indicating whether the given rectangle is contained within the region.
 
wxRegionContain Contains (const wxRect &rect) const
 Returns a value indicating whether the given rectangle is contained within the region.
 
wxBitmap ConvertToBitmap () const
 Convert the region to a black and white bitmap with the white pixels being inside the region.
 
bool Intersect (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
 Finds the intersection of this region and another, rectangular region, specified using position and size.
 
bool Intersect (const wxRect &rect)
 Finds the intersection of this region and another, rectangular region.
 
bool Intersect (const wxRegion &region)
 Finds the intersection of this region and another region.
 
virtual bool IsEmpty () const
 Returns true if the region is empty, false otherwise.
 
bool IsEqual (const wxRegion &region) const
 Returns true if the region is equal to, i.e. covers the same area as, another one.
 
bool Subtract (const wxRect &rect)
 Subtracts a rectangular region from this region.
 
bool Subtract (const wxRegion &region)
 Subtracts a region from this region.
 
bool Union (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
 Finds the union of this region and another, rectangular region, specified using position and size.
 
bool Union (const wxRect &rect)
 Finds the union of this region and another, rectangular region.
 
bool Union (const wxRegion &region)
 Finds the union of this region and another region.
 
bool Union (const wxBitmap &bmp)
 Finds the union of this region and the non-transparent pixels of a bitmap.
 
bool Union (const wxBitmap &bmp, const wxColour &transColour, int tolerance=0)
 Finds the union of this region and the non-transparent pixels of a bitmap.
 
bool Xor (wxCoord x, wxCoord y, wxCoord width, wxCoord height)
 Finds the Xor of this region and another, rectangular region, specified using position and size.
 
bool Xor (const wxRect &rect)
 Finds the Xor of this region and another, rectangular region.
 
bool Xor (const wxRegion &region)
 Finds the Xor of this region and another region.
 
wxRegionoperator= (const wxRegion &region)
 Assignment operator, using Reference Counting.
 
void GetBox (wxCoord &x, wxCoord &y, wxCoord &width, wxCoord &height) const
 Returns the outer bounds of the region.
 
wxRect GetBox () const
 Returns the outer bounds of the region.
 
bool Offset (wxCoord x, wxCoord y)
 Moves the region by the specified offsets in horizontal and vertical directions.
 
bool Offset (const wxPoint &pt)
 Moves the region by the specified offsets in horizontal and vertical directions.
 
- Public Member Functions inherited from wxGDIObject
 wxGDIObject ()
 Default constructor.
 
- Public Member Functions inherited from wxObject
 wxObject ()
 Default ctor; initializes to NULL the internal reference data.
 
 wxObject (const wxObject &other)
 Copy ctor.
 
virtual ~wxObject ()
 Destructor.
 
virtual wxClassInfoGetClassInfo () const
 This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar).
 
wxObjectRefDataGetRefData () const
 Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
 
bool IsKindOf (const wxClassInfo *info) const
 Determines whether this class is a subclass of (or the same class as) the given class.
 
bool IsSameAs (const wxObject &obj) const
 Returns true if this object has the same data pointer as obj.
 
void Ref (const wxObject &clone)
 Makes this object refer to the data in clone.
 
void SetRefData (wxObjectRefData *data)
 Sets the wxObject::m_refData pointer.
 
void UnRef ()
 Decrements the reference count in the associated data, and if it is zero, deletes the data.
 
void UnShare ()
 This is the same of AllocExclusive() but this method is public.
 
void operator delete (void *buf)
 The delete operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 
void * operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
 The new operator is defined for debugging versions of the library only, when the identifier WXDEBUG is defined.
 

Additional Inherited Members

- Protected Member Functions inherited from wxObject
void AllocExclusive ()
 Ensure that this object's data is not shared with any other object.
 
virtual wxObjectRefDataCreateRefData () const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it.
 
virtual wxObjectRefDataCloneRefData (const wxObjectRefData *data) const
 Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data.
 
- Protected Attributes inherited from wxObject
wxObjectRefDatam_refData
 Pointer to an object which is the object's reference-counted data.
 

Constructor & Destructor Documentation

wxRegion::wxRegion ( )

Default constructor.

This constructor creates an invalid, or null, object, i.e. calling IsOk() on it returns false and IsEmpty() returns true.

wxRegion::wxRegion ( wxCoord  x,
wxCoord  y,
wxCoord  width,
wxCoord  height 
)

Constructs a rectangular region with the given position and size.

wxRegion::wxRegion ( const wxPoint topLeft,
const wxPoint bottomRight 
)

Constructs a rectangular region from the top left point and the bottom right point.

wxRegion::wxRegion ( const wxRect rect)

Constructs a rectangular region a wxRect object.

wxRegion::wxRegion ( const wxRegion region)

Copy constructor, uses Reference Counting.

wxRegion::wxRegion ( size_t  n,
const wxPoint points,
wxPolygonFillMode  fillStyle = wxODDEVEN_RULE 
)

Constructs a region corresponding to the polygon made of n points in the provided array.

fillStyle parameter may have values wxWINDING_RULE or wxODDEVEN_RULE.

wxRegion::wxRegion ( const wxBitmap bmp)

Constructs a region using a bitmap.

See Union() for more details.

wxRegion::wxRegion ( const wxBitmap bmp,
const wxColour transColour,
int  tolerance = 0 
)

Constructs a region using the non-transparent pixels of a bitmap.

See Union() for more details.

virtual wxRegion::~wxRegion ( )
virtual

Destructor.

See reference-counted object destruction for more info.

Member Function Documentation

virtual void wxRegion::Clear ( )
virtual

Clears the current region.

The object becomes invalid, or null, after being cleared.

wxRegionContain wxRegion::Contains ( wxCoord  x,
wxCoord  y 
) const

Returns a value indicating whether the given point is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

Returns
The return value is one of wxOutRegion and wxInRegion.
wxRegionContain wxRegion::Contains ( const wxPoint pt) const

Returns a value indicating whether the given point is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

Returns
The return value is one of wxOutRegion and wxInRegion.
wxRegionContain wxRegion::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 wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

Returns
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 wxRegion::Contains ( const wxRect rect) const

Returns a value indicating whether the given rectangle is contained within the region.

This method always returns wxOutRegion for an invalid region but may, nevertheless, be safely called in this case.

Returns
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.
wxBitmap wxRegion::ConvertToBitmap ( ) const

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.

void wxRegion::GetBox ( wxCoord x,
wxCoord y,
wxCoord width,
wxCoord height 
) const

Returns the outer bounds of the region.

This method returns 0-sized bounding box for invalid regions.

wxRect wxRegion::GetBox ( ) const

Returns the outer bounds of the region.

This method returns 0-sized bounding box for invalid regions.

bool wxRegion::Intersect ( wxCoord  x,
wxCoord  y,
wxCoord  width,
wxCoord  height 
)

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.

Returns
true if successful, false otherwise.
Remarks
Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.
bool wxRegion::Intersect ( const wxRect rect)

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.

Returns
true if successful, false otherwise.
Remarks
Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.
bool wxRegion::Intersect ( const wxRegion region)

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.

Returns
true if successful, false otherwise.
Remarks
Creates the intersection of the two regions, that is, the parts which are in both regions. The result is stored in this region.
virtual bool wxRegion::IsEmpty ( ) const
virtual

Returns true if the region is empty, false otherwise.

Always returns true if the region is invalid.

bool wxRegion::IsEqual ( const wxRegion region) const

Returns true if the region is equal to, i.e. covers the same area as, another one.

If both this region and region are both invalid, they are considered to be equal.

bool wxRegion::Offset ( wxCoord  x,
wxCoord  y 
)

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.

Returns
true if successful, false otherwise (the region is unchanged then).
bool wxRegion::Offset ( const wxPoint pt)

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.

Returns
true if successful, false otherwise (the region is unchanged then).
wxRegion& wxRegion::operator= ( const wxRegion region)

Assignment operator, using Reference Counting.

bool wxRegion::Subtract ( const wxRect rect)

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.

Returns
true if successful, false otherwise.
Remarks
This operation combines the parts of 'this' region that are not part of the second region. The result is stored in this region.
bool wxRegion::Subtract ( const wxRegion region)

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.

Returns
true if successful, false otherwise.
Remarks
This operation combines the parts of 'this' region that are not part of the second region. The result is stored in this region.
bool wxRegion::Union ( wxCoord  x,
wxCoord  y,
wxCoord  width,
wxCoord  height 
)

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.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region. The result is stored in this region.
bool wxRegion::Union ( const wxRect rect)

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.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region. The result is stored in this region.
bool wxRegion::Union ( const wxRegion region)

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 region.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region. The result is stored in this region.
bool wxRegion::Union ( const wxBitmap bmp)

Finds the union of this region and the non-transparent pixels of a bitmap.

The bitmap's mask is used to determine transparency. If the bitmap doesn't have a mask, the bitmap's full dimensions are used.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region. The result is stored in this region.
bool wxRegion::Union ( const wxBitmap bmp,
const wxColour transColour,
int  tolerance = 0 
)

Finds the union of this region and the non-transparent pixels of a bitmap.

Colour to be treated as transparent is specified in the transColour argument, along with an optional colour tolerance value.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region. The result is stored in this region.
bool wxRegion::Xor ( wxCoord  x,
wxCoord  y,
wxCoord  width,
wxCoord  height 
)

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.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.
bool wxRegion::Xor ( const wxRect rect)

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.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.
bool wxRegion::Xor ( const wxRegion region)

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 region.

Returns
true if successful, false otherwise.
Remarks
This operation creates a region that combines all of this region and the second region, except for any overlapping areas. The result is stored in this region.