Version: 3.1.4
wxSafeArray< varType > Class Template Reference

#include <wx/msw/ole/safearray.h>

Detailed Description

template<VARTYPE varType>
class wxSafeArray< varType >

wxSafeArray<varType> is wxWidgets wrapper for working with MS Windows SAFEARRAY used in Component Object Model (COM) and OLE Automation APIs.

It also has convenience functions for converting between SAFEARRAY and wxVariant with list type or wxArrayString.

wxSafeArray is a template class which must be created with an appropriate type matching the underlying VARIANT type (such as VT_VARIANT or VT_BSTR).

See wxVariantDataSafeArray documentation for examples of using it.

Availability:  only available for the wxMSW port.
Since
3.0

Library:  wxCore
Category:  Data Structures
See also
wxAutomationObject, wxVariantDataSafeArray, wxVariant

Public Member Functions

 wxSafeArray ()
 The default constructor. More...
 
 ~wxSafeArray ()
 The destructor unlocks and destroys the owned SAFEARRAY. More...
 
bool Create (size_t count)
 Creates and locks a zero-based one-dimensional SAFEARRAY with the given number of elements. More...
 
bool Create (SAFEARRAYBOUND *bound, size_t dimensions)
 Creates and locks a SAFEARRAY. More...
 
bool CreateFromListVariant (const wxVariant &variant)
 Creates a zero-based one-dimensional SAFEARRAY from wxVariant with the list type. More...
 
bool CreateFromArrayString (const wxArrayString &strings)
 Creates a zero-based one-dimensional SAFEARRAY from wxArrayString. More...
 
bool Attach (SAFEARRAY *array)
 Attaches and locks an existing SAFEARRAY. More...
 
SAFEARRAY * Detach ()
 Unlocks the owned SAFEARRAY, returns it and gives up its ownership. More...
 
void Destroy ()
 Unlocks and destroys the owned SAFEARRAY. More...
 
bool HasArray () const
 Returns true if it has a valid SAFEARRAY. More...
 
size_t GetDim () const
 Returns the number of dimensions. More...
 
bool GetLBound (size_t dim, long &bound) const
 Returns lower bound for dimension dim in bound. More...
 
bool GetUBound (size_t dim, long &bound) const
 Returns upper bound for dimension dim in bound. More...
 
size_t GetCount (size_t dim) const
 Returns element count for dimension dim. More...
 
bool SetElement (long *indices, const externT &element)
 Change the value of the specified element. More...
 
bool GetElement (long *indices, externT &element) const
 Retrieve the value of the specified element. More...
 
bool ConvertToVariant (wxVariant &variant) const
 Converts the array to a wxVariant with the list type, regardless of the underlying SAFEARRAY type. More...
 
bool ConvertToArrayString (wxArrayString &strings) const
 Converts an array to wxArrayString. More...
 

Static Public Member Functions

static bool ConvertToVariant (SAFEARRAY *psa, wxVariant &variant)
 Converts psa to wxVariant. More...
 
static bool ConvertToArrayString (SAFEARRAY *psa, wxArrayString &strings)
 Converts psa to wxArrayString. More...
 

Constructor & Destructor Documentation

template<VARTYPE varType>
wxSafeArray< varType >::wxSafeArray ( )

The default constructor.

template<VARTYPE varType>
wxSafeArray< varType >::~wxSafeArray ( )

The destructor unlocks and destroys the owned SAFEARRAY.

Member Function Documentation

template<VARTYPE varType>
bool wxSafeArray< varType >::Attach ( SAFEARRAY *  array)

Attaches and locks an existing SAFEARRAY.

The array must have the same VARTYPE as this wxSafeArray was instantiated with.

template<VARTYPE varType>
bool wxSafeArray< varType >::ConvertToArrayString ( wxArrayString strings) const

Converts an array to wxArrayString.

Can be called only for wxSafeArray<VT_BSTR>. If the array is multidimensional, it is flattened using the algorithm originally employed in wxConvertOleToVariant().

