[wxWidgets.git] / interface / wx / region.h

/////////////////////////////////////////////////////////////////////////////
// Name:        region.h
// Purpose:     interface of wxRegionIterator
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    Types of results returned from a call to wxRegion::Contains().
*/
enum wxRegionContain
{
    /** The specified value is not contained within this region. */
    wxOutRegion = 0,

    /**
        The specified value is partially contained within this region.

        On Windows, this result is not supported. ::wxInRegion will be returned
        instead.
    */
    wxPartRegion = 1,

    /**
        The specified value is fully contained within this region.

        On Windows, this result will be returned even if only part of the specified
        value is contained in this region.
    */
    wxInRegion = 2
};

/**
    @class wxRegionIterator

    This class is used to iterate through the rectangles in a region,
    typically when examining the damaged regions of a window within an OnPaint call.

    To use it, construct an iterator object on the stack and loop through the
    regions, testing the object and incrementing the iterator at the end of the
    loop.

    See wxPaintEvent for an example of use.

    @library{wxcore}
    @category{gdi}

    @stdobjects
    ::wxNullRegion

    @see wxPaintEvent
*/
class wxRegionIterator : public wxObject
{
public:
    /**
        Default constructor.
    */
    wxRegionIterator();
    /**
        Creates an iterator object given a region.
    */
    wxRegionIterator(const wxRegion& region);

    /**
        An alias for GetHeight().
    */
    wxCoord GetH() const;

    /**
        Returns the height value for the current region.
    */
    wxCoord GetHeight() const;

    /**
        Returns the current rectangle.
    */
    wxRect GetRect() const;

    /**
        An alias for GetWidth().
    */
    wxCoord GetW() const;

    /**
        Returns the width value for the current region.
    */
    wxCoord GetWidth() const;

    /**
        Returns the x value for the current region.
    */
    wxCoord GetX() const;

    /**
        Returns the y value for the current region.
    */
    wxCoord GetY() const;

    /**
        Returns @true if there are still some rectangles; otherwise returns @false.
    */
    bool HaveRects() const;

    /**
        Resets the iterator to the beginning of the rectangles.
    */
    void Reset();

    /**
        Resets the iterator to the given region.
    */
    void Reset(const wxRegion& region);

    /**
        Increment operator. Increments the iterator to the next region.
    */
    wxRegionIterator& operator ++();

    /**
        Returns @true if there are still some rectangles; otherwise returns @false.

        You can use this to test the iterator object as if it were of type @c bool.
    */
    operator bool() const;
};


