Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'fix-doc-oleauto-helpers' of https://github.com/PBfordev/wxWidgets

Browse Source 
Improve OLE Automation classes documentation.

See https://github.com/wxWidgets/wxWidgets/pull/1615
This commit is contained in:
Vadim Zeitlin
2019-10-23 01:54:59 +02:00
parent dddbc1bafc aa3e812d42
commit ab33227578
3 changed files with 558 additions and 553 deletions
Download Patch File Download Diff File Expand all files Collapse all files

553
interface/wx/msw/ole/automtn.h
View File

@@ -41,558 +41,6 @@ enum wxAutomationInstanceFlags
wxAutomationInstance_SilentIfNone = 2
};
/**
Flags used for conversions between wxVariant and OLE @c VARIANT.
These flags are used by wxAutomationObject for its wxConvertOleToVariant()
calls. They can be obtained by wxAutomationObject::GetConvertVariantFlags()
and set by wxAutomationObject::SetConvertVariantFlags().
@since 3.0
@header{wx/msw/ole/oleutils.h}
*/
enum wxOleConvertVariantFlags
{
/**
Default value.
*/
wxOleConvertVariant_Default = 0,
/**
If this flag is used, SAFEARRAYs contained in OLE @c VARIANTs will be
returned as wxVariants with wxVariantDataSafeArray type instead of
wxVariants with the list type containing the (flattened) SAFEARRAY's
elements.
*/
wxOleConvertVariant_ReturnSafeArrays = 1
};
/**
@class wxVariantDataCurrency
This class represents a thin wrapper for Microsoft Windows @c CURRENCY type.
It is used for converting between wxVariant and OLE @c VARIANT
with type set to @c VT_CURRENCY. When wxVariant stores
wxVariantDataCurrency, it returns "currency" as its type.
An example of setting and getting @c CURRENCY value to and from wxVariant:
@code
CURRENCY cy;
wxVariant variant;
// set wxVariant to currency type
if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) ) // set cy to 123.45
{
variant.SetData(new wxVariantDataCurrency(cy));
// or instead of the line above you could write:
// wxVariantDataCurrency wxCy;
// wxCy.SetValue(cy);
// variant.SetData(wxCy.Clone());
}
// get CURRENCY value from wxVariant
if ( variant.GetType() == "currency" )
{
wxVariantDataCurrency*
wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
cy = wxCy->GetValue();
}
@endcode
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
@header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataCurrency : public wxVariantData
{
public:
/**
Default constructor initializes the object to 0.0.
*/
wxVariantDataCurrency();
/**
Constructor from CURRENCY.
*/
wxVariantDataCurrency(CURRENCY value);
/**
Returns the stored CURRENCY value.
*/
CURRENCY GetValue() const;
/**
Sets the stored value to @a value.
*/
void SetValue(CURRENCY value);
/**
Returns @true if @a data is of wxVariantDataCurency type
and contains the same CURRENCY value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
The implementation of this method uses @c VarBstrFromCy() Windows API
function with @c LOCALE_USER_DEFAULT.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "currency".
*/
virtual wxString GetType() const;
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};
/**
@class wxVariantDataErrorCode
This class represents a thin wrapper for Microsoft Windows @c SCODE type
(which is the same as @c HRESULT).
It is used for converting between a wxVariant and OLE @c VARIANT with type set
to @c VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
"errorcode" as its type. This class can be used for returning error codes
of automation calls or exchanging values with other applications: e.g.
Microsoft Excel returns VARIANTs with @c VT_ERROR type for cell values with
errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
there) etc. See wxVariantDataCurrency for an example of how to exchange
values between wxVariant and a native type not directly supported by it.
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency
@header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataErrorCode : public wxVariantData
{
public:
/**
Constructor initializes the object to @a value or @c S_OK if no value was
passed.
*/
wxVariantDataErrorCode(SCODE value = S_OK);
/**
Returns the stored @c SCODE value.
*/
SCODE GetValue() const;
/**
Set the stored value to @a value.
*/
void SetValue(SCODE value);
/**
Returns @true if @a data is of wxVariantDataErrorCode type
and contains the same @c SCODE value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
The error code is just a number, so it's output as such.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "errorcode".
*/
virtual wxString GetType() const { return wxS("errorcode"); }
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};
/**
@class wxVariantDataSafeArray
This class stores @c SAFEARRAY in a wxVariant. It can be used
to pass arrays having more than one dimension with wxAutomationObject methods.
When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
wxVariantDataSafeArray does NOT manage the @c SAFEARRAY it points to.
If you want to pass it to a wxAutomationObject as a parameter:
-# Create and fill a @c SAFEARRAY.
-# Assign the @c SAFEARRAY pointer to it and store it in a wxVariant.
-# Call a wxAutomationObject method (such as CallMethod() or PutProperty()) with the wxVariant as a parameter.
-# wxAutomationObject will destroy the array after the automation call.
An example of creating a two-dimensional @c SAFEARRAY containing <tt>VARIANT</tt>s
and storing it in a wxVariant, using a utility class wxSafeArray<varType>.
@code
const size_t dimensions = 2;
const long rowCount = 1000;
const long columnCount = 20;
SAFEARRAYBOUND bounds[dimensions];
wxSafeArray<VT_VARIANT> safeArray;
bounds[0].lLbound = 0; // elements start at 0
bounds[0].cElements = rowCount;
bounds[1].lLbound = 0; // elements start at 0
bounds[1].cElements = columnCount;
if ( !safeArray.Create(bounds, dimensions) )
return false;
long indices[dimensions];
for ( long row = 0; row < rowCount; ++row )
{
indices[0] = row;
for ( long column = 0; column < columnCount; ++column )
{
indices[1] = column;
if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row, column)) )
return false;
}
}
range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(safeArray.Detach())));
@endcode
If you want to receive a @c SAFEARRAY in a wxVariant as a result of an wxAutomationObject
call:
-# Call wxAutomationObject::SetConvertVariantFlags() with parameter
::wxOleConvertVariant_ReturnSafeArrays (otherwise the data would be
sent as a flattened one-dimensional list).
-# Call a wxAutomationObject method (such as CallMethod() or GetProperty()).
-# Retrieve the @c SAFEARRAY from the returned wxVariant.
-# Process the data in the @c SAFEARRAY.
-# Destroy the @c SAFEARRAY when you no longer need it.
The following example shows how to process a two-dimensional @c SAFEARRAY
with @c VT_VARIANT type received from a wxAutomationObject call,
using a utility class wxSafeArray<varType>.
@code
const size_t dimensions = 2;
wxVariant result;
range.SetConvertVariantFlags(wxOleConvertVariant_ReturnSafeArrays);
result = range.GetProperty("Value");
if ( !result.IsType("safearray") )
return false;
wxSafeArray<VT_VARIANT> safeArray;
wxVariantDataSafeArray* const
sa = wxStaticCastVariantData(result.GetData(), wxVariantDataSafeArray);
if ( !safeArray.Attach(sa->GetValue()) )
{
if ( !safeArray.HasArray() )
::SafeArrayDestroy(sa->GetValue()); // we have to dispose the SAFEARRAY ourselves
return false;
}
if ( safeArray.GetDim() != dimensions ) // we are expecting 2 dimensions
return false; // SAFEARRAY will be disposed by safeArray's dtor
long rowStart, columnStart;
long rowCount, columnCount;
long indices[dimensions];
wxVariant value;
// get start indices and item counts for rows and columns
safeArray.GetLBound(1, rowStart);
safeArray.GetLBound(2, columnStart);
safeArray.GetUBound(1, rowCount);
safeArray.GetUBound(2, columnCount);
for ( long row = rowStart; row <= rowCount; ++row )
{
indices[0] = row;
for ( long column = columnStart; column <= columnCount; ++column )
{
indices[1] = column;
if ( !safeArray.GetElement(indices, value) )
return false;
// do something with value
}
}
// SAFEARRAY will be disposed by safeArray's dtor
@endcode
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxSafeArray<varType>, wxVariant, wxVariantData
@header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataSafeArray : public wxVariantData
{
public:
/**
Constructor initializes the object to @a value.
*/
explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);
/**
Returns the stored array.
*/
SAFEARRAY* GetValue() const;
/**
Set the stored array.
*/
void SetValue(SAFEARRAY* value);
/**
Returns @true if @a data is of wxVariantDataSafeArray type
and contains the same SAFEARRAY* value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
Only the address of @c SAFEARRAY pointer is output.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "safearray".
*/
virtual wxString GetType() const;
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};
/**
@class wxSafeArray<varType>
wxSafeArray<varType> is wxWidgets wrapper for working with MS Windows @c
SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs.
It also has convenience functions for converting between @c SAFEARRAY and
wxVariant with list type or wxArrayString.
wxSafeArray is a template class which must be created with an appropriate
type matching the underlying @c VARIANT type (such as @c VT_VARIANT or @c
VT_BSTR).
See wxVariantDataSafeArray documentation for examples of using it.
@onlyfor{wxmsw}
@since 3.0
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariantDataSafeArray, wxVariant
@header{wx/msw/ole/safearray.h}
*/
template <VARTYPE varType>
class wxSafeArray<varType>
{
public:
/**
The default constructor.
*/
wxSafeArray();
/**
The destructor unlocks and destroys the owned @c SAFEARRAY.
*/
~wxSafeArray();
/**
Creates and locks a zero-based one-dimensional @c SAFEARRAY with the
given number of elements.
*/
bool Create(size_t count);
/**
Creates and locks a @c SAFEARRAY.
See @c SafeArrayCreate() in MSDN documentation for more information.
*/
bool Create(SAFEARRAYBOUND* bound, size_t dimensions);
/**
Creates a zero-based one-dimensional @c SAFEARRAY from wxVariant
with the list type.
Can be called only for wxSafeArray<@c VT_VARIANT>.
*/
bool CreateFromListVariant(const wxVariant& variant);
/**
Creates a zero-based one-dimensional @c SAFEARRAY from wxArrayString.
Can be called only for wxSafeArray<@c VT_BSTR>.
*/
bool CreateFromArrayString(const wxArrayString& strings);
/**
Attaches and locks an existing @c SAFEARRAY.
The array must have the same @c VARTYPE as this wxSafeArray was
instantiated with.
*/
bool Attach(SAFEARRAY* array);
/**
Unlocks the owned @c SAFEARRAY, returns it and gives up its ownership.
*/
SAFEARRAY* Detach();
/**
Unlocks and destroys the owned @c SAFEARRAY.
*/
void Destroy();
/**
Returns @true if it has a valid @c SAFEARRAY.
*/
bool HasArray() const { return m_array != NULL; }
/**
Returns the number of dimensions.
*/
size_t GetDim() const;
/**
Returns lower bound for dimension @a dim in @a bound.
Dimensions start at @c 1.
*/
bool GetLBound(size_t dim, long& bound) const;
/**
Returns upper bound for dimension @a dim in @a bound.
Dimensions start at @c 1.
*/
bool GetUBound(size_t dim, long& bound) const;
/**
Returns element count for dimension @a dim. Dimensions start at @c 1.
*/
size_t GetCount(size_t dim) const;
/**
Change the value of the specified element.
@a indices have the same row-column order as @c rgIndices i
@c SafeArrayPutElement(), i.e., the right-most dimension is
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@a element must be of type matching @c varType this wxSafeArray was
created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
wxSafeArray<@c VT_R8>.
*/
bool SetElement(long* indices, const externT& element);
/**
Retrieve the value of the specified element.
@a indices have the same row-column order as @c rgIndices in
@c SafeArrayGetElement(), i.e., the right-most dimension is
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@a element must be of type matching @c varType this wxSafeArray was
created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
wxSafeArray<@c VT_R8>.
*/
bool GetElement(long* indices, externT& element) const;
/**
Converts the array to a wxVariant with the list type, regardless of the
underlying @c SAFEARRAY type.
If the array is multidimensional, it is flattened using the algorithm
originally employed in wxConvertOleToVariant().
*/
bool ConvertToVariant(wxVariant& variant) const;
/**
Converts an array to wxArrayString.
Can be called only for wxSafeArray<@c VT_BSTR>. If the array is
multidimensional, it is flattened using the algorithm originally
employed in wxConvertOleToVariant().
*/
bool ConvertToArrayString(wxArrayString& strings) const;
/**
Converts @a psa to wxVariant.
@see wxSafeArray<varType>::ConvertToVariant(wxVariant&) const
*/
static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant);
/**
Converts @a psa to wxArrayString.
@see wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const
*/
static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings);
};
/**
@class wxAutomationObject
@@ -876,4 +324,3 @@ public:
*/
void SetConvertVariantFlags(long flags);
};

