[wxWidgets.git] / interface / wx / msw / ole / automtn.h

/////////////////////////////////////////////////////////////////////////////
// Name:        msw/ole/automtn.h
// Purpose:     interface of wxAutomationObject
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    Automation object creation flags.

    These flags can be used with wxAutomationObject::GetInstance().

    @since 2.9.2
*/
enum wxAutomationInstanceFlags
{
    /**
        Only use the existing instance, never create a new one.

        This flag can be used to forbid the creation of a new instance if none
        is currently running.
     */
    wxAutomationInstance_UseExistingOnly = 0,

    /**
        Create a new instance if there are no existing ones.

        This flag corresponds to the default behaviour of
        wxAutomationObject::GetInstance() and means that if getting an existing
        instance failed, we should call wxAutomationObject::CreateInstance() to
        create a new one.
     */
    wxAutomationInstance_CreateIfNeeded = 1,

    /**
        Do not show an error message if no existing instance is currently
        running.

        All other errors will still be reported as usual.
     */
    wxAutomationInstance_SilentIfNone = 2
};

/**
    @class wxVariantDataCurrency

    This class represents a thin wrapper for Microsoft Windows CURRENCY type.

    It is used for converting between wxVariant and OLE VARIANT
    with type set to VT_CURRENCY. When wxVariant stores
    wxVariantDataCurrency, it returns "currency" as its type.

    An example of setting and getting CURRENCY value to and from wxVariant:
    @code
    CURRENCY cy;
    wxVariant variant;

    // set wxVariant to currency type
    if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) )  // set cy to 123.45
    {
        variant.SetData(new wxVariantDataCurrency(cy));

        // or instead of the line above you could write:
        // wxVariantDataCurrency wxCy;
        // wxCy.SetValue(cy);
        // variant.SetData(wxCy.Clone());
    }

    // get CURRENCY value from wxVariant
    if ( variant.GetType() == "currency" )
    {
        wxVariantDataCurrency*
            wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
        cy = wxCy->GetValue();
    }
    @endcode

    @onlyfor{wxmsw}
    @since 2.9.5

    @library{wxcore}
    @category{data}

    @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode

    @header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataCurrency : public wxVariantData
{
public:
    /**
        Default constructor initializes the object to 0.0.
    */
    wxVariantDataCurrency();

    /**
        Constructor from CURRENCY.
    */
    wxVariantDataCurrency(CURRENCY value);

    /**
        Returns the stored CURRENCY value.
    */
    CURRENCY GetValue() const;

    /**
        Sets the stored value to @a value.
    */
    void SetValue(CURRENCY value);

    /**
        Returns true if @a data is of wxVariantDataCurency type
        and contains the same CURRENCY value.
    */
    virtual bool Eq(wxVariantData& data) const;

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

        The implementation of this method using @c VarBstrFromCy() Windows API
        function with LOCALE_USER_DEFAULT.
    */
    virtual bool Write(wxString& str) const;

    /**
        Returns a copy of itself.
    */
    wxVariantData* Clone() const;

    /**
        Returns "currency".
    */
    virtual wxString GetType() const;

    /**
        Converts the value of this object to wxAny.
    */
    virtual bool GetAsAny(wxAny* any) const;
};


/**
    @class wxVariantDataErrorCode

    This class represents a thin wrapper for Microsoft Windows SCODE type
    (which is the same as HRESULT).

    It is used for converting between a wxVariant and OLE VARIANT with type set
    to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
    "errorcode" as its type. This class can be used for returning error codes
    of automation calls or exchanging values with other applications: e.g.
    Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with
    errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
    there) etc. See wxVariantDataCurrency for an example of how to  exchange
    values between wxVariant and a native type not directly supported by it.

    @onlyfor{wxmsw}
    @since 2.9.5

    @library{wxcore}
    @category{data}

    @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency

    @header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataErrorCode : public wxVariantData
{
public:
    /**
        Constructor initializes the object to @a value or S_OK if no value was
        passed.
    */
    wxVariantDataErrorCode(SCODE value = S_OK);

    /**
        Returns the stored SCODE value.
    */
    SCODE GetValue() const;

    /**
        Set the stored value to @a value.
    */
    void SetValue(SCODE value);

    /**
        Returns true if @a data is of wxVariantDataErrorCode type
        and contains the same SCODE value.
    */
    virtual bool Eq(wxVariantData& data) const;

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

        The error code is just a number, so it's output as such.
    */
    virtual bool Write(wxString& str) const;

    /**
        Returns a copy of itself.
    */
    wxVariantData* Clone() const;

    /**
        Returns "errorcode".
    */
    virtual wxString GetType() const { return wxS("errorcode"); }

    /**
        Converts the value of this object to wxAny.
    */
    virtual bool GetAsAny(wxAny* any) const;
};