/**
    @class wxRegion

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

    This class uses @ref overview_refcount "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.

    @stdobjects
    - ::wxNullRegion

    @library{wxcore}
    @category{data,gdi}

    @see wxRegionIterator
*/
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();
    /**
        Constructs a rectangular region with the given position and size.
    */
    wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
    /**
        Constructs a rectangular region from the top left point and the bottom right
        point.
    */
    wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
    /**
        Constructs a rectangular region a wxRect object.
    */
    wxRegion(const wxRect& rect);
    /**
        Copy constructor, uses @ref overview_refcount.
    */
    wxRegion(const wxRegion& region);
    /**
        Constructs a region corresponding to the polygon made of @a n points
        in the provided array.
        @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
    */
    wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
    /**
        Constructs a region using a bitmap. See Union() for more details.
    */
    wxRegion(const wxBitmap& bmp);
    /**
        Constructs a region using the non-transparent pixels of a bitmap.  See
        Union() for more details.
    */
    wxRegion(const wxBitmap& bmp, const wxColour& transColour,
             int tolerance = 0);

    /**
        Destructor.
        See @ref overview_refcount_destruct "reference-counted object destruction" for
        more info.
    */
    virtual ~wxRegion();

    /**
        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;
    /**
        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(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
              ::wxInRegion then indicates that all or some part of the region is
              contained in this region.
    */
    wxRegionContain Contains(const wxRect& rect) 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.
    */
    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;
    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
                 which are in both regions. The result is stored in this
                 region.
    */
    bool Intersect(wxCoord x, wxCoord y, wxCoord width,
                   wxCoord height);
    /**
        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
                 which are in both regions. The result is stored in this
                 region.
    */
    bool Intersect(const wxRect& rect);
    /**
        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
                 which are in both regions. The result is stored in this
                 region.
    */
    bool Intersect(const wxRegion& region);

    /**
        Returns @true if the region is empty, @false otherwise.

        Always returns @true if the region is invalid.
    */
    virtual bool IsEmpty() const;

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

        If both this region and @a region are both invalid, they are considered
        to be equal.
    */
    bool IsEqual(const wxRegion& region) const;

    //@{
    /**
        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).
    */
    bool Offset(wxCoord x, wxCoord y);
    bool Offset(const wxPoint& pt);
    //@}

    /**
        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
                 part of the second region. The result is stored in this
                 region.
    */
    bool Subtract(const wxRect& rect);
    /**
        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
                 part of the second region. The result is stored in this
                 region.
    */
    bool Subtract(const wxRegion& region);

    /**
        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
                 and the second region. The result is stored in this
                 region.
    */
    bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
    /**
        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
                 and the second region. The result is stored in this
                 region.
    */
    bool Union(const wxRect& rect);
    /**
        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
                 and the second region. The result is stored in this
                 region.
    */
    bool Union(const wxRegion& region);
    /**
        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.

        @return @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 Union(const wxBitmap& bmp);
    /**
        Finds the union of this region and the non-transparent pixels of a
        bitmap. Colour to be treated as transparent is specified in the
        @a transColour argument, along with an optional colour tolerance value.

        @return @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 Union(const wxBitmap& bmp, const wxColour& transColour,
               int tolerance = 0);

    /**
        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
                 and the second region, except for any overlapping
                 areas. The result is stored in this region.
    */
    bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
    /**
        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
                 and the second region, except for any overlapping
                 areas. The result is stored in this region.
    */
    bool Xor(const wxRect& rect);
    /**
        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
                 and the second region, except for any overlapping
                 areas. The result is stored in this region.
    */
    bool Xor(const wxRegion& region);

    /**
        Assignment operator, using @ref overview_refcount.
    */
    wxRegion& operator=(const wxRegion& region);
};

/**
    An empty region.
*/
wxRegion wxNullRegion;
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: region.h
e54c96f1	3	// Purpose: interface of wxRegionIterator
23324ae1 FM	4	// Author: wxWidgets team
23324ae1 FM	5	// RCS-ID: $Id$
526954c5	6	// Licence: wxWindows licence
23324ae1 FM	7	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	8
bbc5b7f8 BP	9	/**
	10	Types of results returned from a call to wxRegion::Contains().
	11	*/
	12	enum wxRegionContain
	13	{
	14	/** The specified value is not contained within this region. */
	15	wxOutRegion = 0,
	16
	17	/**
	18	The specified value is partially contained within this region.
	19
	20	On Windows, this result is not supported. ::wxInRegion will be returned
	21	instead.
	22	*/
	23	wxPartRegion = 1,
	24
	25	/**
	26	The specified value is fully contained within this region.
	27
	28	On Windows, this result will be returned even if only part of the specified
	29	value is contained in this region.
	30	*/
	31	wxInRegion = 2
	32	};
	33
