#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

◆ wxSafeArray()

template<VARTYPE varType>

wxSafeArray< varType >::wxSafeArray ( )

The default constructor.

◆ ~wxSafeArray()

template<VARTYPE varType>

wxSafeArray< varType >::~wxSafeArray ( )

The destructor unlocks and destroys the owned SAFEARRAY.

Member Function Documentation

◆ Attach()

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.

◆ ConvertToArrayString() [1/2]

template<VARTYPE varType>

static bool wxSafeArray< varType >::ConvertToArrayString	(	SAFEARRAY *	psa,
		wxArrayString &	strings
	)

static

Converts psa to wxArrayString.

See also: wxSafeArray<varType>::ConvertToArrayString(wxArrayString&) const

◆ ConvertToArrayString() [2/2]

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().

◆ ConvertToVariant() [1/2]

template<VARTYPE varType>

static bool wxSafeArray< varType >::ConvertToVariant	(	SAFEARRAY *	psa,
		wxVariant &	variant
	)

static

Converts psa to wxVariant.

See also: wxSafeArray<varType>::ConvertToVariant(wxVariant&) const

◆ ConvertToVariant() [2/2]

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().

◆ Create() [1/2]

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.

◆ Create() [2/2]

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.

◆ CreateFromArrayString()

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>.

◆ CreateFromListVariant()

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>.

◆ Destroy()

template<VARTYPE varType>

void wxSafeArray< varType >::Destroy ( )

Unlocks and destroys the owned SAFEARRAY.

◆ Detach()

template<VARTYPE varType>

SAFEARRAY * wxSafeArray< varType >::Detach ( )

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

◆ GetCount()

template<VARTYPE varType>

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

Returns element count for dimension dim.

Dimensions start at 1.

◆ GetDim()

template<VARTYPE varType>

size_t wxSafeArray< varType >::GetDim ( ) const

Returns the number of dimensions.

◆ GetElement()

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>.

◆ GetLBound()

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.

◆ GetUBound()

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.

◆ HasArray()

template<VARTYPE varType>

bool wxSafeArray< varType >::HasArray ( ) const

inline

Returns true if it has a valid SAFEARRAY.

◆ SetElement()

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>.

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

◆ wxSafeArray()

◆ ~wxSafeArray()

Member Function Documentation

◆ Attach()

◆ ConvertToArrayString() [1/2]

◆ ConvertToArrayString() [2/2]

◆ ConvertToVariant() [1/2]

◆ ConvertToVariant() [2/2]

◆ Create() [1/2]

◆ Create() [2/2]

◆ CreateFromArrayString()

◆ CreateFromListVariant()

◆ Destroy()

◆ Detach()

◆ GetCount()

◆ GetDim()

◆ GetElement()

◆ GetLBound()

◆ GetUBound()

◆ HasArray()

◆ SetElement()