API change: a single SELECTION_CHANGED not lots of SELECT and UNSELECT events

[wxWidgets.git] / docs / latex / wx / region.tex

diff --git a/docs/latex/wx/region.tex b/docs/latex/wx/region.tex
index a2828e8e244314f4a5791bf86e542b6380f4fcda..060b19f31a35f9c2a32cc3accc76ef55b415ba98 100644 (file)
--- a/docs/latex/wx/region.tex
+++ b/docs/latex/wx/region.tex
@@ -1,26 +1,51 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name:        region.tex
+%% Purpose:     wxRegion documentation
+%% Author:      wxTeam
+%% Created:
+%% RCS-ID:      $Id$
+%% Copyright:   (c) wxTeam
+%% License:     wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+

 \section{\class{wxRegion}}\label{wxregion}
 
 \section{\class{wxRegion}}\label{wxregion}
 

-A wxRegion represents a simple or complex region on a device context or window. It uses
-reference counting, so copying and assignment operations are fast.
+A wxRegion represents a simple or complex region on a device context or window.
+
+This class uses \helpref{reference counting and copy-on-write}{trefcount}
+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.

 
 \wxheading{Derived from}
 
 \helpref{wxGDIObject}{wxgdiobject}\\
 \helpref{wxObject}{wxobject}
 
 
 \wxheading{Derived from}
 
 \helpref{wxGDIObject}{wxgdiobject}\\
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/region.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{wxRegionIterator}{wxregioniterator}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \wxheading{See also}
 
 \helpref{wxRegionIterator}{wxregioniterator}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxRegion::wxRegion}\label{wxregionconstr}
+
+\membersection{wxRegion::wxRegion}\label{wxregionctor}

 
 \func{}{wxRegion}{\void}
 
 Default constructor.
 
 
 \func{}{wxRegion}{\void}
 
 Default constructor.
 

-\func{}{wxRegion}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
+\func{}{wxRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}

 
 Constructs a rectangular region with the given position and size.
 
 
 Constructs a rectangular region with the given position and size.
 


@@ -34,13 +59,32 @@ Constructs a rectangular region a wxRect object.
 
 \func{}{wxRegion}{\param{const wxRegion\&}{ region}}
 
 
 \func{}{wxRegion}{\param{const wxRegion\&}{ region}}
 

-Constructs a region by copying another region.
+Copy constructor, uses \helpref{reference counting}{trefcount}.
+
+\func{}{wxRegion}{\param{size\_t}{ n}, \param{const wxPoint }{*points}, \param{int }{fillStyle = wxWINDING\_RULE}}
+
+Constructs a region corresponding to the polygon made of {\it n} points in the
+provided array. {\it fillStyle} parameter may have values
+{\tt wxWINDING\_RULE} or {\tt wxODDEVEN\_RULE}.

 
 

-\membersection{wxRegion::\destruct{wxRegion}}
+\func{}{wxRegion}{\param{const wxBitmap\&}{ bmp}}
+
+\func{}{wxRegion}{\param{const wxBitmap\&}{ bmp},
+                  \param{const wxColour\&}{ transColour},
+                  \param{int}{ tolerance = 0}}
+
+Constructs a region using the non-transparent pixels of a bitmap.  See
+\helpref{Union}{wxregionunion} for more details.
+
+
+
+\membersection{wxRegion::\destruct{wxRegion}}\label{wxregiondtor}

 
 \func{}{\destruct{wxRegion}}{\void}
 
 Destructor.
 
 \func{}{\destruct{wxRegion}}{\void}
 
 Destructor.

+See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
+

 
 \membersection{wxRegion::Clear}\label{wxregionclear}
 
 
 \membersection{wxRegion::Clear}\label{wxregionclear}
 


@@ -48,6 +92,7 @@ Destructor.
 
 Clears the current region.
 
 
 Clears the current region.
 

