X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/954b8ae60391d18b87a604e7919c87c0c6ae208b..daf5b37afdda9e8ab7f909e01ffd6387219a80ea:/docs/latex/wx/variant.tex diff --git a/docs/latex/wx/variant.tex b/docs/latex/wx/variant.tex index f91ca59e14..d165cd6281 100644 --- a/docs/latex/wx/variant.tex +++ b/docs/latex/wx/variant.tex @@ -1,25 +1,76 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: variant.tex +%% Purpose: wxVariant docs +%% Author: wxWidgets Team +%% Modified by: +%% Created: 01/30/2005 +%% RCS-ID: $Id$ +%% Copyright: (c) wxWidgets Team +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \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. +As standard, wxVariant can store values of type bool, wxChar, 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 +\helpref{GetLong}{wxvariantgetlong} can be used. + +Pointers to any \helpref{wxObject}{wxobject} derived class can also easily be stored +in a wxVariant. wxVariant will then use wxWidgets' built-in RTTI system to set the +type name (returned by \helpref{GetType}{wxvariantgettype}) and to perform +type-safety checks at runtime. 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. +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. + +Note that as of wxWidgets 2.7.1, wxVariant is \helpref{reference counted}{trefcount}. +Additionally, the convenience macros {\bf DECLARE\_VARIANT\_OBJECT} and +{\bf IMPLEMENT\_VARIANT\_OBJECT} were added so that adding (limited) support +for conversion to and from wxVariant can be very easily implemented without modifying +either wxVariant or the class to be stored by wxVariant. Since assignment operators +cannot be declared outside the class, the shift left operators are used like this: + +\begin{verbatim} + // in the header file + DECLARE_VARIANT_OBJECT(MyClass) + + // in the implementation file + IMPLMENT_VARIANT_OBJECT(MyClass) + + // in the user code + wxVariant variant; + MyClass value; + variant << value; + + // or + value << variant; +\end{verbatim} + +For this to work, MyClass must derive from \helpref{wxObject}{wxobject}, implement +the \helpref{wxWidgets RTTI system}{runtimeclassoverview} +and support the assignment operator and equality operator for itself. Ideally, it +should also be reference counted to make copying operations cheap and fast. This +can be most easily implemented using the reference counting support offered by +\helpref{wxObject}{wxobject} itself. By default, wxWidgets already implements +the shift operator conversion for a few of its drawing related classes: + +\begin{verbatim} +IMPLEMENT_VARIANT_OBJECT(wxColour) +IMPLEMENT_VARIANT_OBJECT(wxImage) +IMPLEMENT_VARIANT_OBJECT(wxIcon) +IMPLEMENT_VARIANT_OBJECT(wxBitmap) +\end{verbatim} \wxheading{Derived from} @@ -29,6 +80,10 @@ wxPropertyValue may be replaced by wxVariant eventually. +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxVariantData}{wxvariantdata} @@ -43,14 +98,15 @@ Default constructor. \func{}{wxVariant}{\param{const wxVariant\& }{variant}} -Copy constructor. +Copy constructor, uses \helpref{reference counting}{trefcount}. + +\func{}{wxVariant}{\param{const wxChar*}{ value}, \param{const wxString\& }{name = ``"}} -\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 = ``"}} +\func{}{wxVariant}{\param{wxChar}{ value}, \param{const wxString\& }{name = ``"}} Construction from a character value. @@ -73,29 +129,37 @@ 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 = ``"}} +\func{}{wxVariant}{\param{void*}{ 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. +Construction from a void pointer. -%Note: this constructor is currently disabled because it causes a C++ ambiguity. +\func{}{wxVariant}{\param{wxObject*}{ value}, \param{const wxString\& }{name = ``"}} -\func{}{wxVariant}{\param{const wxTime\&}{ value}, \param{const wxString\& }{name = ``"}} +Construction from a wxObject pointer. -Construction from a time. +\func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}} -\func{}{wxVariant}{\param{const wxDate\&}{ value}, \param{const wxString\& }{name = ``"}} +Construction from user-defined data. The variant holds onto the {\it data} pointer. -Construction from a date. +\func{}{wxVariant}{\param{wxDateTime\&}{ val}, \param{const wxString\& }{name = ``"}} -\func{}{wxVariant}{\param{void*}{ value}, \param{const wxString\& }{name = ``"}} +Construction from a \helpref{wxDateTime}{wxdatetime}. -Construction from a void pointer. +\func{}{wxVariant}{\param{wxArrayString\&}{ val}, \param{const wxString\& }{name = ``"}} -\func{}{wxVariant}{\param{wxVariantData*}{ data}, \param{const wxString\& }{name = ``"}} +Construction from an array of strings. This constructor copies {\it value} and its contents. + +\func{}{wxVariant}{\param{DATE\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} + +Construction from a odbc date value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. -Construction from user-defined data. The variant holds on to the {\it data} pointer. +\func{}{wxVariant}{\param{TIME\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} + +Construction from a odbc time value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. + +\func{}{wxVariant}{\param{TIMESTAMP\_STRUCT*}{ val}, \param{const wxString\& }{name = ``"}} + +Construction from a odbc timestamp value. Represented internally by a \helpref{wxDateTime}{wxdatetime} value. \membersection{wxVariant::\destruct{wxVariant}}\label{wxvariantdtor} @@ -103,30 +167,66 @@ Construction from user-defined data. The variant holds on to the {\it data} poin Destructor. +Note that destructor is protected, so wxVariantData cannot usually +be deleted. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called. +See \helpref{reference-counted object destruction}{refcountdestruct} for more info. + + \membersection{wxVariant::Append}\label{wxvariantappend} \func{void}{Append}{\param{const wxVariant\&}{ value}} Appends a value to the list. +\membersection{wxVariant::Clear}\label{wxvariantclear} + +\func{void}{Clear}{\void} + +Makes the variant null by deleting the internal data and +set the name to {\it wxEmptyString}. + \membersection{wxVariant::ClearList}\label{wxvariantclearlist} \func{void}{ClearList}{\void} Deletes the contents of the list. + +\membersection{wxVariant::Convert}\label{wxvariantconvert} + +\constfunc{bool}{Convert}{\param{long*}{ value}} + +\constfunc{bool}{Convert}{\param{bool*}{ value}} + +\constfunc{bool}{Convert}{\param{double*}{ value}} + +\constfunc{bool}{Convert}{\param{wxString*}{ value}} + +\constfunc{bool}{Convert}{\param{wxChar*}{ value}} + +\constfunc{bool}{Convert}{\param{wxDateTime*}{ value}} + +Retrieves and converts the value of this variant to the type that {\it value} is. + + \membersection{wxVariant::GetCount}\label{wxvariantgetcount} -\constfunc{int}{GetCount}{\void} +\constfunc{size\_t}{GetCount}{\void} Returns the number of elements in the list. \membersection{wxVariant::Delete}\label{wxvariantdelete} -\func{bool}{Delete}{\param{int }{item}} +\func{bool}{Delete}{\param{size\_t }{item}} Deletes the zero-based {\it item} from the list. +\membersection{wxVariant::GetArrayString}\label{wxvariantgetarraystring} + +\constfunc{wxArrayString}{GetArrayString}{\void} + +Returns the string array value. + \membersection{wxVariant::GetBool}\label{wxvariantgetbool} \constfunc{bool}{GetBool}{\void} @@ -135,7 +235,7 @@ Returns the boolean value. \membersection{wxVariant::GetChar}\label{wxvariantgetchar} -\constfunc{char}{GetChar}{\void} +\constfunc{wxChar}{GetChar}{\void} Returns the character value. @@ -143,13 +243,16 @@ Returns the character value. \constfunc{wxVariantData*}{GetData}{\void} -Returns a pointer to the internal variant data. +Returns a pointer to the internal variant data. To take ownership +of this data, you must call its \helpref{IncRef}{wxvariantdataincref} +method. When you stop using it, \helpref{DecRef}{wxvariantdatadecref} +must be likewise called. -\membersection{wxVariant::GetDate}\label{wxvariantgetdate} +\membersection{wxVariant::GetDateTime}\label{wxvariantgetdatetime} -\constfunc{wxDate}{GetDate}{\void} +\constfunc{wxDateTime}{GetDateTime}{\void} -Gets the date value. +Returns the date value. \membersection{wxVariant::GetDouble}\label{wxvariantgetdouble} @@ -175,12 +278,6 @@ Returns a constant reference to the variant name. 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} @@ -195,6 +292,12 @@ If the variant is null, the value type returned is the string ``null" (not the e Gets the void pointer value. +\membersection{wxVariant::GetWxObjectPtr}\label{wxvariantgetwxobjectptr} + +\constfunc{wxObject*}{GetWxObjectPtr}{\void} + +Gets the wxObject pointer value. + \membersection{wxVariant::Insert}\label{wxvariantinsert} \func{void}{Insert}{\param{const wxVariant\&}{ value}} @@ -205,13 +308,19 @@ Inserts a value at the front of the list. \constfunc{bool}{IsNull}{\void} -Returns TRUE if there is no data associated with this variant, FALSE if there is data. +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. +Returns true if {\it type} matches the type of the variant, false otherwise. + +\membersection{wxVariant::IsValueKindOf}\label{wxvariantisvaluekindof} + +\constfunc{bool}{IsValueKindOf}{\param{const wxClassInfo* type}{ type}} + +Returns true if the data is derived from the class described by {\it type}, false otherwise. \membersection{wxVariant::MakeNull}\label{wxvariantmakenull} @@ -229,7 +338,7 @@ Makes a string representation of the variant value (for any type). \constfunc{bool}{Member}{\param{const wxVariant\&}{ value}} -Returns TRUE if {\it value} matches an element in the list. +Returns true if {\it value} matches an element in the list. \membersection{wxVariant::NullList}\label{wxvariantnulllist} @@ -252,9 +361,9 @@ Sets the internal variant data, deleting the existing data if there is any. \func{void}{operator $=$}{\param{const wxString\& }{value}} -\func{void}{operator $=$}{\param{const char* }{value}} +\func{void}{operator $=$}{\param{const wxChar* }{value}} -\func{void}{operator $=$}{\param{char }{value}} +\func{void}{operator $=$}{\param{wxChar }{value}} \func{void}{operator $=$}{\param{const long }{value}} @@ -262,71 +371,77 @@ Sets the internal variant data, deleting the existing data if there is any. \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{wxObject* }{value}} + \func{void}{operator $=$}{\param{const wxList\& }{value}} -\func{void}{operator $=$}{\param{const wxStringList\& }{value}} +\func{void}{operator $=$}{\param{const wxDateTime\& }{value}} + +\func{void}{operator $=$}{\param{const wxArrayString\& }{value}} + +\func{void}{operator $=$}{\param{const DATE\_STRUCT* }{value}} + +\func{void}{operator $=$}{\param{const TIME\_STRUCT* }{value}} + +\func{void}{operator $=$}{\param{const TIMESTAMP\_STRUCT* }{value}} -Assignment operators. +Assignment operators, using \helpref{reference counting}{trefcount} when possible. \membersection{wxVariant::operator $==$}\label{wxvarianteq} -\func{bool}{operator $==$}{\param{const wxVariant\& }{value}} +\constfunc{bool}{operator $==$}{\param{const wxVariant\& }{value}} -\func{bool}{operator $==$}{\param{const wxString\& }{value}} +\constfunc{bool}{operator $==$}{\param{const wxString\& }{value}} -\func{bool}{operator $==$}{\param{const char* }{value}} +\constfunc{bool}{operator $==$}{\param{const wxChar* }{value}} -\func{bool}{operator $==$}{\param{char }{value}} +\constfunc{bool}{operator $==$}{\param{wxChar }{value}} -\func{bool}{operator $==$}{\param{const long }{value}} +\constfunc{bool}{operator $==$}{\param{const long }{value}} -\func{bool}{operator $==$}{\param{const bool }{value}} +\constfunc{bool}{operator $==$}{\param{const bool }{value}} -\func{bool}{operator $==$}{\param{const double }{value}} +\constfunc{bool}{operator $==$}{\param{const double }{value}} -\func{bool}{operator $==$}{\param{const wxDate\& }{value}} +\constfunc{bool}{operator $==$}{\param{void* }{value}} -\func{bool}{operator $==$}{\param{const wxTime\& }{value}} +\constfunc{bool}{operator $==$}{\param{wxObject* }{value}} -\func{bool}{operator $==$}{\param{void* }{value}} +\constfunc{bool}{operator $==$}{\param{const wxList\& }{value}} -\func{bool}{operator $==$}{\param{const wxList\& }{value}} +\constfunc{bool}{operator $==$}{\param{const wxArrayString\& }{value}} -\func{bool}{operator $==$}{\param{const wxStringList\& }{value}} +\constfunc{bool}{operator $==$}{\param{const wxDateTime\& }{value}} Equality test operators. \membersection{wxVariant::operator $!=$}\label{wxvariantneq} -\func{bool}{operator $!=$}{\param{const wxVariant\& }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxVariant\& }{value}} -\func{bool}{operator $!=$}{\param{const wxString\& }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxString\& }{value}} -\func{bool}{operator $!=$}{\param{const char* }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxChar* }{value}} -\func{bool}{operator $!=$}{\param{char }{value}} +\constfunc{bool}{operator $!=$}{\param{wxChar }{value}} -\func{bool}{operator $!=$}{\param{const long }{value}} +\constfunc{bool}{operator $!=$}{\param{const long }{value}} -\func{bool}{operator $!=$}{\param{const bool }{value}} +\constfunc{bool}{operator $!=$}{\param{const bool }{value}} -\func{bool}{operator $!=$}{\param{const double }{value}} +\constfunc{bool}{operator $!=$}{\param{const double }{value}} -\func{bool}{operator $!=$}{\param{const wxDate\& }{value}} +\constfunc{bool}{operator $!=$}{\param{void* }{value}} -\func{bool}{operator $!=$}{\param{const wxTime\& }{value}} +\constfunc{bool}{operator $!=$}{\param{wxObject* }{value}} -\func{bool}{operator $!=$}{\param{void* }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxList\& }{value}} -\func{bool}{operator $!=$}{\param{const wxList\& }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxArrayString\& }{value}} -\func{bool}{operator $!=$}{\param{const wxStringList\& }{value}} +\constfunc{bool}{operator $!=$}{\param{const wxDateTime\& }{value}} Inequality test operators. @@ -341,11 +456,11 @@ Returns the value at {\it idx} (zero-based). 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} +\membersection{wxVariant::operator wxChar}\label{wxvariantchar} -\constfunc{char}{operator char}{\void} +\constfunc{char}{operator wxChar}{\void} -Operator for implicit conversion to a char, using \helpref{wxVariant::GetChar}{wxvariantgetchar}. +Operator for implicit conversion to a wxChar, using \helpref{wxVariant::GetChar}{wxvariantgetchar}. \membersection{wxVariant::operator double}\label{wxvariantdouble} @@ -357,34 +472,42 @@ Operator for implicit conversion to a double, using \helpref{wxVariant::GetDoubl 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}. +\membersection{wxVariant::operator wxDateTime}\label{wxvariantdatetime} + +\constfunc{void*}{operator wxDateTime}{\void} + +Operator for implicit conversion to a pointer to a \helpref{wxDateTime}{wxdatetime}, using \helpref{wxVariant::GetDateTime}{wxvariantgetdatetime}. + + + +%% wxVariantData + + \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. +The {\bf wxVariantData} class is used to implement a new type for \helpref{wxVariant}{wxvariant}. +Derive from wxVariantData, and override the pure virtual functions. + +wxVariantData is \helpref{reference counted}{refcount}, but you don't normally have to care about this, +as wxVariant manages the count automatically. However, in case your application needs to take +ownership of wxVariantData, be aware that the object is created with reference count of 1, +and passing it to wxVariant will not increase this. In other words, \helpref{IncRef}{wxvariantdataincref} +needs to be called only if you both take ownership of wxVariantData and pass it to a wxVariant. +Also note that the destructor is protected, so you can never explicitly delete a wxVariantData +instance. Instead, \helpref{DecRef}{wxvariantdatadecref} will delete the object automatically +when the reference count reaches zero. \wxheading{Derived from} @@ -394,6 +517,10 @@ and override the pure virtual functions. +\wxheading{Library} + +\helpref{wxBase}{librarieslist} + \wxheading{See also} \helpref{wxVariant}{wxvariant} @@ -406,17 +533,23 @@ and override the pure virtual functions. Default constructor. -\membersection{wxVariantData::Copy}\label{wxvariantdatacopy} +\membersection{wxVariantData::DecRef}\label{wxvariantdatadecref} + +\func{void}{DecRef}{\void} + +Decreases reference count. If the count reaches zero, the object is +automatically deleted. + +Note that destructor of wxVariantData is protected, so delete +cannot be used as normal. Instead, \helpref{DecRef}{wxvariantdatadecref} should be called. -\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}. +Returns true if this object is equal to {\it data}. \membersection{wxVariantData::GetType}\label{wxvariantdatagettype} @@ -424,6 +557,19 @@ Returns TRUE if this object is equal to {\it data}. Returns the string type of the data. +\membersection{wxVariantData::GetValueClassInfo}\label{wxvariantdatagetvalueclassinfo} + +\constfunc{wxClassInfo*}{GetValueClassInfo}{\void} + +If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if +the data isn't a wxObject the method returns NULL. + +\membersection{wxVariantData::IncRef}\label{wxvariantdataincref} + +\func{void}{IncRef}{\void} + +Increases reference count. Note that initially wxVariantData has reference count of 1. + \membersection{wxVariantData::Read}\label{wxvariantdataread} \func{bool}{Read}{\param{ostream\&}{ stream}} @@ -441,4 +587,17 @@ Reads the data from {\it stream} or {\it string}. Writes the data to {\it stream} or {\it string}. +\membersection{wxGetVariantCast}\label{wxgetvariantcast} + +\func{classname *}{wxGetVariantCast}{wxVariant\&, classname} + +This macro returns the data stored in {\it variant} cast to the type {\it classname *} if +the data is of this type (the check is done during the run-time) or +{\tt NULL} otherwise. + + +\wxheading{See also} + +\helpref{RTTI overview}{runtimeclassoverview}\\ +\helpref{wxDynamicCast}{wxdynamiccast}