wxVariantDataSafeArray Class Reference

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

Inheritance diagram for wxVariantDataSafeArray:

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 VARIANTs 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())));

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

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.