/**
    @class wxVariantDataSafeArray

    This class represents a thin wrapper for Microsoft Windows SAFEARRAY type.

    It is used for converting between wxVariant and OLE VARIANT
    with type set to VT_ARRAY, which has more than one dimension.
    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:
        -# Assign a SAFEARRAY pointer to it and store it in a wxVariant.
        -# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke())
        -# wxAutomationObject will destroy the array after the approapriate automation call.

    An example of creating a 2-dimensional SAFEARRAY containing VARIANTs
    and storing it in a wxVariant
    @code
    SAFEARRAYBOUND bounds[2]; // 2 dimensions
    wxSafeArray<VT_VARIANT> safeArray;
    unsigned rowCount = 1000;
    unsigned colCount = 20;

    bounds[0].lLbound = 0; // elements start at 0
    bounds[0].cElements = rowCount;
    bounds[1].lLbound = 0; // elements start at 0
    bounds[1].cElements = colCount;

    if ( !safeArray.Create(bounds, 2) )
        return false;

    long indices[2];

    for ( unsigned row = 0; row < rowCount; row++ )
    {
        indices[0] = row;
        for ( unsigned col = 0; col < colCount; col++ )
        {
            indices[1] = col;
            if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row+1, col+1)) )
               return false;
        }
    }
    range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(sa.Detach())));
    @endcode

    If you you received wxVariantDataSafeArray as a result of wxAutomationObject method call:
    (1) Get the data out of the array.
    (2) Destroy the array.
    @code
    wxVariant result;
    result = range.GetProperty("Value");
    if ( result.GetType() == "safearray" )
    {
        wxSafeArray<VT_VARIANT> safeArray;
        wxVariantDataSafeArray* const
            sa = wxStaticCastVariantData(variant.GetData(), wxVariantDataSafeArray);

        if ( !safeArray.Attach(sa.GetValue() )
        {
            if ( !safeArray.HasArray() )
                SafeArrayDestroy(sa.GetValue()); // we have to dispose the SAFEARRAY ourselves
            return false;
        }

        // get the data from the SAFEARRAY using wxSafeArray::GetElement()
        // SAFEARRAY will be disposed by safeArray's dtor
    }
    @endcode

    @onlyfor{wxmsw}
    @since 2.9.5

    @library{wxcore}
    @category{data}

    @see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode

    @header{wx/msw/ole/oleutils.h}
*/
class wxVariantDataSafeArray : public wxVariantData
{
public:
    /**
        Constructor initializes the object to @a value.
    */
    explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);

    /**
        Returns the stored array.
    */
    SAFEARRAY* GetValue() const;

    /**
        Set the stored array.
    */
    void SetValue(SAFEARRAY* value);

    /**
        Returns true if @a data is of wxVariantDataSafeArray type
        and contains the same SAFEARRAY* value.
    */
    virtual bool Eq(wxVariantData& data) const;

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

        Only the address of SAFEARRAY pointer is output.
    */
    virtual bool Write(wxString& str) const;

    /**
        Returns a copy of itself.
    */
    wxVariantData* Clone() const;

    /**
        Returns "safearray".
    */
    virtual wxString GetType() const;

    /**
        Converts the value of this object to wxAny.
    */
    virtual bool GetAsAny(wxAny* any) const;
};