23324ae1 FM	34	/**
23324ae1 FM	35	@class wxRegionIterator
7c913512	36
23324ae1 FM	37	This class is used to iterate through the rectangles in a region,
23324ae1 FM	38	typically when examining the damaged regions of a window within an OnPaint call.
7c913512	39
23324ae1 FM	40	To use it, construct an iterator object on the stack and loop through the
	41	regions, testing the object and incrementing the iterator at the end of the
	42	loop.
7c913512	43
23324ae1	44	See wxPaintEvent for an example of use.
7c913512	45
23324ae1	46	@library{wxcore}
de022e4f RR	47	@category{gdi}
	48
	49	@stdobjects
	50	::wxNullRegion
7c913512	51
e54c96f1	52	@see wxPaintEvent
23324ae1 FM	53	*/
	54	class wxRegionIterator : public wxObject
	55	{
	56	public:
23324ae1	57	/**
bbc5b7f8	58	Default constructor.
23324ae1 FM	59	*/
23324ae1 FM	60	wxRegionIterator();
bbc5b7f8 BP	61	/**
	62	Creates an iterator object given a region.
	63	*/
7c913512	64	wxRegionIterator(const wxRegion& region);
23324ae1 FM	65
23324ae1 FM	66	/**
bbc5b7f8	67	An alias for GetHeight().
23324ae1	68	*/
328f5751	69	wxCoord GetH() const;
23324ae1 FM	70
	71	/**
	72	Returns the height value for the current region.
	73	*/
328f5751	74	wxCoord GetHeight() const;
23324ae1 FM	75
	76	/**
	77	Returns the current rectangle.
	78	*/
328f5751	79	wxRect GetRect() const;
23324ae1 FM	80
23324ae1 FM	81	/**
bbc5b7f8	82	An alias for GetWidth().
23324ae1	83	*/
328f5751	84	wxCoord GetW() const;
23324ae1 FM	85
	86	/**
	87	Returns the width value for the current region.
	88	*/
328f5751	89	wxCoord GetWidth() const;
23324ae1 FM	90
	91	/**
	92	Returns the x value for the current region.
	93	*/
328f5751	94	wxCoord GetX() const;
23324ae1 FM	95
	96	/**
	97	Returns the y value for the current region.
	98	*/
328f5751	99	wxCoord GetY() const;
23324ae1 FM	100
	101	/**
	102	Returns @true if there are still some rectangles; otherwise returns @false.
	103	*/
328f5751	104	bool HaveRects() const;
23324ae1	105
23324ae1	106	/**
bbc5b7f8	107	Resets the iterator to the beginning of the rectangles.
23324ae1 FM	108	*/
23324ae1 FM	109	void Reset();
bbc5b7f8 BP	110
	111	/**
	112	Resets the iterator to the given region.
	113	*/
7c913512	114	void Reset(const wxRegion& region);
23324ae1 FM	115
	116	/**
	117	Increment operator. Increments the iterator to the next region.
	118	*/
11e3af6e	119	wxRegionIterator& operator ++();
23324ae1 FM	120
	121	/**
	122	Returns @true if there are still some rectangles; otherwise returns @false.
bbc5b7f8 BP	123
bbc5b7f8 BP	124	You can use this to test the iterator object as if it were of type @c bool.
23324ae1	125	*/
328f5751	126	operator bool() const;
23324ae1 FM	127	};
	128
	129
e54c96f1	130
23324ae1 FM	131	/**
23324ae1 FM	132	@class wxRegion
7c913512	133
23324ae1	134	A wxRegion represents a simple or complex region on a device context or window.
7c913512	135
bbc5b7f8	136	This class uses @ref overview_refcount "reference counting and copy-on-write"
23324ae1 FM	137	internally so that assignments between two instances of this class are very
	138	cheap. You can therefore use actual objects instead of pointers without
	139	efficiency problems. If an instance of this class is changed it will create
	140	its own data internally so that other instances, which previously shared the
	141	data using the reference counting, are not affected.
7c913512	142
bbc5b7f8 BP	143	@stdobjects
	144	- ::wxNullRegion
	145
23324ae1	146	@library{wxcore}
c0cc7004	147	@category{data,gdi}
7c913512	148
e54c96f1	149	@see wxRegionIterator
23324ae1 FM	150	*/
	151	class wxRegion : public wxGDIObject
	152	{
	153	public:
23324ae1	154	/**
bbc5b7f8	155	Default constructor.
dd4eefcb VZ	156
dd4eefcb VZ	157	This constructor creates an invalid, or null, object, i.e. calling
6cdab3b4	158	IsOk() on it returns @false and IsEmpty() returns @true.
23324ae1 FM	159	*/
23324ae1 FM	160	wxRegion();
bbc5b7f8 BP	161	/**
	162	Constructs a rectangular region with the given position and size.
	163	*/
7c913512	164	wxRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
bbc5b7f8 BP	165	/**
	166	Constructs a rectangular region from the top left point and the bottom right
	167	point.
	168	*/
7c913512	169	wxRegion(const wxPoint& topLeft, const wxPoint& bottomRight);
bbc5b7f8 BP	170	/**
	171	Constructs a rectangular region a wxRect object.
	172	*/
7c913512	173	wxRegion(const wxRect& rect);
bbc5b7f8 BP	174	/**
	175	Copy constructor, uses @ref overview_refcount.
	176	*/
7c913512	177	wxRegion(const wxRegion& region);
bbc5b7f8 BP	178	/**
	179	Constructs a region corresponding to the polygon made of @a n points
	180	in the provided array.
	181	@a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
	182	*/
ccf39540	183	wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);
bbc5b7f8 BP	184	/**
	185	Constructs a region using a bitmap. See Union() for more details.
	186	*/
