Added wxVariant documentation; updated wxWindow, wxScrollBar docs

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1082 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/category.tex

@@ -220,6 +220,8 @@ These are the data structure classes supported by wxWindows.
 \twocolitem{\helpref{wxRealPoint}{wxrealpoint}}{Representation of a point using floating point numbers}
 \twocolitem{\helpref{wxSize}{wxsize}}{Representation of a size}
 \twocolitem{\helpref{wxTime}{wxtime}}{A class for time manipulation}
+\twocolitem{\helpref{wxVariant}{wxvariant}}{A class for storing arbitrary types
+that may change at run-time.}
 \end{twocollist}
 
 {\large {\bf Run-time class information system}}

docs/latex/wx/classes.tex

@@ -181,6 +181,7 @@ $$\image{14cm;0cm}{wxclass.ps}$$
 \input upduievt.tex
 \input url.tex
 \input validatr.tex
+\input variant.tex
 \input view.tex
 \input wave.tex
 \input window.tex

docs/latex/wx/scrolbar.tex

@@ -141,15 +141,15 @@ same as the thumb size.
 
 \helpref{wxScrollBar::SetScrollbar}{wxscrollbarsetscrollbar}
 
-\membersection{wxScrollBar::GetPosition}\label{wxscrollbargetposition}
+\membersection{wxScrollBar::GetThumbPosition}\label{wxscrollbargetthumbposition}
 
-\constfunc{int}{GetPosition}{\void}
+\constfunc{int}{GetThumbPosition}{\void}
 
-Returns the current position of the scrollbar.
+Returns the current position of the scrollbar thumb.
 
 \wxheading{See also}
 
-\helpref{wxScrollBar::SetPosition}{wxscrollbarsetposition}
+\helpref{wxScrollBar::SetThumbPosition}{wxscrollbarsetthumbposition}
 
 \membersection{wxScrollBar::GetThumbLength}\label{wxscrollbargetthumblength}
 
@@ -207,9 +207,9 @@ At present, this needs to be called {\it before} other set functions.
 \helpref{wxScrollBar::GetPageSize}{wxscrollbargetpagesize}
 \end{comment}
 
-\membersection{wxScrollBar::SetPosition}\label{wxscrollbarsetposition}
+\membersection{wxScrollBar::SetThumbPosition}\label{wxscrollbarsetthumbposition}
 
-\func{void}{SetPosition}{\param{int}{ viewStart}}
+\func{void}{SetThumbPosition}{\param{int}{ viewStart}}
 
 Sets the position of the scrollbar.
 
@@ -219,7 +219,7 @@ Sets the position of the scrollbar.
 
 \wxheading{See also}
 
-\helpref{wxScrollBar::GetPosition}{wxscrollbargetposition}
+\helpref{wxScrollBar::GetThumbPosition}{wxscrollbargetthumbposition}
 
 \membersection{wxScrollBar::SetScrollbar}\label{wxscrollbarsetscrollbar}
 

docs/latex/wx/variant.tex