/**
    @class wxAutomationObject

    The @b wxAutomationObject class represents an OLE automation object containing
    a single data member,
    an IDispatch pointer. It contains a number of functions that make it easy to
    perform
    automation operations, and set and get properties. The class makes heavy use of
    the wxVariant class.

    The usage of these classes is quite close to OLE automation usage in Visual
    Basic. The API is
    high-level, and the application can specify multiple properties in a single
    string. The following example
    gets the current Excel instance, and if it exists, makes the active cell bold.

    @code
    wxAutomationObject excelObject;
      if (excelObject.GetInstance("Excel.Application"))
          excelObject.PutProperty("ActiveCell.Font.Bold", @true);
    @endcode

    Note that this class obviously works under Windows only.

    @onlyfor{wxmsw}

    @library{wxcore}
    @category{data}

    @see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray
*/
class wxAutomationObject : public wxObject
{
public:
    /**
        Constructor, taking an optional IDispatch pointer which will be released when
        the
        object is deleted.
    */
    wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);

    /**
        Destructor. If the internal IDispatch pointer is non-null, it will be released.
    */
    ~wxAutomationObject();

    //@{
    /**
        Calls an automation method for this object. The first form takes a method name,
        number of
        arguments, and an array of variants. The second form takes a method name and
        zero to six
        constant references to variants. Since the variant class has constructors for
        the basic
        data types, and C++ provides temporary objects automatically, both of the
        following lines
        are syntactically valid:

        Note that @a method can contain dot-separated property names, to save the
        application
        needing to call GetProperty several times using several temporary objects. For
        example:
    */
    wxVariant CallMethod(const wxString& method, int noArgs,
                         wxVariant args[]) const;
    const wxVariant  CallMethod(const wxString& method, ... ) const;
    //@}

    /**
        Creates a new object based on the ProgID, returning @true if the object was
        successfully created,
        or @false if not.
    */
    bool CreateInstance(const wxString& progId) const;

    /**
        Checks if the object is in a valid state.

        Returns @true if the object was successfully initialized or @false if
        it has no valid IDispatch pointer.

        @see GetDispatchPtr()
     */
    bool IsOk() const;

    /**
        Gets the IDispatch pointer.

        Notice that the return value of this function is an untyped pointer but
        it can be safely cast to @c IDispatch.
    */
    void* GetDispatchPtr() const;

    /**
        Retrieves the current object associated with the specified ProgID, and
        attaches the IDispatch pointer to this object.

        If attaching to an existing object failed and @a flags includes
        wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
        Otherwise this function will normally log an error message which may be
        undesirable if the object may or may not exist. The
        wxAutomationInstance_SilentIfNone flag can be used to prevent the error
        from being logged in this case.

        Returns @true if a pointer was successfully retrieved, @false
        otherwise.

        Note that this cannot cope with two instances of a given OLE object being
        active simultaneously,
        such as two copies of Excel running. Which object is referenced cannot
        currently be specified.

        @param progId COM ProgID, e.g. "Excel.Application"
        @param flags The creation flags (this parameters was added in wxWidgets
            2.9.2)
    */
    bool GetInstance(const wxString& progId,
                     int flags = wxAutomationInstance_CreateIfNeeded) const;

    /**
        Retrieves a property from this object, assumed to be a dispatch pointer, and
        initialises @a obj with it.
        To avoid having to deal with IDispatch pointers directly, use this function in
        preference
        to GetProperty() when retrieving objects
        from other objects.
        Note that an IDispatch pointer is stored as a void* pointer in wxVariant
        objects.

        @see GetProperty()
    */
    bool GetObject(wxAutomationObject& obj, const wxString& property,
                   int noArgs = 0,
                   wxVariant args[] = NULL) const;

    //@{
    /**
        Gets a property value from this object. The first form takes a property name,
        number of
        arguments, and an array of variants. The second form takes a property name and
        zero to six
        constant references to variants. Since the variant class has constructors for
        the basic
        data types, and C++ provides temporary objects automatically, both of the
        following lines
        are syntactically valid:

        Note that @a property can contain dot-separated property names, to save the
        application
        needing to call GetProperty several times using several temporary objects.
    */
    wxVariant GetProperty(const wxString& property, int noArgs,
                          wxVariant args[]) const;
    const wxVariant  GetProperty(const wxString& property, ... ) const;
    //@}

    /**
        This function is a low-level implementation that allows access to the IDispatch
        Invoke function.
        It is not meant to be called directly by the application, but is used by other
        convenience functions.

        @param member
            The member function or property name.
        @param action
            Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
            DISPATCH_METHOD.
        @param retValue
            Return value (ignored if there is no return value)
        @param noArgs
            Number of arguments in args or ptrArgs.
        @param args
            If non-null, contains an array of variants.
        @param ptrArgs
            If non-null, contains an array of constant pointers to variants.

        @return @true if the operation was successful, @false otherwise.

        @remarks Two types of argument array are provided, so that when possible
                 pointers are used for efficiency.
    */
    bool Invoke(const wxString& member, int action,
                wxVariant& retValue, int noArgs,
                wxVariant args[],
                const wxVariant* ptrArgs[] = 0) const;

    //@{
    /**
        Puts a property value into this object. The first form takes a property name,
        number of
        arguments, and an array of variants. The second form takes a property name and
        zero to six
        constant references to variants. Since the variant class has constructors for
        the basic
        data types, and C++ provides temporary objects automatically, both of the
        following lines
        are syntactically valid:

        Note that @a property can contain dot-separated property names, to save the
        application
        needing to call GetProperty several times using several temporary objects.
    */
    bool PutProperty(const wxString& property, int noArgs,
                     wxVariant args[]);
    const bool PutProperty(const wxString& property, ... );
    //@}

    /**
        Sets the IDispatch pointer. This function does not check if there is already an
        IDispatch pointer.
        You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
    */
    void SetDispatchPtr(WXIDISPATCH* dispatchPtr);

    /**
        Returns the locale identifier used in automation calls.

        The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
        GetObject() inherit the locale identifier from the one that created
        them.

        @since 2.9.5
    */
    LCID GetLCID() const;

    /**
        Sets the locale identifier to be used in automation calls performed by
        this object.

        The default value is LOCALE_SYSTEM_DEFAULT.

        Notice that any automation objects created by this one inherit the same
        LCID.

        @since 2.9.5
    */
    void SetLCID(LCID lcid);

};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: msw/ole/automtn.h
e54c96f1	3	// Purpose: interface of wxAutomationObject
23324ae1 FM	4	// Author: wxWidgets team
23324ae1 FM	5	// RCS-ID: $Id$
526954c5	6	// Licence: wxWindows licence
23324ae1 FM	7	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	8
6eefca4f VZ	9	/**
	10	Automation object creation flags.
	11
	12	These flags can be used with wxAutomationObject::GetInstance().
	13
	14	@since 2.9.2
	15	*/
	16	enum wxAutomationInstanceFlags
	17	{
	18	/**
	19	Only use the existing instance, never create a new one.
	20
	21	This flag can be used to forbid the creation of a new instance if none
	22	is currently running.
	23	*/
	24	wxAutomationInstance_UseExistingOnly = 0,
	25
	26	/**
	27	Create a new instance if there are no existing ones.
	28
	29	This flag corresponds to the default behaviour of
	30	wxAutomationObject::GetInstance() and means that if getting an existing
	31	instance failed, we should call wxAutomationObject::CreateInstance() to
	32	create a new one.
	33	*/
1244d2e0 VZ	34	wxAutomationInstance_CreateIfNeeded = 1,
	35
	36	/**
	37	Do not show an error message if no existing instance is currently
	38	running.
	39
	40	All other errors will still be reported as usual.
	41	*/
	42	wxAutomationInstance_SilentIfNone = 2
6eefca4f VZ	43	};
6eefca4f VZ	44
7f3bd468 VZ	45	/**
	46	@class wxVariantDataCurrency
	47
	48	This class represents a thin wrapper for Microsoft Windows CURRENCY type.
	49
	50	It is used for converting between wxVariant and OLE VARIANT
	51	with type set to VT_CURRENCY. When wxVariant stores
	52	wxVariantDataCurrency, it returns "currency" as its type.
	53
	54	An example of setting and getting CURRENCY value to and from wxVariant:
	55	@code
	56	CURRENCY cy;
	57	wxVariant variant;
	58
	59	// set wxVariant to currency type
	60	if ( SUCCEEDED(VarCyFromR8(123.45, &cy)) ) // set cy to 123.45
	61	{
	62	variant.SetData(new wxVariantDataCurrency(cy));
	63
	64	// or instead of the line above you could write:
	65	// wxVariantDataCurrency wxCy;
	66	// wxCy.SetValue(cy);
	67	// variant.SetData(wxCy.Clone());
	68	}
	69
	70	// get CURRENCY value from wxVariant
	71	if ( variant.GetType() == "currency" )
	72	{
	73	wxVariantDataCurrency*
	74	wxCy = wxDynamicCastVariantData(variant.GetData(), wxVariantDataCurrency);
	75	cy = wxCy->GetValue();
	76	}
	77	@endcode
	78
	79	@onlyfor{wxmsw}
	80	@since 2.9.5
	81
	82	@library{wxcore}
	83	@category{data}
	84
	85	@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
	86
	87	@header{wx/msw/ole/oleutils.h}
	88	*/
	89	class wxVariantDataCurrency : public wxVariantData
	90	{
	91	public:
	92	/**
	93	Default constructor initializes the object to 0.0.
	94	*/
	95	wxVariantDataCurrency();
	96
	97	/**
	98	Constructor from CURRENCY.
	99	*/
	100	wxVariantDataCurrency(CURRENCY value);
	101
	102	/**
	103	Returns the stored CURRENCY value.
	104	*/
	105	CURRENCY GetValue() const;
	106
	107	/**
	108	Sets the stored value to @a value.
109	*/
110	void SetValue(CURRENCY value);
111
112	/**
113	Returns true if @a data is of wxVariantDataCurency type
114	and contains the same CURRENCY value.
115	*/
116	virtual bool Eq(wxVariantData& data) const;
117
118	/**
119	Fills the provided string with the textual representation of this
120	object.
121
122	The implementation of this method using @c VarBstrFromCy() Windows API
123	function with LOCALE_USER_DEFAULT.
124	*/
125	virtual bool Write(wxString& str) const;
126
127	/**
128	Returns a copy of itself.
129	*/
130	wxVariantData* Clone() const;
131
132	/**
133	Returns "currency".
134	*/
135	virtual wxString GetType() const;
136
137	/**
138	Converts the value of this object to wxAny.
139	*/
140	virtual bool GetAsAny(wxAny* any) const;
141	};
142
143
144	/**
145	@class wxVariantDataErrorCode
146
147	This class represents a thin wrapper for Microsoft Windows SCODE type
148	(which is the same as HRESULT).
149
150	It is used for converting between a wxVariant and OLE VARIANT with type set
151	to VT_ERROR. When wxVariant stores wxVariantDataErrorCode, it returns
152	"errorcode" as its type. This class can be used for returning error codes
153	of automation calls or exchanging values with other applications: e.g.
154	Microsoft Excel returns VARIANTs with VT_ERROR type for cell values with
155	errors (one of XlCVError constants, displayed as e.g. "#DIV/0!" or "#REF!"
156	there) etc. See wxVariantDataCurrency for an example of how to exchange
157	values between wxVariant and a native type not directly supported by it.
158
159	@onlyfor{wxmsw}
160	@since 2.9.5
161
162	@library{wxcore}
163	@category{data}
164
165	@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataCurrency
166
167	@header{wx/msw/ole/oleutils.h}
168	*/
169	class wxVariantDataErrorCode : public wxVariantData
170	{
171	public:
172	/**
173	Constructor initializes the object to @a value or S_OK if no value was
174	passed.
175	*/
176	wxVariantDataErrorCode(SCODE value = S_OK);
177
178	/**
179	Returns the stored SCODE value.
180	*/
181	SCODE GetValue() const;
182
183	/**
184	Set the stored value to @a value.
185	*/
186	void SetValue(SCODE value);
187
188	/**
189	Returns true if @a data is of wxVariantDataErrorCode type
190	and contains the same SCODE value.
191	*/
192	virtual bool Eq(wxVariantData& data) const;
193
194	/**
195	Fills the provided string with the textual representation of this
196	object.
197
198	The error code is just a number, so it's output as such.
199	*/
200	virtual bool Write(wxString& str) const;
201
202	/**
203	Returns a copy of itself.
204	*/
205	wxVariantData* Clone() const;
206
207	/**
208	Returns "errorcode".
209	*/
210	virtual wxString GetType() const { return wxS("errorcode"); }
211
212	/**
213	Converts the value of this object to wxAny.
214	*/
215	virtual bool GetAsAny(wxAny* any) const;
216	};
217
226fa6db VZ	218	/**
	219	@class wxVariantDataSafeArray
	220
	221	This class represents a thin wrapper for Microsoft Windows SAFEARRAY type.
	222
	223	It is used for converting between wxVariant and OLE VARIANT
	224	with type set to VT_ARRAY, which has more than one dimension.
	225	When wxVariant stores wxVariantDataSafeArray, it returns "safearray" as its type.
	226
	227	wxVariantDataSafeArray does NOT manage the SAFEARRAY it points to.
	228	If you want to pass it to a wxAutomationObject as a parameter:
	229	-# Assign a SAFEARRAY pointer to it and store it in a wxVariant.
	230	-# Call the wxAutomationObject method (CallMethod(), SetProperty() or Invoke())
	231	-# wxAutomationObject will destroy the array after the approapriate automation call.
	232
	233	An example of creating a 2-dimensional SAFEARRAY containing VARIANTs
	234	and storing it in a wxVariant
	235	@code
	236	SAFEARRAYBOUND bounds[2]; // 2 dimensions
	237	wxSafeArray<VT_VARIANT> safeArray;
	238	unsigned rowCount = 1000;
	239	unsigned colCount = 20;
	240
	241	bounds[0].lLbound = 0; // elements start at 0
	242	bounds[0].cElements = rowCount;
	243	bounds[1].lLbound = 0; // elements start at 0
	244	bounds[1].cElements = colCount;
	245
	246	if ( !safeArray.Create(bounds, 2) )
	247	return false;
	248
	249	long indices[2];
	250
	251	for ( unsigned row = 0; row < rowCount; row++ )
	252	{
	253	indices[0] = row;
	254	for ( unsigned col = 0; col < colCount; col++ )
	255	{
	256	indices[1] = col;
a7cf6f55	257	if ( !safeArray.SetElement(indices, wxString::Format("R%u C%u", row+1, col+1)) )
226fa6db VZ	258	return false;
	259	}
	260	}
	261	range.PutProperty("Value", wxVariant(new wxVariantDataSafeArray(sa.Detach())));
	262	@endcode
	263
	264	If you you received wxVariantDataSafeArray as a result of wxAutomationObject method call:
	265	(1) Get the data out of the array.
	266	(2) Destroy the array.
	267	@code
	268	wxVariant result;
	269	result = range.GetProperty("Value");
	270	if ( result.GetType() == "safearray" )
	271	{
	272	wxSafeArray<VT_VARIANT> safeArray;
	273	wxVariantDataSafeArray* const
	274	sa = wxStaticCastVariantData(variant.GetData(), wxVariantDataSafeArray);
	275
	276	if ( !safeArray.Attach(sa.GetValue() )
	277	{
	278	if ( !safeArray.HasArray() )
	279	SafeArrayDestroy(sa.GetValue()); // we have to dispose the SAFEARRAY ourselves
	280	return false;
	281	}
	282
	283	// get the data from the SAFEARRAY using wxSafeArray::GetElement()
	284	// SAFEARRAY will be disposed by safeArray's dtor
	285	}
	286	@endcode
	287
	288	@onlyfor{wxmsw}
	289	@since 2.9.5
	290
	291	@library{wxcore}
	292	@category{data}
	293
	294	@see wxAutomationObject, wxVariant, wxVariantData, wxVariantDataErrorCode
	295
	296	@header{wx/msw/ole/oleutils.h}
	297	*/
	298	class wxVariantDataSafeArray : public wxVariantData
	299	{
	300	public:
	301	/**
	302	Constructor initializes the object to @a value.
	303	*/
	304	explicit wxVariantDataSafeArray(SAFEARRAY* value = NULL);
	305
	306	/**
	307	Returns the stored array.
	308	*/
	309	SAFEARRAY* GetValue() const;
	310
	311	/**
	312	Set the stored array.
	313	*/
	314	void SetValue(SAFEARRAY* value);
	315
	316	/**
a7cf6f55 VZ	317	Returns true if @a data is of wxVariantDataSafeArray type
a7cf6f55 VZ	318	and contains the same SAFEARRAY* value.
226fa6db VZ	319	*/
	320	virtual bool Eq(wxVariantData& data) const;
	321
	322	/**
	323	Fills the provided string with the textual representation of this
	324	object.
	325
a7cf6f55	326	Only the address of SAFEARRAY pointer is output.
226fa6db VZ	327	*/
	328	virtual bool Write(wxString& str) const;
	329
	330	/**
	331	Returns a copy of itself.
	332	*/
	333	wxVariantData* Clone() const;
	334
	335	/**
	336	Returns "safearray".
	337	*/
	338	virtual wxString GetType() const;
	339
	340	/**
	341	Converts the value of this object to wxAny.
	342	*/
	343	virtual bool GetAsAny(wxAny* any) const;
	344	};