7c913512	187	wxRegion(const wxBitmap& bmp);
bbc5b7f8 BP	188	/**
	189	Constructs a region using the non-transparent pixels of a bitmap. See
	190	Union() for more details.
	191	*/
7c913512 FM	192	wxRegion(const wxBitmap& bmp, const wxColour& transColour,
7c913512 FM	193	int tolerance = 0);
23324ae1 FM	194
	195	/**
	196	Destructor.
bbc5b7f8	197	See @ref overview_refcount_destruct "reference-counted object destruction" for
23324ae1 FM	198	more info.
23324ae1 FM	199	*/
adaaa686	200	virtual ~wxRegion();
23324ae1 FM	201
	202	/**
	203	Clears the current region.
dd4eefcb VZ	204
dd4eefcb VZ	205	The object becomes invalid, or null, after being cleared.
23324ae1	206	*/
adaaa686	207	virtual void Clear();
23324ae1	208
bbc5b7f8 BP	209	/**
	210	Returns a value indicating whether the given point is contained within the region.
	211
dd4eefcb VZ	212	This method always returns @c wxOutRegion for an invalid region but
	213	may, nevertheless, be safely called in this case.
	214
bbc5b7f8 BP	215	@return The return value is one of @c wxOutRegion and @c wxInRegion.
bbc5b7f8 BP	216	*/
11e3af6e	217	wxRegionContain Contains(wxCoord x, wxCoord y) const;
bbc5b7f8 BP	218	/**
	219	Returns a value indicating whether the given point is contained within the region.
	220
dd4eefcb VZ	221	This method always returns @c wxOutRegion for an invalid region but
	222	may, nevertheless, be safely called in this case.
	223
bbc5b7f8 BP	224	@return The return value is one of @c wxOutRegion and @c wxInRegion.
	225	*/
	226	wxRegionContain Contains(const wxPoint& pt) const;
23324ae1 FM	227	/**
	228	Returns a value indicating whether the given rectangle is contained within the
	229	region.
3c4f71cc	230
dd4eefcb VZ	231	This method always returns @c wxOutRegion for an invalid region but
	232	may, nevertheless, be safely called in this case.
	233
bbc5b7f8 BP	234	@return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
	235
	236	@note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
	237	::wxInRegion then indicates that all or some part of the region is
	238	contained in this region.
23324ae1	239	*/
11e3af6e	240	wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const;
bbc5b7f8 BP	241	/**
	242	Returns a value indicating whether the given rectangle is contained within the
	243	region.
	244
dd4eefcb VZ	245	This method always returns @c wxOutRegion for an invalid region but
	246	may, nevertheless, be safely called in this case.
	247
bbc5b7f8 BP	248	@return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
	249
	250	@note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
	251	::wxInRegion then indicates that all or some part of the region is
	252	contained in this region.
	253	*/
	254	wxRegionContain Contains(const wxRect& rect) const;
23324ae1 FM	255
	256	/**
	257	Convert the region to a black and white bitmap with the white pixels
	258	being inside the region.
dd4eefcb VZ	259
dd4eefcb VZ	260	This method can't be used for invalid region.
23324ae1	261	*/
328f5751	262	wxBitmap ConvertToBitmap() const;
23324ae1 FM	263
	264	//@{
	265	/**
	266	Returns the outer bounds of the region.
dd4eefcb VZ	267
dd4eefcb VZ	268	This method returns 0-sized bounding box for invalid regions.
23324ae1 FM	269	*/
23324ae1 FM	270	void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
328f5751	271	wxCoord& height) const;
11e3af6e	272	wxRect GetBox() const;
23324ae1 FM	273	//@}
23324ae1 FM	274
23324ae1	275	/**
bbc5b7f8 BP	276	Finds the intersection of this region and another, rectangular region,
bbc5b7f8 BP	277	specified using position and size.
3c4f71cc	278
dd4eefcb VZ	279	This method always fails, i.e. returns @false, if this region is
	280	invalid but may nevertheless be safely used even in this case.
	281
d29a9a8a	282	@return @true if successful, @false otherwise.
3c4f71cc	283
23324ae1	284	@remarks Creates the intersection of the two regions, that is, the parts
4cc4bfaf FM	285	which are in both regions. The result is stored in this
4cc4bfaf FM	286	region.
23324ae1 FM	287	*/
	288	bool Intersect(wxCoord x, wxCoord y, wxCoord width,
	289	wxCoord height);
