wxWidgets: wxVariantDataSafeArray Class Reference

| Version: 3.2.5

Public Member Functions | List of all members
wxVariantDataSafeArray Class Reference
Class List by Category » Data Structures

`#include <wx/msw/ole/oleutils.h>`

Inheritance diagram for wxVariantDataSafeArray:
[legend]

## Detailed Description

This class stores `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 `SAFEARRAY` it points to. If you want to pass it to a wxAutomationObject as a parameter:

1. Create and fill a `SAFEARRAY`.
2. Assign the `SAFEARRAY` pointer to it and store it in a wxVariant.
3. Call a wxAutomationObject method (such as CallMethod() or PutProperty()) with the wxVariant as a parameter.
4. wxAutomationObject will destroy the array after the automation call.

An example of creating a two-dimensional `SAFEARRAY` containing `VARIANT`s and storing it in a wxVariant, using a utility class wxSafeArray<varType>.

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())));
wxString::Format
static wxString Format(const wxString &format,...)
This static function returns the string containing the result of calling Printf() with the passed par...
wxVariantDataSafeArray::wxVariantDataSafeArray
wxVariantDataSafeArray(SAFEARRAY *value=NULL)
Constructor initializes the object to value.
wxVariant
The wxVariant class represents a container for any type.
Definition: variant.h:163

If you want to receive a `SAFEARRAY` in a wxVariant as a result of an wxAutomationObject call:

1. Call wxAutomationObject::SetConvertVariantFlags() with parameter wxOleConvertVariant_ReturnSafeArrays (otherwise the data would be sent as a flattened one-dimensional list).
2. Call a wxAutomationObject method (such as CallMethod() or GetProperty()).
3. Retrieve the `SAFEARRAY` from the returned wxVariant.
4. Process the data in the `SAFEARRAY`.
5. Destroy the `SAFEARRAY` when you no longer need it.

The following example shows how to process a two-dimensional `SAFEARRAY` with `VT_VARIANT` type received from a wxAutomationObject call, using a utility class wxSafeArray<varType>.

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
wxVariantDataSafeArray
This class stores SAFEARRAY in a wxVariant.
Definition: oleutils.h:329
wxVariantDataSafeArray::GetValue
SAFEARRAY * GetValue() const
Returns the stored array.
wxVariant::IsType
bool IsType(const wxString &type) const
Returns true if type matches the type of the variant, false otherwise.
wxVariant::GetData
wxVariantData * GetData() const
Returns a pointer to the internal variant data.
wxOleConvertVariant_ReturnSafeArrays
@ wxOleConvertVariant_ReturnSafeArrays
If this flag is used, SAFEARRAYs contained in OLE VARIANTs will be returned as wxVariants with wxVari...
Definition: oleutils.h:33
Availability: only available for the wxMSW port.

Since
  2.9.5

##

Library: wxCore
Category: Data Structures

See also
  wxAutomationObject, wxSafeArray<varType>, wxVariant, wxVariantData

## Public Member Functions
| wxVariantDataSafeArray (SAFEARRAY *value=NULL)
| Constructor initializes the object to value. More...
SAFEARRAY * | GetValue () const
| Returns the stored array. More...
void | SetValue (SAFEARRAY *value)
| Set the stored array. More...
virtual bool | Eq (wxVariantData &data) const
| Returns true if data is of wxVariantDataSafeArray type and contains the same SAFEARRAY* value. More...
virtual bool | Write (wxString &str) const
| Fills the provided string with the textual representation of this object. More...
wxVariantData * | Clone () const
| Returns a copy of itself. More...
virtual wxString | GetType () const
| Returns "safearray". More...
virtual bool | GetAsAny (wxAny *any) const
| Converts the value of this object to wxAny. More...
Public Member Functions inherited from wxVariantData
| wxVariantData ()
| Default constructor. More...
void | DecRef ()
| Decreases reference count. More...
virtual bool | GetAny (wxAny *any) const
| Converts value to wxAny, if possible. More...
virtual wxClassInfo * | GetValueClassInfo ()
| If the data is a wxObject returns a pointer to the objects wxClassInfo structure, if the data isn't a wxObject the method returns NULL. More...
void | IncRef ()
| Increases reference count. More...
virtual bool | Read (istream &stream)
| Reads the data from stream. More...
virtual bool | Read (wxString &string)
| Reads the data from string. More...
virtual bool | Write (ostream &stream) const
| Writes the data to stream. More...

## Constructor & Destructor Documentation

## ◆ wxVariantDataSafeArray()

wxVariantDataSafeArray::wxVariantDataSafeArray | ( | SAFEARRAY * | value = `NULL` | ) |
| explicit

Constructor initializes the object to value.

## Member Function Documentation

## ◆ Clone()

wxVariantData* wxVariantDataSafeArray::Clone | ( |  | ) | const
| virtual

Returns a copy of itself.

Reimplemented from wxVariantData.

## ◆ Eq()

virtual bool wxVariantDataSafeArray::Eq | ( | wxVariantData & | data | ) | const
| virtual

Returns true if data is of wxVariantDataSafeArray type and contains the same SAFEARRAY* value.

Implements wxVariantData.

## ◆ GetAsAny()

virtual bool wxVariantDataSafeArray::GetAsAny | ( | wxAny * | any | ) | const
| virtual

Converts the value of this object to wxAny.

## ◆ GetType()

virtual wxString wxVariantDataSafeArray::GetType | ( |  | ) | const
| virtual

Returns "safearray".

Implements wxVariantData.

## ◆ GetValue()

SAFEARRAY* wxVariantDataSafeArray::GetValue | ( |  | ) | const

Returns the stored array.

## ◆ SetValue()

void wxVariantDataSafeArray::SetValue | ( | SAFEARRAY * | value | ) |

Set the stored array.

## ◆ Write()

virtual bool wxVariantDataSafeArray::Write | ( | wxString & | str | ) | const
| virtual

Fills the provided string with the textual representation of this object.

Only the address of `SAFEARRAY` pointer is output.

Reimplemented from wxVariantData.