374
interface/wx/msw/ole/oleutils.h Normal file
View File

@@ -0,0 +1,374 @@
/////////////////////////////////////////////////////////////////////////////
// Name: msw/ole/oleutils.h
// Purpose: interface of OLE helpers
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
Flags used for conversions between wxVariant and OLE @c VARIANT.
These flags are used by wxAutomationObject for its wxConvertOleToVariant()
calls. They can be obtained by wxAutomationObject::GetConvertVariantFlags()
and set by wxAutomationObject::SetConvertVariantFlags().
@since 3.0
@see wxVariantDataSafeArray
*/
enum wxOleConvertVariantFlags
{
/**
Default value.
*/
wxOleConvertVariant_Default = 0,
/**
If this flag is used, SAFEARRAYs contained in OLE @c VARIANTs will be
returned as wxVariants with wxVariantDataSafeArray type instead of
wxVariants with the list type containing the (flattened) SAFEARRAY's
elements.
*/
wxOleConvertVariant_ReturnSafeArrays = 1
};
/**
@class wxVariantDataCurrency
This class represents a thin wrapper for Microsoft Windows @c CURRENCY type.
It is used for converting between wxVariant and OLE @c VARIANT
with type set to @c VT_CURRENCY. When wxVariant stores
wxVariantDataCurrency, it returns "currency" as its type.
An example of setting and getting @c CURRENCY value to and from wxVariant:
@code
CURRENCY cy;
wxVariant variant;
// set wxVariant to currency type
if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) ) // set cy to 123.45
{
variant.SetData(new wxVariantDataCurrency(cy));
// or instead of the line above you could write:
// wxVariantDataCurrency wxCy;
// wxCy.SetValue(cy);
// variant.SetData(wxCy.Clone());
}
// get CURRENCY value from wxVariant
if ( variant.GetType() == "currency" )
{
wxVariantDataCurrency*
wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
cy = wxCy->GetValue();
}
@endcode
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
*/
class wxVariantDataCurrency : public wxVariantData
{
public:
/**
Default constructor initializes the object to 0.0.
*/
wxVariantDataCurrency();
/**
Constructor from CURRENCY.
*/
wxVariantDataCurrency(CURRENCY value);
/**
Returns the stored CURRENCY value.
*/
CURRENCY GetValue() const;
/**
Sets the stored value to @a value.
*/
void SetValue(CURRENCY value);
/**
Returns @true if @a data is of wxVariantDataCurency type
and contains the same CURRENCY value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
The implementation of this method uses @c VarBstrFromCy() Windows API
function with @c LOCALE_USER_DEFAULT.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "currency".
*/
virtual wxString GetType() const;
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};
/**
@class wxVariantDataErrorCode
This class represents a thin wrapper for Microsoft Windows @c SCODE type
(which is the same as @c HRESULT).
It is used for converting between a wxVariant and OLE @c VARIANT with type set
to @c VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
"errorcode" as its type. This class can be used for returning error codes
of automation calls or exchanging values with other applications: e.g.
Microsoft Excel returns VARIANTs with @c VT_ERROR type for cell values with
errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
there) etc. See wxVariantDataCurrency for an example of how to exchange
values between wxVariant and a native type not directly supported by it.
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency
*/
class wxVariantDataErrorCode : public wxVariantData
{
public:
/**
Constructor initializes the object to @a value or @c S_OK if no value was
passed.
*/
wxVariantDataErrorCode(SCODE value = S_OK);
/**
Returns the stored @c SCODE value.
*/
SCODE GetValue() const;
/**
Set the stored value to @a value.
*/
void SetValue(SCODE value);
/**
Returns @true if @a data is of wxVariantDataErrorCode type
and contains the same @c SCODE value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
The error code is just a number, so it's output as such.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "errorcode".
*/
virtual wxString GetType() const { return wxS("errorcode"); }
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};
/**
@class wxVariantDataSafeArray
This class stores @c SAFEARRAY in a wxVariant. It can be used
to pass arrays having more than one dimension with wxAutomationObject methods.
When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
wxVariantDataSafeArray does NOT manage the @c SAFEARRAY it points to.
If you want to pass it to a wxAutomationObject as a parameter:
-# Create and fill a @c SAFEARRAY.
-# Assign the @c SAFEARRAY pointer to it and store it in a wxVariant.
-# Call a wxAutomationObject method (such as CallMethod() or PutProperty()) with the wxVariant as a parameter.
-# wxAutomationObject will destroy the array after the automation call.
An example of creating a two-dimensional @c SAFEARRAY containing <tt>VARIANT</tt>s
and storing it in a wxVariant, using a utility class wxSafeArray<varType>.
@code
const size_t dimensions = 2;
const long rowCount = 1000;
const long columnCount = 20;
SAFEARRAYBOUND bounds[dimensions];
wxSafeArray<VT_VARIANT> safeArray;
bounds[0].lLbound = 0; // elements start at 0
bounds[0].cElements = rowCount;
bounds[1].lLbound = 0; // elements start at 0
bounds[1].cElements = columnCount;
if ( !safeArray.Create(bounds, dimensions) )
return false;
long indices[dimensions];
for ( long row = 0; row < rowCount; ++row )
{
indices[0] = row;
for ( long column = 0; column < columnCount; ++column )
{
indices[1] = column;
if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row, column)) )
return false;
}
}
range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(safeArray.Detach())));
@endcode
If you want to receive a @c SAFEARRAY in a wxVariant as a result of an wxAutomationObject
call:
-# Call wxAutomationObject::SetConvertVariantFlags() with parameter
::wxOleConvertVariant_ReturnSafeArrays (otherwise the data would be
sent as a flattened one-dimensional list).
-# Call a wxAutomationObject method (such as CallMethod() or GetProperty()).
-# Retrieve the @c SAFEARRAY from the returned wxVariant.
-# Process the data in the @c SAFEARRAY.
-# Destroy the @c SAFEARRAY when you no longer need it.
The following example shows how to process a two-dimensional @c SAFEARRAY
with @c VT_VARIANT type received from a wxAutomationObject call,
using a utility class wxSafeArray<varType>.
@code
const size_t dimensions = 2;
wxVariant result;
range.SetConvertVariantFlags(wxOleConvertVariant_ReturnSafeArrays);
result = range.GetProperty("Value");
if ( !result.IsType("safearray") )
return false;
wxSafeArray<VT_VARIANT> safeArray;
wxVariantDataSafeArray* const
sa = wxStaticCastVariantData(result.GetData(), wxVariantDataSafeArray);
if ( !safeArray.Attach(sa->GetValue()) )
{
if ( !safeArray.HasArray() )
::SafeArrayDestroy(sa->GetValue()); // we have to dispose the SAFEARRAY ourselves
return false;
}
if ( safeArray.GetDim() != dimensions ) // we are expecting 2 dimensions
return false; // SAFEARRAY will be disposed by safeArray's dtor
long rowStart, columnStart;
long rowCount, columnCount;
long indices[dimensions];
wxVariant value;
// get start indices and item counts for rows and columns
safeArray.GetLBound(1, rowStart);
safeArray.GetLBound(2, columnStart);
safeArray.GetUBound(1, rowCount);
safeArray.GetUBound(2, columnCount);
for ( long row = rowStart; row <= rowCount; ++row )
{
indices[0] = row;
for ( long column = columnStart; column <= columnCount; ++column )
{
indices[1] = column;
if ( !safeArray.GetElement(indices, value) )
return false;
// do something with value
}
}
// SAFEARRAY will be disposed by safeArray's dtor
@endcode
@onlyfor{wxmsw}
@since 2.9.5
@library{wxcore}
@category{data}
@see wxAutomationObject, wxSafeArray<varType>, wxVariant, wxVariantData
*/
class wxVariantDataSafeArray : public wxVariantData
{
public:
/**
Constructor initializes the object to @a value.
*/
explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);
/**
Returns the stored array.
*/
SAFEARRAY* GetValue() const;
/**
Set the stored array.
*/
void SetValue(SAFEARRAY* value);
/**
Returns @true if @a data is of wxVariantDataSafeArray type
and contains the same SAFEARRAY* value.
*/
virtual bool Eq(wxVariantData& data) const;
/**
Fills the provided string with the textual representation of this
object.
Only the address of @c SAFEARRAY pointer is output.
*/
virtual bool Write(wxString& str) const;
/**
Returns a copy of itself.
*/
wxVariantData* Clone() const;
/**
Returns "safearray".
*/
virtual wxString GetType() const;
/**
Converts the value of this object to wxAny.
*/
virtual bool GetAsAny(wxAny* any) const;
};