template<VARTYPE varType>
static bool wxSafeArray< varType >::ConvertToArrayString ( SAFEARRAY *  psa,
wxArrayString strings 
)
static
template<VARTYPE varType>
bool wxSafeArray< varType >::ConvertToVariant ( wxVariant variant) const

Converts the array to a wxVariant with the list type, regardless of the underlying SAFEARRAY type.

If the array is multidimensional, it is flattened using the algorithm originally employed in wxConvertOleToVariant().

template<VARTYPE varType>
static bool wxSafeArray< varType >::ConvertToVariant ( SAFEARRAY *  psa,
wxVariant variant 
)
static
template<VARTYPE varType>
bool wxSafeArray< varType >::Create ( size_t  count)

Creates and locks a zero-based one-dimensional SAFEARRAY with the given number of elements.

template<VARTYPE varType>
bool wxSafeArray< varType >::Create ( SAFEARRAYBOUND *  bound,
size_t  dimensions 
)

Creates and locks a SAFEARRAY.

See SafeArrayCreate() in MSDN documentation for more information.

template<VARTYPE varType>
bool wxSafeArray< varType >::CreateFromArrayString ( const wxArrayString strings)

Creates a zero-based one-dimensional SAFEARRAY from wxArrayString.

Can be called only for wxSafeArray<VT_BSTR>.

template<VARTYPE varType>
bool wxSafeArray< varType >::CreateFromListVariant ( const wxVariant variant)

Creates a zero-based one-dimensional SAFEARRAY from wxVariant with the list type.

Can be called only for wxSafeArray<VT_VARIANT>.

template<VARTYPE varType>
void wxSafeArray< varType >::Destroy ( )

Unlocks and destroys the owned SAFEARRAY.

template<VARTYPE varType>
SAFEARRAY* wxSafeArray< varType >::Detach ( )

Unlocks the owned SAFEARRAY, returns it and gives up its ownership.

template<VARTYPE varType>
size_t wxSafeArray< varType >::GetCount ( size_t  dim) const

Returns element count for dimension dim.

Dimensions start at 1.

template<VARTYPE varType>
size_t wxSafeArray< varType >::GetDim ( ) const

Returns the number of dimensions.

template<VARTYPE varType>
bool wxSafeArray< varType >::GetElement ( long *  indices,
externT &  element 
) const

Retrieve the value of the specified element.

indices have the same row-column order as rgIndices in SafeArrayGetElement(), i.e., the right-most dimension is rgIndices[0] and the left-most dimension is stored at rgIndices[GetDim() – 1].

element must be of type matching varType this wxSafeArray was created with. For example, wxString for wxSafeArray<VT_BSTR>, wxVariant for wxSafeArray<VT_VARIANT>, or double for wxSafeArray<VT_R8>.

template<VARTYPE varType>
bool wxSafeArray< varType >::GetLBound ( size_t  dim,
long &  bound 
) const

Returns lower bound for dimension dim in bound.

Dimensions start at 1.

template<VARTYPE varType>
bool wxSafeArray< varType >::GetUBound ( size_t  dim,
long &  bound 
) const

Returns upper bound for dimension dim in bound.

Dimensions start at 1.

template<VARTYPE varType>
bool wxSafeArray< varType >::HasArray ( ) const
inline

Returns true if it has a valid SAFEARRAY.

template<VARTYPE varType>
bool wxSafeArray< varType >::SetElement ( long *  indices,
const externT &  element 
)

Change the value of the specified element.

indices have the same row-column order as rgIndices i SafeArrayPutElement(), i.e., the right-most dimension is rgIndices[0] and the left-most dimension is stored at rgIndices[GetDim() – 1].

element must be of type matching varType this wxSafeArray was created with. For example, wxString for wxSafeArray<VT_BSTR>, wxVariant for wxSafeArray<VT_VARIANT>, or double for wxSafeArray<VT_R8>.