6eefca4f	345
23324ae1 FM	346	/**
23324ae1 FM	347	@class wxAutomationObject
4cc4bfaf	348
23324ae1 FM	349	The @b wxAutomationObject class represents an OLE automation object containing
	350	a single data member,
	351	an IDispatch pointer. It contains a number of functions that make it easy to
	352	perform
	353	automation operations, and set and get properties. The class makes heavy use of
	354	the wxVariant class.
4cc4bfaf	355
23324ae1 FM	356	The usage of these classes is quite close to OLE automation usage in Visual
	357	Basic. The API is
	358	high-level, and the application can specify multiple properties in a single
	359	string. The following example
	360	gets the current Excel instance, and if it exists, makes the active cell bold.
4cc4bfaf	361
23324ae1 FM	362	@code
	363	wxAutomationObject excelObject;
	364	if (excelObject.GetInstance("Excel.Application"))
	365	excelObject.PutProperty("ActiveCell.Font.Bold", @true);
	366	@endcode
4cc4bfaf	367
23324ae1	368	Note that this class obviously works under Windows only.
4cc4bfaf	369
d9faa1fe FM	370	@onlyfor{wxmsw}
d9faa1fe FM	371
23324ae1	372	@library{wxcore}
3c99e2fd	373	@category{data}
4cc4bfaf	374
226fa6db	375	@see wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray
23324ae1 FM	376	*/
	377	class wxAutomationObject : public wxObject
	378	{
	379	public:
	380	/**
	381	Constructor, taking an optional IDispatch pointer which will be released when
	382	the
	383	object is deleted.
	384	*/
4cc4bfaf	385	wxAutomationObject(WXIDISPATCH* dispatchPtr = NULL);
23324ae1 FM	386
	387	/**
	388	Destructor. If the internal IDispatch pointer is non-null, it will be released.
	389	*/
	390	~wxAutomationObject();
	391
	392	//@{
	393	/**
	394	Calls an automation method for this object. The first form takes a method name,
	395	number of
	396	arguments, and an array of variants. The second form takes a method name and
	397	zero to six
	398	constant references to variants. Since the variant class has constructors for
	399	the basic
	400	data types, and C++ provides temporary objects automatically, both of the
	401	following lines
	402	are syntactically valid:
d9faa1fe	403
4cc4bfaf	404	Note that @a method can contain dot-separated property names, to save the
23324ae1 FM	405	application
	406	needing to call GetProperty several times using several temporary objects. For
	407	example:
	408	*/
	409	wxVariant CallMethod(const wxString& method, int noArgs,
328f5751 FM	410	wxVariant args[]) const;
328f5751 FM	411	const wxVariant CallMethod(const wxString& method, ... ) const;
23324ae1 FM	412	//@}
	413
	414	/**
27d76879	415	Creates a new object based on the ProgID, returning @true if the object was
23324ae1 FM	416	successfully created,
	417	or @false if not.
	418	*/
27d76879	419	bool CreateInstance(const wxString& progId) const;
23324ae1	420
bb24f84b VZ	421	/**
	422	Checks if the object is in a valid state.
	423
	424	Returns @true if the object was successfully initialized or @false if
	425	it has no valid IDispatch pointer.
	426
	427	@see GetDispatchPtr()
	428	*/
	429	bool IsOk() const;
	430
23324ae1 FM	431	/**
23324ae1 FM	432	Gets the IDispatch pointer.
d72177fd VZ	433
	434	Notice that the return value of this function is an untyped pointer but
	435	it can be safely cast to @c IDispatch.
23324ae1	436	*/
d72177fd	437	void* GetDispatchPtr() const;
23324ae1 FM	438
23324ae1 FM	439	/**
27d76879 VZ	440	Retrieves the current object associated with the specified ProgID, and
	441	attaches the IDispatch pointer to this object.
	442
6eefca4f VZ	443	If attaching to an existing object failed and @a flags includes
6eefca4f VZ	444	wxAutomationInstance_CreateIfNeeded flag, a new object will be created.
1244d2e0 VZ	445	Otherwise this function will normally log an error message which may be
	446	undesirable if the object may or may not exist. The
	447	wxAutomationInstance_SilentIfNone flag can be used to prevent the error
	448	from being logged in this case.
6eefca4f	449
27d76879	450	Returns @true if a pointer was successfully retrieved, @false
23324ae1	451	otherwise.
6eefca4f	452
23324ae1 FM	453	Note that this cannot cope with two instances of a given OLE object being
	454	active simultaneously,
	455	such as two copies of Excel running. Which object is referenced cannot
	456	currently be specified.
6eefca4f VZ	457
	458	@param progId COM ProgID, e.g. "Excel.Application"
	459	@param flags The creation flags (this parameters was added in wxWidgets
	460	2.9.2)
23324ae1	461	*/
6eefca4f VZ	462	bool GetInstance(const wxString& progId,
6eefca4f VZ	463	int flags = wxAutomationInstance_CreateIfNeeded) const;
23324ae1 FM	464
	465	/**
	466	Retrieves a property from this object, assumed to be a dispatch pointer, and
4cc4bfaf	467	initialises @a obj with it.
23324ae1 FM	468	To avoid having to deal with IDispatch pointers directly, use this function in
	469	preference
	470	to GetProperty() when retrieving objects
	471	from other objects.
23324ae1 FM	472	Note that an IDispatch pointer is stored as a void* pointer in wxVariant
23324ae1 FM	473	objects.
d9faa1fe	474
4cc4bfaf	475	@see GetProperty()
23324ae1 FM	476	*/
	477	bool GetObject(wxAutomationObject& obj, const wxString& property,
	478	int noArgs = 0,
328f5751	479	wxVariant args[] = NULL) const;
23324ae1 FM	480
	481	//@{
	482	/**
	483	Gets a property value from this object. The first form takes a property name,
	484	number of
	485	arguments, and an array of variants. The second form takes a property name and
	486	zero to six
	487	constant references to variants. Since the variant class has constructors for
	488	the basic
	489	data types, and C++ provides temporary objects automatically, both of the
	490	following lines
	491	are syntactically valid:
d9faa1fe	492
4cc4bfaf	493	Note that @a property can contain dot-separated property names, to save the
23324ae1 FM	494	application
	495	needing to call GetProperty several times using several temporary objects.
	496	*/
	497	wxVariant GetProperty(const wxString& property, int noArgs,
328f5751 FM	498	wxVariant args[]) const;
328f5751 FM	499	const wxVariant GetProperty(const wxString& property, ... ) const;
23324ae1 FM	500	//@}
	501
	502	/**
	503	This function is a low-level implementation that allows access to the IDispatch
	504	Invoke function.
	505	It is not meant to be called directly by the application, but is used by other
	506	convenience functions.
d9faa1fe	507
4cc4bfaf FM	508	@param member
	509	The member function or property name.
	510	@param action
	511	Bitlist: may contain DISPATCH_PROPERTYPUT, DISPATCH_PROPERTYPUTREF,
	512	DISPATCH_METHOD.
	513	@param retValue
	514	Return value (ignored if there is no return value)
	515	@param noArgs
	516	Number of arguments in args or ptrArgs.
	517	@param args
	518	If non-null, contains an array of variants.
	519	@param ptrArgs
	520	If non-null, contains an array of constant pointers to variants.
d9faa1fe	521
d29a9a8a	522	@return @true if the operation was successful, @false otherwise.
d9faa1fe	523
23324ae1	524	@remarks Two types of argument array are provided, so that when possible
4cc4bfaf	525	pointers are used for efficiency.
23324ae1 FM	526	*/
	527	bool Invoke(const wxString& member, int action,
	528	wxVariant& retValue, int noArgs,
	529	wxVariant args[],
328f5751	530	const wxVariant* ptrArgs[] = 0) const;
23324ae1 FM	531
	532	//@{
	533	/**
	534	Puts a property value into this object. The first form takes a property name,
	535	number of
	536	arguments, and an array of variants. The second form takes a property name and
	537	zero to six
	538	constant references to variants. Since the variant class has constructors for
	539	the basic
	540	data types, and C++ provides temporary objects automatically, both of the
	541	following lines
	542	are syntactically valid:
d9faa1fe	543
4cc4bfaf	544	Note that @a property can contain dot-separated property names, to save the
23324ae1 FM	545	application
	546	needing to call GetProperty several times using several temporary objects.
	547	*/
	548	bool PutProperty(const wxString& property, int noArgs,
	549	wxVariant args[]);
328f5751	550	const bool PutProperty(const wxString& property, ... );
23324ae1 FM	551	//@}
	552
	553	/**
	554	Sets the IDispatch pointer. This function does not check if there is already an
	555	IDispatch pointer.
23324ae1 FM	556	You may need to cast from IDispatch* to WXIDISPATCH* when calling this function.
	557	*/
	558	void SetDispatchPtr(WXIDISPATCH* dispatchPtr);
f239af65 VZ	559
	560	/**
	561	Returns the locale identifier used in automation calls.
	562
	563	The default is LOCALE_SYSTEM_DEFAULT but the objects obtained by
	564	GetObject() inherit the locale identifier from the one that created
	565	them.
	566
	567	@since 2.9.5
	568	*/
	569	LCID GetLCID() const;
	570
	571	/**
	572	Sets the locale identifier to be used in automation calls performed by
	573	this object.
	574
	575	The default value is LOCALE_SYSTEM_DEFAULT.
	576
	577	Notice that any automation objects created by this one inherit the same
	578	LCID.
	579
	580	@since 2.9.5
	581	*/
	582	void SetLCID(LCID lcid);
	583
23324ae1	584	};
e54c96f1	585