bbc5b7f8 BP	290	/**
	291	Finds the intersection of this region and another, rectangular region.
	292
dd4eefcb VZ	293	This method always fails, i.e. returns @false, if this region is
	294	invalid but may nevertheless be safely used even in this case.
	295
bbc5b7f8 BP	296	@return @true if successful, @false otherwise.
	297
	298	@remarks Creates the intersection of the two regions, that is, the parts
	299	which are in both regions. The result is stored in this
	300	region.
	301	*/
7c913512	302	bool Intersect(const wxRect& rect);
bbc5b7f8 BP	303	/**
	304	Finds the intersection of this region and another region.
	305
dd4eefcb VZ	306	This method always fails, i.e. returns @false, if this region is
	307	invalid but may nevertheless be safely used even in this case.
	308
bbc5b7f8 BP	309	@return @true if successful, @false otherwise.
	310
	311	@remarks Creates the intersection of the two regions, that is, the parts
	312	which are in both regions. The result is stored in this
	313	region.
	314	*/
7c913512	315	bool Intersect(const wxRegion& region);
23324ae1 FM	316
	317	/**
	318	Returns @true if the region is empty, @false otherwise.
dd4eefcb VZ	319
dd4eefcb VZ	320	Always returns @true if the region is invalid.
23324ae1	321	*/
adaaa686	322	virtual bool IsEmpty() const;
23324ae1 FM	323
	324	/**
	325	Returns @true if the region is equal to, i.e. covers the same area as,
bbc5b7f8 BP	326	another one.
bbc5b7f8 BP	327
dd4eefcb VZ	328	If both this region and @a region are both invalid, they are considered
dd4eefcb VZ	329	to be equal.
23324ae1	330	*/
328f5751	331	bool IsEqual(const wxRegion& region) const;
23324ae1 FM	332
	333	//@{
	334	/**
	335	Moves the region by the specified offsets in horizontal and vertical
	336	directions.
3c4f71cc	337
dd4eefcb VZ	338	This method can't be called if the region is invalid as it doesn't make
	339	sense to offset it then. Attempts to do it will result in assert
	340	failure.
	341
d29a9a8a	342	@return @true if successful, @false otherwise (the region is unchanged
4cc4bfaf	343	then).
23324ae1 FM	344	*/
23324ae1 FM	345	bool Offset(wxCoord x, wxCoord y);
7c913512	346	bool Offset(const wxPoint& pt);
23324ae1 FM	347	//@}
23324ae1 FM	348
23324ae1	349	/**
bbc5b7f8	350	Subtracts a rectangular region from this region.
3c4f71cc	351
dd4eefcb VZ	352	This method always fails, i.e. returns @false, if this region is
	353	invalid but may nevertheless be safely used even in this case.
	354
d29a9a8a	355	@return @true if successful, @false otherwise.
3c4f71cc	356
23324ae1	357	@remarks This operation combines the parts of 'this' region that are not
4cc4bfaf FM	358	part of the second region. The result is stored in this
4cc4bfaf FM	359	region.
23324ae1 FM	360	*/
23324ae1 FM	361	bool Subtract(const wxRect& rect);
bbc5b7f8 BP	362	/**
	363	Subtracts a region from this region.
	364
dd4eefcb VZ	365	This method always fails, i.e. returns @false, if this region is
	366	invalid but may nevertheless be safely used even in this case.
	367
bbc5b7f8 BP	368	@return @true if successful, @false otherwise.
	369
	370	@remarks This operation combines the parts of 'this' region that are not
	371	part of the second region. The result is stored in this
	372	region.
	373	*/