184
interface/wx/msw/ole/safearray.h Normal file
View File

@@ -0,0 +1,184 @@
/////////////////////////////////////////////////////////////////////////////
// Name: msw/ole/automtn.h
// Purpose: interface of wxSafeArray
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@class wxSafeArray<varType>
wxSafeArray<varType> is wxWidgets wrapper for working with MS Windows @c
SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs.
It also has convenience functions for converting between @c SAFEARRAY and
wxVariant with list type or wxArrayString.
wxSafeArray is a template class which must be created with an appropriate
type matching the underlying @c VARIANT type (such as @c VT_VARIANT or @c
VT_BSTR).
See wxVariantDataSafeArray documentation for examples of using it.
@onlyfor{wxmsw}
@since 3.0
@library{wxcore}
@category{data}
@see wxAutomationObject, wxVariantDataSafeArray, wxVariant
*/
template <VARTYPE varType>
class wxSafeArray<varType>
{
public:
/**
The default constructor.
*/
wxSafeArray();
/**
The destructor unlocks and destroys the owned @c SAFEARRAY.
*/
~wxSafeArray();
/**
Creates and locks a zero-based one-dimensional @c SAFEARRAY with the
given number of elements.
*/
bool Create(size_t count);
/**
Creates and locks a @c SAFEARRAY.
See @c SafeArrayCreate() in MSDN documentation for more information.
*/
bool Create(SAFEARRAYBOUND* bound, size_t dimensions);
/**
Creates a zero-based one-dimensional @c SAFEARRAY from wxVariant
with the list type.
Can be called only for wxSafeArray<@c VT_VARIANT>.
*/
bool CreateFromListVariant(const wxVariant& variant);
/**
Creates a zero-based one-dimensional @c SAFEARRAY from wxArrayString.
Can be called only for wxSafeArray<@c VT_BSTR>.
*/
bool CreateFromArrayString(const wxArrayString& strings);
/**
Attaches and locks an existing @c SAFEARRAY.
The array must have the same @c VARTYPE as this wxSafeArray was
instantiated with.
*/
bool Attach(SAFEARRAY* array);
/**
Unlocks the owned @c SAFEARRAY, returns it and gives up its ownership.
*/
SAFEARRAY* Detach();
/**
Unlocks and destroys the owned @c SAFEARRAY.
*/
void Destroy();
/**
Returns @true if it has a valid @c SAFEARRAY.
*/
bool HasArray() const { return m_array != NULL; }
/**
Returns the number of dimensions.
*/
size_t GetDim() const;
/**
Returns lower bound for dimension @a dim in @a bound.
Dimensions start at @c 1.
*/
bool GetLBound(size_t dim, long& bound) const;
/**
Returns upper bound for dimension @a dim in @a bound.
Dimensions start at @c 1.
*/
bool GetUBound(size_t dim, long& bound) const;
/**
Returns element count for dimension @a dim. Dimensions start at @c 1.
*/
size_t GetCount(size_t dim) const;
/**
Change the value of the specified element.
@a indices have the same row-column order as @c rgIndices i
@c SafeArrayPutElement(), i.e., the right-most dimension is
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@a element must be of type matching @c varType this wxSafeArray was
created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
wxSafeArray<@c VT_R8>.
*/
bool SetElement(long* indices, const externT& element);
/**
Retrieve the value of the specified element.
@a indices have the same row-column order as @c rgIndices in
@c SafeArrayGetElement(), i.e., the right-most dimension is
<tt>rgIndices[0]</tt> and the left-most dimension is stored at
<tt>rgIndices[</tt>GetDim()<tt> – 1]</tt>.
@a element must be of type matching @c varType this wxSafeArray was
created with. For example, wxString for wxSafeArray<@c VT_BSTR>,
wxVariant for wxSafeArray<@c VT_VARIANT>, or @c double for
wxSafeArray<@c VT_R8>.
*/
bool GetElement(long* indices, externT& element) const;
/**
Converts the array to a wxVariant with the list type, regardless of the
underlying @c SAFEARRAY type.
If the array is multidimensional, it is flattened using the algorithm
originally employed in wxConvertOleToVariant().
*/
bool ConvertToVariant(wxVariant& variant) const;
/**
Converts an array to wxArrayString.
Can be called only for wxSafeArray<@c VT_BSTR>. If the array is
multidimensional, it is flattened using the algorithm originally
employed in wxConvertOleToVariant().
*/
bool ConvertToArrayString(wxArrayString& strings) const;
/**
Converts @a psa to wxVariant.
@see wxSafeArray<varType>::ConvertToVariant(wxVariant&) const
*/
static bool ConvertToVariant(SAFEARRAY* psa, wxVariant& variant);
/**
Converts @a psa to wxArrayString.
@see wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const
*/
static bool ConvertToArrayString(SAFEARRAY* psa, wxArrayString& strings);
};