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

Restructure OLE-related doxygen documentation

Browse Source 
All OLE-related classes and enums were described
in interface header msw/ole/automatn.h which led
to incorrectly listed include files in the generated
documentation for those classes and enum that
were actually declared in different include header files.

The documentation in the interface files has now been
split into files with names matching the actual include files.

Closes #18536
This commit is contained in:
PB
2019-10-22 20:46:13 +02:00
parent dddbc1bafc
commit 4f7a3fbbbd
3 changed files with 556 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);
};

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

@@ -0,0 +1,372 @@
/////////////////////////////////////////////////////////////////////////////
// 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
*/
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);
};