7c913512	374	bool Subtract(const wxRegion& region);
23324ae1	375
23324ae1	376	/**
bbc5b7f8 BP	377	Finds the union of this region and another, rectangular region, specified using
bbc5b7f8 BP	378	position and size.
3c4f71cc	379
dd4eefcb VZ	380	This method can be used even if this region is invalid and has the
	381	natural behaviour in this case, i.e. makes this region equal to the
	382	given rectangle.
	383
d29a9a8a	384	@return @true if successful, @false otherwise.
3c4f71cc	385
23324ae1	386	@remarks This operation creates a region that combines all of this region
4cc4bfaf FM	387	and the second region. The result is stored in this
4cc4bfaf FM	388	region.
23324ae1 FM	389	*/
23324ae1 FM	390	bool Union(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
bbc5b7f8 BP	391	/**
	392	Finds the union of this region and another, rectangular region.
	393
dd4eefcb VZ	394	This method can be used even if this region is invalid and has the
	395	natural behaviour in this case, i.e. makes this region equal to the
	396	given rectangle.
	397
bbc5b7f8 BP	398	@return @true if successful, @false otherwise.
	399
	400	@remarks This operation creates a region that combines all of this region
	401	and the second region. The result is stored in this
	402	region.
	403	*/
7c913512	404	bool Union(const wxRect& rect);
bbc5b7f8 BP	405	/**
	406	Finds the union of this region and another region.
	407
dd4eefcb VZ	408	This method can be used even if this region is invalid and has the
	409	natural behaviour in this case, i.e. makes this region equal to the
	410	given @a region.
	411
bbc5b7f8 BP	412	@return @true if successful, @false otherwise.
	413
	414	@remarks This operation creates a region that combines all of this region
	415	and the second region. The result is stored in this
	416	region.
	417	*/
7c913512	418	bool Union(const wxRegion& region);
bbc5b7f8 BP	419	/**
	420	Finds the union of this region and the non-transparent pixels of a
	421	bitmap. The bitmap's mask is used to determine transparency. If the
	422	bitmap doesn't have a mask, the bitmap's full dimensions are used.
	423
	424	@return @true if successful, @false otherwise.
	425
	426	@remarks This operation creates a region that combines all of this region
	427	and the second region. The result is stored in this
	428	region.
	429	*/
7c913512	430	bool Union(const wxBitmap& bmp);
bbc5b7f8 BP	431	/**
	432	Finds the union of this region and the non-transparent pixels of a
	433	bitmap. Colour to be treated as transparent is specified in the
	434	@a transColour argument, along with an optional colour tolerance value.
	435
	436	@return @true if successful, @false otherwise.
	437
	438	@remarks This operation creates a region that combines all of this region
	439	and the second region. The result is stored in this
	440	region.
	441	*/
7c913512 FM	442	bool Union(const wxBitmap& bmp, const wxColour& transColour,
7c913512 FM	443	int tolerance = 0);
23324ae1	444
23324ae1	445	/**
bbc5b7f8 BP	446	Finds the Xor of this region and another, rectangular region, specified using
bbc5b7f8 BP	447	position and size.
3c4f71cc	448
dd4eefcb VZ	449	This method can be used even if this region is invalid and has the
	450	natural behaviour in this case, i.e. makes this region equal to the
	451	given rectangle.
	452
d29a9a8a	453	@return @true if successful, @false otherwise.
3c4f71cc	454
23324ae1	455	@remarks This operation creates a region that combines all of this region
4cc4bfaf FM	456	and the second region, except for any overlapping
4cc4bfaf FM	457	areas. The result is stored in this region.
23324ae1 FM	458	*/
23324ae1 FM	459	bool Xor(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
bbc5b7f8 BP	460	/**
	461	Finds the Xor of this region and another, rectangular region.
	462
dd4eefcb VZ	463	This method can be used even if this region is invalid and has the
	464	natural behaviour in this case, i.e. makes this region equal to the
	465	given rectangle.
	466
bbc5b7f8 BP	467	@return @true if successful, @false otherwise.
	468
	469	@remarks This operation creates a region that combines all of this region
	470	and the second region, except for any overlapping
	471	areas. The result is stored in this region.
	472	*/
7c913512	473	bool Xor(const wxRect& rect);
bbc5b7f8 BP	474	/**
	475	Finds the Xor of this region and another region.
	476
dd4eefcb VZ	477	This method can be used even if this region is invalid and has the
	478	natural behaviour in this case, i.e. makes this region equal to the
	479	given @a region.
	480
bbc5b7f8 BP	481	@return @true if successful, @false otherwise.
	482
	483	@remarks This operation creates a region that combines all of this region
	484	and the second region, except for any overlapping
	485	areas. The result is stored in this region.
	486	*/
7c913512	487	bool Xor(const wxRegion& region);
23324ae1 FM	488
23324ae1 FM	489	/**
bbc5b7f8	490	Assignment operator, using @ref overview_refcount.
23324ae1	491	*/
43c48e1e	492	wxRegion& operator=(const wxRegion& region);
23324ae1	493	};
e54c96f1	494
bbc5b7f8 BP	495	/**
	496	An empty region.
	497	*/
	498	wxRegion wxNullRegion;