mars3142/wx_wherigo
1
0
Fork 0
Code Issues Pull Requests Wiki Activity

initial commit

Browse Source 
Signed-off-by: Peter Siegmund <mars3142@noreply.mars3142.dev>
This commit is contained in:
Peter Siegmund
2025-10-31 23:37:30 +01:00
commit bf6b52fd94
9654 changed files with 4035664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

704
libs/wxWidgets-3.3.1/interface/wx/variant.h Normal file
View File

@@ -0,0 +1,704 @@
/////////////////////////////////////////////////////////////////////////////
// Name: variant.h
// Purpose: interface of wxVariant
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxVariant
The 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.
@note As of wxWidgets 2.9.1, wxAny has become the preferred variant class.
While most controls still use wxVariant in their interface, you
can start using wxAny in your code because of an implicit conversion
layer. See below for more information.
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 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.
Under Microsoft Windows, three additional wxVariantData-derived classes --
wxVariantDataCurrency, wxVariantDataErrorCode and wxVariantDataSafeArray --
are available for interoperation with OLE VARIANT when using wxAutomationObject.
Pointers to any 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 GetType()) 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.
Note that as of wxWidgets 2.7.1, wxVariant is
@ref overview_refcount "reference counted".
Convenience macros wxDECLARE_VARIANT_OBJECT() and wxIMPLEMENT_VARIANT_OBJECT()
allow easily adding support for conversion to and from wxVariant to custom
classes. The first of these macros must be used inside the class declaration
and the second one outside of it in the implementation file, e.g.
@code
// in the header file
class MyClass : public wxObject {
...
wxDECLARE_VARIANT_OBJECT(MyClass);
};
// in the implementation file
wxIMPLEMENT_VARIANT_OBJECT(MyClass);
// and then objects of MyClass can be used with wxVariant like this:
wxVariant variant;
MyClass value;
variant << value;
// or
value << variant;
@endcode
For this to work, MyClass must derive from wxObject, implement the
@ref overview_rtti "wxWidgets RTTI system" 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
wxObject itself. By default, wxWidgets already implements the shift
operator conversion for a few of its drawing related classes:
- wxColour
- wxImage
- wxIcon
- wxBitmap
- wxBitmapBundle
@note There also are legacy versions of the above macros without `wx`
prefix, working in a slightly different way. Please use the new
versions in the new code and consider replacing any existing use of
the legacy macros with the new ones.
Note that as of wxWidgets 2.9.0, wxVariantData no longer inherits from
wxObject and wxVariant no longer uses the type-unsafe wxList class for list
operations but the type-safe wxVariantList class. Also, wxVariantData now
supports the wxVariantData::Clone() function for implementing the Unshare()
function. wxVariantData::Clone() is implemented automatically by
IMPLEMENT_VARIANT_OBJECT().
Since wxVariantData no longer derives from wxObject, any code that tests
the type of the data using wxDynamicCast() will require adjustment. You can
use the macro wxDynamicCastVariantData() with the same arguments as
wxDynamicCast(), to use C++ RTTI type information instead of wxWidgets
RTTI.
@section variant_wxanyconversion wxVariant to wxAny Conversion Layer
wxAny is a more modern, template-based variant class. It is not
directly compatible with wxVariant, but there is a transparent conversion
layer.
Following is an example how to use these conversions with wxPropertyGrid's
property class wxPGProperty (which currently uses wxVariants both
internally and in the public API):
@code
// Get property value as wxAny instead of wxVariant
wxAny value = property->GetValue();
// Do something with it
DoSomethingWithString(value.As<wxString>());
// Write back new value to property
value = "New Value";
property->SetValue(value);
@endcode
Some caveats:
@li In wxAny, there are no separate types for handling integers of
different sizes, so converting wxAny with 'long long' value
will yield wxVariant of "long" type when the value is small
enough to fit in without overflow. Otherwise, variant type
"longlong" is used. Also note that wxAny holding unsigned integer
will always be converted to "ulonglong" wxVariant type.
@li Unlike wxVariant, wxAny does not store a (rarely needed) name string.
@li Because of implicit conversion of wxVariant to wxAny, wxAny cannot
usually contain value of type wxVariant. In other words,
any.CheckType<wxVariant>() can never return @true.
Supplied conversion functions will automatically work with all
built-in wxVariant types, and also with all user-specified types generated
using IMPLEMENT_VARIANT_OBJECT(). For hand-built wxVariantData classes,
you will need to use supplied macros in a following manner:
@code
// Declare wxVariantData for data type Foo
class wxVariantDataFoo: public wxVariantData
{
public:
// interface
// ...
DECLARE_WXANY_CONVERSION()
protected:
// data storage etc
// ...
};
IMPLEMENT_TRIVIAL_WXANY_CONVERSION(Foo, wxVariantDataFoo)
@endcode
@library{wxbase}
@category{data}
@see wxVariantData, wxAny
*/
class wxVariant : public wxObject
{
public:
/**
Default constructor.
*/
wxVariant();
/**
Constructs a variant directly with a wxVariantData object. wxVariant
will take ownership of the wxVariantData and will not increase its
reference count.
*/
wxVariant(wxVariantData* data, const wxString& name = wxEmptyString);
/**
Constructs a variant from another variant by increasing the reference
count.
*/
wxVariant(const wxVariant& variant);
/**
Constructs a variant by converting it from wxAny.
*/
wxVariant(const wxAny& any);
/**
Constructs a variant from a wide string literal.
*/
wxVariant(const wxChar* value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a string.
*/
wxVariant(const wxString& value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a wide char.
*/
wxVariant(wxChar value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a long.
*/
wxVariant(long value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a bool.
*/
wxVariant(bool value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a double.
*/
wxVariant(double value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a wxLongLong.
*/
wxVariant(wxLongLong value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a wxULongLong.
*/
wxVariant(wxULongLong value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a list of variants
*/
wxVariant(const wxVariantList& value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a void pointer.
*/
wxVariant(void* value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a pointer to a wxObject
derived class.
*/
wxVariant(wxObject* value, const wxString& name = wxEmptyString);
/**
Constructs a variant from a wxDateTime.
*/
wxVariant(const wxDateTime& val, const wxString& name = wxEmptyString);
/**
Constructs a variant from a wxArrayString.
*/
wxVariant(const wxArrayString& val, const wxString& name = wxEmptyString);
/**
Destructor.
@note wxVariantData's destructor is protected, so wxVariantData cannot
usually be deleted. Instead, wxVariantData::DecRef() should be
called. See @ref overview_refcount_destruct
"reference-counted object destruction" for more info.
*/
virtual ~wxVariant();
/**
@name List Functionality
*/
///@{
/**
Returns the value at @a idx (zero-based).
*/
wxVariant operator [](size_t idx) const;
/**
Returns a reference to the value at @a idx (zero-based). This can be
used to change the value at this index.
*/
wxVariant& operator [](size_t idx);
/**
Appends a value to the list.
*/
void Append(const wxVariant& value);
/**
Makes the variant null by deleting the internal data and set the name
to wxEmptyString.
*/
void Clear();
/**
Deletes the contents of the list.
*/
void ClearList();
/**
Deletes the zero-based @a item from the list.
*/
bool Delete(size_t item);
/**
Returns the number of elements in the list.
*/
size_t GetCount() const;
/**
Returns a reference to the wxVariantList class used by wxVariant if
this wxVariant is currently a list of variants.
*/
wxVariantList& GetList() const;
/**
Inserts a value at the front of the list.
*/
void Insert(const wxVariant& value);
/**
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.
*/
void NullList();
///@}
///@{
/**
Retrieves and converts the value of this variant to the type that
@a value is.
*/
bool Convert(long* value) const;
bool Convert(bool* value) const;
bool Convert(double* value) const;
bool Convert(wxString* value) const;
bool Convert(wxChar* value) const;
bool Convert(wxLongLong* value) const;
bool Convert(wxULongLong* value) const;
bool Convert(wxDateTime* value) const;
///@}
/**
Converts wxVariant into wxAny.
*/
wxAny GetAny() const;
/**
Returns the string array value.
*/
wxArrayString GetArrayString() const;
/**
Returns the boolean value.
*/
bool GetBool() const;
/**
Returns the character value.
*/
wxUniChar GetChar() const;
/**
Returns a pointer to the internal variant data. To take ownership of
this data, you must call its wxVariantData::IncRef() method. When you
stop using it, wxVariantData::DecRef() must be called as well.
*/
wxVariantData* GetData() const;
/**
Returns the date value.
*/
wxDateTime GetDateTime() const;
/**
Returns the floating point value.
*/
double GetDouble() const;
/**
Returns the integer value.
*/
long GetLong() const;
/**
Returns the signed 64-bit integer value.
*/
wxLongLong GetLongLong() const;
/**
Returns a constant reference to the variant name.
*/
const wxString& GetName() const;
/**
Gets the string value.
*/
wxString GetString() const;
/**
Returns the value type as a string.
The built-in types are:
- "bool"
- "char"
- "datetime"
- "double"
- "list"
- "long"
- "longlong"
- "string"
- "ulonglong"
- "arrstring"
- "void*"
If the variant is null, the value type returned is the string "null"
(not the empty string).
*/
wxString GetType() const;
/**
Returns the unsigned 64-bit integer value.
*/
wxULongLong GetULongLong() const;
/**
Gets the void pointer value.
Notice that this method can be used for null objects (i.e. those for
which IsNull() returns @true) and will return @NULL for them.
*/
void* GetVoidPtr() const;
/**
Gets the wxObject pointer value.
*/
wxObject* GetWxObjectPtr() const;
/**
Returns @true if there is no data associated with this variant, @false
if there is data.
*/
bool IsNull() const;
/**
Returns @true if @a type matches the type of the variant, @false
otherwise.
*/
bool IsType(const wxString& type) const;
/**
Returns @true if the data is derived from the class described by
@a type, @false otherwise.
*/
bool IsValueKindOf(const wxClassInfo* type) const;
/**
Makes the variant null by deleting the internal data.
*/
void MakeNull();
/**
Makes a string representation of the variant value (for any type).
*/
wxString MakeString() const;
/**
Returns @true if @a value matches an element in the list.
*/
bool Member(const wxVariant& value) const;
/**
Sets the internal variant data, deleting the existing data if there is
any.
*/
void SetData(wxVariantData* data);
/**
Makes sure that any data associated with this variant is not shared
with other variants. For this to work, wxVariantData::Clone() must be
implemented for the data types you are working with.
wxVariantData::Clone() is implemented for all the default data types.
*/
bool Unshare();
///@{
/**
Inequality test operator.
*/
bool operator !=(const wxVariant& value) const;
bool operator !=(const wxString& value) const;
bool operator !=(const wxChar* value) const;
bool operator !=(wxChar value) const;
bool operator !=(long value) const;
bool operator !=(bool value) const;
bool operator !=(double value) const;
bool operator !=(wxLongLong value) const;
bool operator !=(wxULongLong value) const;
bool operator !=(void* value) const;
bool operator !=(wxObject* value) const;
bool operator !=(const wxVariantList& value) const;
bool operator !=(const wxArrayString& value) const;
bool operator !=(const wxDateTime& value) const;
///@}
///@{
/**
Assignment operator, using @ref overview_refcount "reference counting"
if possible.
*/
void operator =(const wxVariant& value);
void operator =(wxVariantData* value);
void operator =(const wxString& value);
void operator =(const wxChar* value);
void operator =(wxChar value);
void operator =(long value);
void operator =(bool value);
void operator =(double value);
bool operator =(wxLongLong value) const;
bool operator =(wxULongLong value) const;
void operator =(void* value);
void operator =(wxObject* value);
void operator =(const wxVariantList& value);
void operator =(const wxDateTime& value);
void operator =(const wxArrayString& value);
///@}
///@{
/**
Equality test operator.
*/
bool operator ==(const wxVariant& value) const;
bool operator ==(const wxString& value) const;
bool operator ==(const wxChar* value) const;
bool operator ==(wxChar value) const;
bool operator ==(long value) const;
bool operator ==(bool value) const;
bool operator ==(double value) const;
bool operator ==(wxLongLong value) const;
bool operator ==(wxULongLong value) const;
bool operator ==(void* value) const;
bool operator ==(wxObject* value) const;
bool operator ==(const wxVariantList& value) const;
bool operator ==(const wxArrayString& value) const;
bool operator ==(const wxDateTime& value) const;
///@}
///@{
/**
Operators for implicit conversion, using appropriate getter member
function.
*/
double operator double() const;
long operator long() const;
wxLongLong operator wxLongLong() const;
wxULongLong operator wxULongLong() const;
///@}
/**
Operator for implicit conversion to a pointer to a void, using
GetVoidPtr().
*/
void* operator void*() const;
/**
Operator for implicit conversion to a wxChar, using GetChar().
*/
char operator wxChar() const;
/**
Operator for implicit conversion to a pointer to a wxDateTime, using
GetDateTime().
*/
void* operator wxDateTime() const;
/**
Operator for implicit conversion to a string, using MakeString().
*/
wxString operator wxString() const;
};
/**
@class wxVariantData
The wxVariantData class is used to implement a new type for wxVariant.
Derive from wxVariantData, and override the pure virtual functions.
wxVariantData is @ref overview_refcount "reference counted", 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 a reference count
of 1, and passing it to wxVariant will not increase this. In other words,
IncRef() 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, DecRef() will delete the object automatically when the reference
count reaches zero.
@library{wxbase}
@category{data}
@see wxVariant, wxGetVariantCast()
*/
class wxVariantData : public wxObjectRefData
{
public:
/**
Default constructor.
*/
wxVariantData();
/**
This function can be overridden to clone the data. You must implement
this function in order for wxVariant::Unshare() to work for your data.
This function is implemented for all built-in data types.
*/
virtual wxVariantData* Clone() const;
/**
Decreases reference count. If the count reaches zero, the object is
automatically deleted.
@note The destructor of wxVariantData is protected, so delete cannot be
used as normal. Instead, DecRef() should be called.
*/
void DecRef();
/**
Returns @true if this object is equal to @a data.
*/
virtual bool Eq(wxVariantData& data) const = 0;
/**
Converts value to wxAny, if possible. Return @true if successful.
*/
virtual bool GetAny(wxAny* any) const;
/**
Returns the string type of the data.
*/
virtual wxString GetType() const = 0;
/**
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.
*/
virtual wxClassInfo* GetValueClassInfo();
/**
Increases reference count. Note that initially wxVariantData has
reference count of 1.
*/
void IncRef();
/**
Reads the data from @a stream.
*/
virtual bool Read(istream& stream);
/**
Reads the data from @a string.
*/
virtual bool Read(wxString& string);
/**
Writes the data to @a stream.
*/
virtual bool Write(ostream& stream) const;
/**
Writes the data to @a string.
*/
virtual bool Write(wxString& string) const;
};
// ============================================================================
// Global functions/macros
// ============================================================================
/** @addtogroup group_funcmacro_rtti */
///@{
/**
This macro returns a pointer to the data stored in @a var (wxVariant) cast
to the type @a classname if the data is of this type (the check is done
during the run-time) or @NULL otherwise.
@header{wx/variant.h}
@see @ref overview_rtti, wxDynamicCast()
*/
#define wxGetVariantCast(var, classname)
///@}