+

 \membersection{wxRegion::Contains}\label{wxregioncontains}
 
 \constfunc{wxRegionContain}{Contains}{\param{long\& }{x}, \param{long\& }{y}}
 \membersection{wxRegion::Contains}\label{wxregioncontains}
 
 \constfunc{wxRegionContain}{Contains}{\param{long\& }{x}, \param{long\& }{y}}


@@ -73,9 +118,18 @@ The return value is one of wxOutRegion, wxPartRegion and wxInRegion.
 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.
 
 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.
 

+
+\membersection{wxRegion::ConvertToBitmap}\label{wxregionconverttobitmap}
+
+\constfunc{wxBitmap}{ConvertToBitmap}{}
+
+Convert the region to a black and white bitmap with the white pixels
+being inside the region.
+
+

 \membersection{wxRegion::GetBox}\label{wxregiongetbox}
 
 \membersection{wxRegion::GetBox}\label{wxregiongetbox}
 

-\constfunc{void}{GetBox}{\param{long\& }{x}, \param{long\& }{y}, \param{long\& }{width}, \param{long\& }{height}}
+\constfunc{void}{GetBox}{\param{wxCoord\& }{x}, \param{wxCoord\& }{y}, \param{wxCoord\& }{width}, \param{wxCoord\& }{height}}

 
 Returns the outer bounds of the region.
 
 
 Returns the outer bounds of the region.
 


@@ -83,9 +137,10 @@ Returns the outer bounds of the region.
 
 Returns the outer bounds of the region.
 
 
 Returns the outer bounds of the region.
 

+

 \membersection{wxRegion::Intersect}\label{wxregionintersect}
 
 \membersection{wxRegion::Intersect}\label{wxregionintersect}
 

-\func{bool}{Intersect}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
+\func{bool}{Intersect}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}

 
 Finds the intersection of this region and another, rectangular region, specified using position and size.
 
 
 Finds the intersection of this region and another, rectangular region, specified using position and size.
 


@@ -99,20 +154,31 @@ Finds the intersection of this region and another region.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+{\tt true} if successful, {\tt false} otherwise.

 
 \wxheading{Remarks}
 
 Creates the intersection of the two regions, that is, the parts which are in both regions. The result
 is stored in this region.
 
 
 \wxheading{Remarks}
 
 Creates the intersection of the two regions, that is, the parts which are in both regions. The result
 is stored in this region.
 

+

 \membersection{wxRegion::IsEmpty}\label{wxregionisempty}
 
 \constfunc{bool}{IsEmpty}{\void}
 
 \membersection{wxRegion::IsEmpty}\label{wxregionisempty}
 
 \constfunc{bool}{IsEmpty}{\void}
 

-\func{bool}{IsEmpty}{\void}
+Returns {\tt true} if the region is empty, {\tt false} otherwise.
+
+
+\membersection{wxRegion::IsEqual}\label{wxregionisequal}
+
+\constfunc{bool}{IsEqual}{\param{const wxRegion\& }{region}}

 
 

-Returns TRUE if the region is empty, FALSE otherwise.
+Returns {\tt true} if the region is equal to, i.e. covers the same area as,
+another one. Note that if both this region and \arg{region} are invalid, they
+are considered to be equal.
+
+
+\membersection{wxRegion::Subtract}\label{wxregionsubtract}

 
 \func{bool}{Subtract}{\param{const wxRect\&}{ rect}}
 
 
 \func{bool}{Subtract}{\param{const wxRect\&}{ rect}}
 


@@ -124,16 +190,31 @@ Subtracts a region from this region.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+{\tt true} if successful, {\tt false} otherwise.

 
 \wxheading{Remarks}
 
 This operation combines the parts of 'this' region that are not part of the second region.
 The result is stored in this region.
 
 
 \wxheading{Remarks}
 
 This operation combines the parts of 'this' region that are not part of the second region.
 The result is stored in this region.
 

