| Version: 3.2.5

Public Member Functions | Static Public Member Functions | List of all members
wxSafeArray< varType > Class Template Reference
Class List by Category » Data Structures

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