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

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