+
+\membersection{wxRegion::Offset}\label{wxregionoffset}
+
+\func{bool}{Offset}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
+
+\func{bool}{Offset}{\param{const wxPoint\& }{ pt}}
+
+Moves the region by the specified offsets in horizontal and vertical
+directions.
+
+\wxheading{Return value}
+
+{\tt true} if successful, {\tt false} otherwise (the region is unchanged then).
+
+

 \membersection{wxRegion::Union}\label{wxregionunion}
 
 \membersection{wxRegion::Union}\label{wxregionunion}
 

-\func{bool}{Union}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
+\func{bool}{Union}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}

 
 Finds the union of this region and another, rectangular region, specified using position and size.
 
 
 Finds the union of this region and another, rectangular region, specified using position and size.
 


@@ -145,18 +226,34 @@ Finds the union of this region and another, rectangular region.
 
 Finds the union of this region and another region.
 
 
 Finds the union of this region and another region.
 

+\func{bool}{Union}{\param{const wxBitmap\&}{ bmp}}
+
+Finds the union of this region and the non-transparent pixels of a
+bitmap. Bitmap's mask is used to determine transparency. If the bitmap doesn't
+have a mask, solid rectangle of bitmap's dimensions is used.
+
+\func{bool}{Union}{\param{const wxBitmap\&}{ bmp},
+                  \param{const wxColour\&}{ transColour},
+                  \param{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
+\arg{transColour} argument, along with an
+optional colour tolerance value.
+

 \wxheading{Return value}
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+{\tt true} if successful, {\tt false} otherwise.

 
 \wxheading{Remarks}
 
 This operation creates a region that combines all of this region and the second region.
 The result is stored in this region.
 
 
 \wxheading{Remarks}
 
 This operation creates a region that combines all of this region and the second region.
 The result is stored in this region.
 

+

 \membersection{wxRegion::Xor}\label{wxregionxor}
 
 \membersection{wxRegion::Xor}\label{wxregionxor}
 

-\func{bool}{Xor}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
+\func{bool}{Xor}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}

 
 Finds the Xor of this region and another, rectangular region, specified using position and size.
 
 
 Finds the Xor of this region and another, rectangular region, specified using position and size.
 


@@ -170,18 +267,21 @@ Finds the Xor of this region and another region.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE if successful, FALSE otherwise.
+{\tt true} if successful, {\tt false} otherwise.

 
 \wxheading{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.
 
 
 \wxheading{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.
 

+

 \membersection{wxRegion::operator $=$}\label{wxregionassign}
 
 \func{void}{operator $=$}{\param{const wxRegion\&}{ region}}
 
 \membersection{wxRegion::operator $=$}\label{wxregionassign}
 
 \func{void}{operator $=$}{\param{const wxRegion\&}{ region}}
 

-Copies {\it region} by reference counting.
+Assignment operator, using \helpref{reference counting}{trefcount}.
+
+

 
 \section{\class{wxRegionIterator}}\label{wxregioniterator}
 
 
 \section{\class{wxRegionIterator}}\label{wxregioniterator}
 


@@ -191,19 +291,28 @@ 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.
 
 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 \helpref{wxWindow::OnPaint}{wxwindowonpaint} for an example of use.
+See \helpref{wxPaintEvent}{wxpaintevent} for an example of use.

 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 
 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/region.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{See also}
 
 \wxheading{See also}
 

-\helpref{wxWindow::OnPaint}{wxwindowonpaint}
+\helpref{wxPaintEvent}{wxpaintevent}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxRegionIterator::wxRegionIterator}
+
+\membersection{wxRegionIterator::wxRegionIterator}\label{wxregioniteratorctor}

 
 \func{}{wxRegionIterator}{\void}
 
 
 \func{}{wxRegionIterator}{\void}
 


@@ -213,55 +322,64 @@ Default constructor.
 
 Creates an iterator object given a region.
 
 
 Creates an iterator object given a region.
 

-\membersection{wxRegionIterator::GetX}

 
 

-\constfunc{long}{GetX}{\void}
+\membersection{wxRegionIterator::GetX}\label{wxregioniteratorgetx}
+
+\constfunc{wxCoord}{GetX}{\void}

 
 Returns the x value for the current region.
 
 
 Returns the x value for the current region.
 

-\membersection{wxRegionIterator::GetY}

 
 

-\constfunc{long}{GetY}{\void}
+\membersection{wxRegionIterator::GetY}\label{wxregioniteratorgety}
+
+\constfunc{wxCoord}{GetY}{\void}

 
 Returns the y value for the current region.
 
 
 Returns the y value for the current region.
 

-\membersection{wxRegionIterator::GetW}

 
 

-\constfunc{long}{GetW}{\void}
+\membersection{wxRegionIterator::GetW}\label{wxregioniteratorgetw}
+
+\constfunc{wxCoord}{GetW}{\void}

 
 An alias for GetWidth.
 
 
 An alias for GetWidth.
 

-\membersection{wxRegionIterator::GetWidth}

 
 

-\constfunc{long}{GetWidth}{\void}
+\membersection{wxRegionIterator::GetHeight}\label{wxregioniteratorgetheight}

 
 

-Returns the width value for the current region.
+\constfunc{wxCoord}{GetHeight}{\void}

 
 

-\membersection{wxRegionIterator::GetH}
+Returns the height value for the current region.

 
 

-\constfunc{long}{GetH}{\void}

 
 

-An alias for GetHeight.
+\membersection{wxRegionIterator::GetH}\label{wxregioniteratorgeth}

 
 

-\membersection{wxRegionIterator::GetHeight}
+\constfunc{wxCoord}{GetH}{\void}

 
 

-\constfunc{long}{GetWidth}{\void}
+An alias for GetHeight.

 
 

-Returns the width value for the current region.

 
 

-\membersection{wxRegionIterator::GetRect}
+\membersection{wxRegionIterator::GetRect}\label{wxregioniteratorgetrect}

 
 \constfunc{wxRect}{GetRect}{\void}
 
 Returns the current rectangle.
 
 
 \constfunc{wxRect}{GetRect}{\void}
 
 Returns the current rectangle.
 

-\membersection{wxRegionIterator::HaveRects}
+
+\membersection{wxRegionIterator::GetWidth}\label{wxregioniteratorgetwidth}
+
+\constfunc{wxCoord}{GetWidth}{\void}
+
+Returns the width value for the current region.
+
+
+\membersection{wxRegionIterator::HaveRects}\label{wxregioniteratorhaverects}

 
 \constfunc{bool}{HaveRects}{\void}
 
 
 \constfunc{bool}{HaveRects}{\void}
 

-Returns TRUE if there are still some rectangles; otherwise returns FALSE.
+Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.

 
 

-\membersection{wxRegionIterator::Reset}
+
+\membersection{wxRegionIterator::Reset}\label{wxregioniteratorreset}

 
 \func{void}{Reset}{\void}
 
 
 \func{void}{Reset}{\void}
 


@@ -271,17 +389,21 @@ Resets the iterator to the beginning of the rectangles.
 
 Resets the iterator to the given region.
 
 
 Resets the iterator to the given region.
 

-\membersection{wxRegionIterator::operator $++$}
+
+\membersection{wxRegionIterator::operator $++$}\label{wxregioniteratorinc}

 
 \func{void}{operator $++$}{\void}
 
 Increment operator. Increments the iterator to the next region.
 
 
 \func{void}{operator $++$}{\void}
 
 Increment operator. Increments the iterator to the next region.
 

-\membersection{wxRegionIterator::operator bool}
+\pythonnote{A wxPython alias for this operator is called {\tt Next}.}
+
+
+\membersection{wxRegionIterator::operator bool}\label{wxregioniteratorbool}

 
 \constfunc{}{operator bool}{\void}
 
 
 \constfunc{}{operator bool}{\void}
 

-Returns TRUE if there are still some rectangles; otherwise returns FALSE.
+Returns {\tt true} if there are still some rectangles; otherwise returns {\tt false}.

 
 You can use this to test the iterator object as if it were of type bool.
 
 
 You can use this to test the iterator object as if it were of type bool.