@@ -0,0 +1,436 @@
+\section{\class{wxVariant}}\label{wxvariant}
+
+The {\bf wxVariant} class represents a container for any type.
+A variant's value can be changed at run time, possibly to a different type of value.
+
+As standard, wxVariant can store values of type bool, char, double, long, string,
+string list, time, date, void pointer, list of strings, and list of variants. However, an application can extend
+wxVariant's capabilities by deriving from the class \helpref{wxVariantData}{wxvariantdata} and
+using the wxVariantData form of the wxVariant constructor or assignment operator
+to assign this data to a variant. Actual values for user-defined types will need to be accessed
+via the wxVariantData object, unlike the case for basic data types where convenience
+functions such as GetLong can be used.
+
+This class is useful for reducing the programming for certain tasks, such as an editor
+for different data types, or a remote procedure call protocol.
+
+An optional name member is associated with a wxVariant. This might be used, for example, in CORBA
+or OLE automation classes, where named parameters are required.
+
+wxVariant is similar to wxExpr and also to wxPropertyValue. However, wxExpr is efficiency-optimized for
+a restricted range of data types, whereas wxVariant is less efficient but more extensible.
+wxPropertyValue may be replaced by wxVariant eventually.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{See also}
+
+\helpref{wxVariantData}{wxvariantdata}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxVariant::wxVariant}\label{wxvariantctor}
+
+\func{}{wxVariant}{\void}
+
+Default constructor.
+
+\func{}{wxVariant}{\param{const wxVariant\& }{variant}}
+
+Copy constructor.
+
+\func{}{wxVariant}{\param{const char*}{ value}, \param{const wxString\& }{name = ``"}}\\
+\func{}{wxVariant}{\param{const wxString\&}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a string value.
+
+\func{}{wxVariant}{\param{char}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a character value.
+
+\func{}{wxVariant}{\param{long}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from an integer value. You may need to cast to (long) to
+avoid confusion with other constructors (such as the bool constructor).
+
+\func{}{wxVariant}{\param{bool}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a boolean value.
+
+\func{}{wxVariant}{\param{double}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a double-precision floating point value.
+
+\func{}{wxVariant}{\param{const wxList\&}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a list of wxVariant objects. This constructor
+copies {\it value}, the application is still responsible for
+deleting {\it value} and its contents.
+
+\func{}{wxVariant}{\param{const wxStringList\&}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a list of strings. This constructor
+copies {\it value}, the application is still responsible for
+deleting {\it value} and its contents.
+
+%Note: this constructor is currently disabled because it causes a C++ ambiguity.
+
+\func{}{wxVariant}{\param{const wxTime\&}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a time.
+
+\func{}{wxVariant}{\param{const wxDate\&}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a date.
+
+\func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}}
+
+Construction from a void pointer.
+
+\func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}}
+
+Construction from user-defined data. The variant holds on to the {\it data} pointer.
+
+\membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor}
+
+\func{}{\destruct{wxVariant}}{\void}
+
+Destructor.
+
+\membersection{wxVariant::Append}\label{wxvariantappend}
+
+\func{void}{Append}{\param{const wxVariant\&}{ value}}
+
+Appends a value to the list.
+
+\membersection{wxVariant::ClearList}\label{wxvariantclearlist}
+
+\func{void}{ClearList}{\void}
+
+Deletes the contents of the list.
+
+\membersection{wxVariant::GetCount}\label{wxvariantgetcount}
+
+\constfunc{int}{GetCount}{\void}
+
+Returns the number of elements in the list.
+
+\membersection{wxVariant::Delete}\label{wxvariantdelete}
+
+\func{bool}{Delete}{\param{int }{item}}
+
+Deletes the zero-based {\it item} from the list.
+
+\membersection{wxVariant::GetBool}\label{wxvariantgetbool}
+
+\constfunc{bool}{GetBool}{\void}
+
+Returns the boolean value.
+
+\membersection{wxVariant::GetChar}\label{wxvariantgetchar}
+
+\constfunc{char}{GetChar}{\void}
+
+Returns the character value.
+
+\membersection{wxVariant::GetData}\label{wxvariantgetdata}
+
+\constfunc{wxVariantData*}{GetData}{\void}
+
+Returns a pointer to the internal variant data.
+
+\membersection{wxVariant::GetDate}\label{wxvariantgetdate}
+
+\constfunc{wxDate}{GetDate}{\void}
+
+Gets the date value.
+
+\membersection{wxVariant::GetDouble}\label{wxvariantgetdouble}
+
+\constfunc{double}{GetDouble}{\void}
+
+Returns the floating point value.
+
+\membersection{wxVariant::GetLong}\label{wxvariantgetlong}
+
+\constfunc{long}{GetLong}{\void}
+
+Returns the integer value.
+
+\membersection{wxVariant::GetName}\label{wxvariantgetname}
+
+\constfunc{const wxString\&}{GetName}{\void}
+
+Returns a constant reference to the variant name.
+
+\membersection{wxVariant::GetString}\label{wxvariantgetstring}
+
+\constfunc{wxString}{GetString}{\void}
+
+Gets the string value.
+
+\membersection{wxVariant::GetTime}\label{wxvariantgettime}
+
+\constfunc{wxTime}{GetTime}{\void}
+
+Gets the time value.
+
+\membersection{wxVariant::GetType}\label{wxvariantgettype}
+
+\constfunc{wxString}{GetType}{\void}
+
+Returns the value type as a string. The built-in types are: bool, char, date, double, list, long, string, stringlist, time, void*.
+
+If the variant is null, the value type returned is the string ``null" (not the empty string).
+
+\membersection{wxVariant::GetVoidPtr}\label{wxvariantgetvoidptr}
+
+\constfunc{void*}{GetVoidPtr}{\void}
+
+Gets the void pointer value.
+
+\membersection{wxVariant::Insert}\label{wxvariantinsert}
+
+\func{void}{Insert}{\param{const wxVariant\&}{ value}}
+
+Inserts a value at the front of the list.
+
+\membersection{wxVariant::IsNull}\label{wxvariantisnull}
+
+\constfunc{bool}{IsNull}{\void}
+
+Returns TRUE if there is no data associated with this variant, FALSE if there is data.
+
+\membersection{wxVariant::IsType}\label{wxvariantistype}
+
+\constfunc{bool}{IsType}{\param{const wxString\&}{ type}}
+
+Returns TRUE if {\it type} matches the type of the variant, FALSE otherwise.
+
+\membersection{wxVariant::MakeNull}\label{wxvariantmakenull}
+
+\func{void}{MakeNull}{\void}
+
+Makes the variant null by deleting the internal data.
+
+\membersection{wxVariant::MakeString}\label{wxvariantmakestring}
+
+\constfunc{wxString}{MakeString}{\void}
+
+Makes a string representation of the variant value (for any type).
+
+\membersection{wxVariant::Member}\label{wxvariantmember}
+
+\constfunc{bool}{Member}{\param{const wxVariant\&}{ value}}
+
+Returns TRUE if {\it value} matches an element in the list.
+
+\membersection{wxVariant::NullList}\label{wxvariantnulllist}
+
+\func{void}{NullList}{\void}
+
+Makes an empty list. This differs from a null variant which has no data; a null list
+is of type list, but the number of elements in the list is zero.
+
+\membersection{wxVariant::SetData}\label{wxvariantsetdata}
+
+\func{void}{SetData}{\param{wxVariantData*}{ data}}
+
+Sets the internal variant data, deleting the existing data if there is any.
+
+\membersection{wxVariant::operator $=$}\label{wxvariantassignment}
+
+\func{void}{operator $=$}{\param{const wxVariant\& }{value}}
+
+\func{void}{operator $=$}{\param{wxVariantData* }{value}}
+
+\func{void}{operator $=$}{\param{const wxString\& }{value}}
+
+\func{void}{operator $=$}{\param{const char* }{value}}
+
+\func{void}{operator $=$}{\param{char }{value}}
+
+\func{void}{operator $=$}{\param{const long }{value}}
+
+\func{void}{operator $=$}{\param{const bool }{value}}
+
+\func{void}{operator $=$}{\param{const double }{value}}
+
+\func{void}{operator $=$}{\param{const wxDate\& }{value}}
+
+\func{void}{operator $=$}{\param{const wxTime\& }{value}}
+
+\func{void}{operator $=$}{\param{void* }{value}}
+
+\func{void}{operator $=$}{\param{const wxList\& }{value}}
+
+\func{void}{operator $=$}{\param{const wxStringList\& }{value}}
+
+Assignment operators.
+
+\membersection{wxVariant::operator $==$}\label{wxvarianteq}
+
+\func{bool}{operator $==$}{\param{const wxVariant\& }{value}}
+
+\func{bool}{operator $==$}{\param{const wxString\& }{value}}
+
+\func{bool}{operator $==$}{\param{const char* }{value}}
+
+\func{bool}{operator $==$}{\param{char }{value}}
+
+\func{bool}{operator $==$}{\param{const long }{value}}
+
+\func{bool}{operator $==$}{\param{const bool }{value}}
+
+\func{bool}{operator $==$}{\param{const double }{value}}
+
+\func{bool}{operator $==$}{\param{const wxDate\& }{value}}
+
+\func{bool}{operator $==$}{\param{const wxTime\& }{value}}
+
+\func{bool}{operator $==$}{\param{void* }{value}}
+
+\func{bool}{operator $==$}{\param{const wxList\& }{value}}
+
+\func{bool}{operator $==$}{\param{const wxStringList\& }{value}}
+
+Equality test operators.
+
+\membersection{wxVariant::operator $!=$}\label{wxvariantneq}
+
+\func{bool}{operator $!=$}{\param{const wxVariant\& }{value}}
+
+\func{bool}{operator $!=$}{\param{const wxString\& }{value}}
+
+\func{bool}{operator $!=$}{\param{const char* }{value}}
+
+\func{bool}{operator $!=$}{\param{char }{value}}
+
+\func{bool}{operator $!=$}{\param{const long }{value}}
+
+\func{bool}{operator $!=$}{\param{const bool }{value}}
+
+\func{bool}{operator $!=$}{\param{const double }{value}}
+
+\func{bool}{operator $!=$}{\param{const wxDate\& }{value}}
+
+\func{bool}{operator $!=$}{\param{const wxTime\& }{value}}
+
+\func{bool}{operator $!=$}{\param{void* }{value}}
+
+\func{bool}{operator $!=$}{\param{const wxList\& }{value}}
+
+\func{bool}{operator $!=$}{\param{const wxStringList\& }{value}}
+
+Inequality test operators.
+
+\membersection{wxVariant::operator $[]$}\label{wxvariantarray}
+
+\constfunc{wxVariant}{operator $[]$}{\param{size\_t }{idx}}
+
+Returns the value at {\it idx} (zero-based).
+
+\func{wxVariant\&}{operator $[]$}{\param{size\_t }{idx}}
+
+Returns a reference to the value at {\it idx} (zero-based). This can be used
+to change the value at this index.
+
+\membersection{wxVariant::operator char}\label{wxvariantchar}
+
+\constfunc{char}{operator char}{\void}
+
+Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}.
+
+\membersection{wxVariant::operator double}\label{wxvariantdouble}
+
+\constfunc{double}{operator double}{\void}
+
+Operator for implicit conversion to a double, using \helpref{wxVariant::GetDouble}{wxvariantgetdouble}.
+
+\constfunc{long}{operator long}{\void}
+
+Operator for implicit conversion to a long, using \helpref{wxVariant::GetLong}{wxvariantgetlong}.
+
+\membersection{wxVariant::operator wxDate}\label{wxvariantwxdate}
+
+\constfunc{wxDate}{operator wxDate}{\void}
+
+Operator for implicit conversion to a wxDate, using \helpref{wxVariant::GetDate}{wxvariantgetdate}.
+
+\membersection{wxVariant::operator wxString}\label{wxvariantwxstring}
+
+\constfunc{wxString}{operator wxString}{\void}
+
+Operator for implicit conversion to a string, using \helpref{wxVariant::MakeString}{wxvariantmakestring}.
+
+\membersection{wxVariant::operator wxTime}\label{wxvariantwxtime}
+
+\constfunc{wxTime}{operator wxTime}{\void}
+
+Operator for implicit conversion to a wxTime, using \helpref{wxVariant::GetTime}{wxvariantgettime}.
+
+\membersection{wxVariant::operator void*}\label{wxvariantvoid}
+
+\constfunc{void*}{operator void*}{\void}
+
+Operator for implicit conversion to a pointer to a void, using \helpref{wxVariant::GetVoidPtr}{wxvariantgetvoidptr}.
+
+\section{\class{wxVariantData}}\label{wxvariantdata}
+
+The {\bf wxVariantData} is used to implement a new type for wxVariant. Derive from wxVariantData,
+and override the pure virtual functions.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{See also}
+
+\helpref{wxVariant}{wxvariant}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxVariantData::wxVariantData}\label{wxvariantdatactor}
+
+\func{}{wxVariantData}{\void}
+
+Default constructor.
+
+\membersection{wxVariantData::Copy}\label{wxvariantdatacopy}
+
+\func{void}{Copy}{\param{wxVariantData\&}{ data}}
+
+Copy the data from `this' object to {\it data}.
+
+\membersection{wxVariantData::Eq}\label{wxvariantdataeq}
+
+\constfunc{bool}{Eq}{\param{wxVariantData\&}{ data}}
+
+Returns TRUE if this object is equal to {\it data}.
+
+\membersection{wxVariantData::GetType}\label{wxvariantdatagettype}
+
+\constfunc{wxString}{GetType}{\void}
+
+Returns the string type of the data.
+
+\membersection{wxVariantData::Read}\label{wxvariantdataread}
+
+\func{bool}{Read}{\param{ostream\&}{ stream}}
+
+\func{bool}{Read}{\param{wxString\&}{ string}}
+
+Reads the data from {\it stream} or {\it string}.
+
+\membersection{wxVariantData::Write}\label{wxvariantdatawrite}
+
+\constfunc{bool}{Write}{\param{ostream\&}{ stream}}
+
+\constfunc{bool}{Write}{\param{wxString\&}{ string}}
+
+Writes the data to {\it stream} or {\it string}.
+
+
+

docs/latex/wx/window.tex

@@ -147,6 +147,8 @@ Clears the window by filling it with the current background colour.
 
 \constfunc{virtual void}{ClientToScreen}{\param{int* }{x}, \param{int* }{y}}
 
+\constfunc{virtual wxPoint}{ClientToScreen}{\param{const wxPoint\&}{ pt}}
+
 Converts to screen coordinates from coordinates relative to this window.
 
 \docparam{x}{A pointer to a integer value for the x coordinate. Pass the client coordinate in, and
@@ -155,6 +157,8 @@ a screen coordinate will be passed out.}
 \docparam{y}{A pointer to a integer value for the y coordinate. Pass the client coordinate in, and
 a screen coordinate will be passed out.}
 
+\docparam{pt}{The client position for the second form of the function.}
+
 \membersection{wxWindow::Close}\label{wxwindowclose}
 
 \func{virtual bool}{Close}{\param{const bool}{ force = FALSE}}
@@ -383,6 +387,8 @@ Returns a pointer to the list of the window's children.
 
 \constfunc{virtual void}{GetClientSize}{\param{int* }{width}, \param{int* }{height}}
 
+\constfunc{virtual wxSize}{GetClientSize}{\void}
+
 This gets the size of the window `client area' in pixels.  The client area is the
 area which may be drawn on by the programmer, excluding title bar, border etc.
 
@@ -527,6 +533,12 @@ name in the window constructor or via \helpref{wxWindow::SetName}{wxwindowsetnam
 
 Returns the parent of the window, or NULL if there is no parent.
 
+\membersection{wxWindow::GetRect}\label{wxwindowgetrect}
+
+\constfunc{virtual wxRect}{GetRect}{\void}
+
+Returns the size and position of the window as a \helpref{wxRect}{wxrect} object.
+
 \membersection{wxWindow::GetReturnCode}\label{wxwindowgetreturncode}
 
 \func{int}{GetReturnCode}{\void}
@@ -573,10 +585,12 @@ Returns the built-in scrollbar range.
 
 \helpref{wxWindow::SetScrollbar}{wxwindowsetscrollbar}
 
-\membersection{wxWindow::GetSize}
+\membersection{wxWindow::GetSize}\label{wxwindowgetsize}
 
 \constfunc{virtual void}{GetSize}{\param{int* }{width}, \param{int* }{height}}
 
+\constfunc{virtual wxSize}{GetSize}{\void}
+
 This gets the size of the entire window in pixels.
 
 \wxheading{Parameters}
@@ -732,6 +746,8 @@ the user can only interact with this window. If FALSE, the effect is reversed.}
 
 \func{void}{Move}{\param{int}{ x}, \param{int}{ y}}
 
+\func{void}{Move}{\param{const wxPoint\&}{ pt}}
+
 Moves the window to the given position.
 
 \wxheading{Parameters}
@@ -740,6 +756,8 @@ Moves the window to the given position.
 
 \docparam{y}{Required y position.}
 
+\docparam{pt}{\helpref{wxPoint}{wxpoint} object representing the position.}
+
 \wxheading{Remarks}
 
 Implementations of SetSize can also implicitly implement the
@@ -1395,10 +1413,12 @@ functions so should not be required by the application programmer.
 
 \docparam{child}{Child window to remove.}
 
-\membersection{wxWindow::ScreenToClient}
+\membersection{wxWindow::ScreenToClient}\label{wxwindowscreentoclient}
 
 \constfunc{virtual void}{ScreenToClient}{\param{int* }{x}, \param{int* }{y}}
 
+\constfunc{virtual wxPoint}{ScreenToClient}{\param{const wxPoint\& }{pt}}
+
 Converts from screen to client window coordinates.
 
 \wxheading{Parameters}
@@ -1407,6 +1427,8 @@ Converts from screen to client window coordinates.
 
 \docparam{y}{Stores the screen x coordinate and receives the client x coordinate.}
 
+\docparam{pt}{The screen position for the second form of the function.}
+
 \membersection{wxWindow::ScrollWindow}\label{wxwindowscrollwindow}
 
 \func{virtual void}{ScrollWindow}{\param{int }{dx}, \param{int }{dy}, \param{const wxRect*}{ rect = NULL}}
@@ -1742,10 +1764,14 @@ and usually the scrollbar will be automatically hidden.
 \func{virtual void}{SetSize}{\param{int}{ x}, \param{int}{ y}, \param{int}{ width}, \param{int}{ height},
  \param{int}{ sizeFlags = wxSIZE\_AUTO}}
 
+\func{virtual void}{SetSize}{\param{const wxRect\&}{ rect}}
+
 Sets the size and position of the window in pixels.
 
 \func{virtual void}{SetSize}{\param{int}{ width}, \param{int}{ height}}
 
+\func{virtual void}{SetSize}{\param{const wxSize\&}{ size}}
+
 Sets the size of the window in pixels.
 
 \wxheading{Parameters}
@@ -1762,6 +1788,10 @@ value should be used.}
 \docparam{height}{Required height position in pixels, or -1 to indicate that the existing
 value should be used.}
 
+\docparam{size}{\helpref{wxSize}{wxsize} object for setting the size.}
+
+\docparam{rect}{\helpref{wxRect}{wxrect} object for setting the position and size.}
+
 \docparam{sizeFlags}{Indicates the interpretation of other parameters. It is a bit list of the following:
 
 {\bf wxSIZE\_AUTO\_WIDTH}: a -1 width value is taken to indicate
@@ -1822,6 +1852,8 @@ The resizing increments are only significant under Motif or Xt.
 
 \func{virtual void}{SetClientSize}{\param{int}{ width}, \param{int}{ height}}
 
+\func{virtual void}{SetClientSize}{\param{const wxSize\&}{ size}}
+
 This sets the size of the window client area in pixels. Using this function to size a window
 tends to be more device-independent than \helpref{wxWindow::SetSize}{wxwindowsetsize}, since the application need not
 worry about what dimensions the border or title bar have when trying to fit the window
@@ -1833,6 +1865,8 @@ around panel items, for example.
 
 \docparam{height}{The required client area height.}
 
+\docparam{size}{The required client size.}
+
 \membersection{wxWindow::SetPalette}
 
 \func{virtual void}{SetPalette}{\param{wxPalette* }{palette}}