wxWidgets: wxAutomationObject Class Reference

| Version: 3.2.2

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

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

Inheritance diagram for wxAutomationObject:
[legend]

## Detailed Description

The 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 Microsoft Excel instance, and if it exists, makes the active cell bold.

wxAutomationObject excelObject;
if ( excelObject.GetInstance("Excel.Application") )
excelObject.PutProperty("ActiveCell.Font.Bold", true);
wxAutomationObject
The wxAutomationObject class represents an OLE automation object containing a single data member,...
Definition: automtn.h:77
wxAutomationObject::PutProperty
bool PutProperty(const wxString &property, int noArgs, wxVariant args[])
Puts a property value into this object.
wxAutomationObject::GetInstance
bool GetInstance(const wxString &progId, int flags=wxAutomationInstance_CreateIfNeeded) const
Retrieves the current object associated with the specified ProgID, and attaches the IDispatch pointer...

Note that this class obviously works under Windows only.

Availability: only available for the wxMSW port.

##

Library: wxCore
Category: Data Structures

See also
  wxVariant, wxVariantDataCurrency, wxVariantDataErrorCode, wxVariantDataSafeArray

## Public Member Functions
| wxAutomationObject (WXIDISPATCH *dispatchPtr=NULL)
| Constructor, taking an optional `IDispatch` pointer which will be released when the object is deleted. More...
| ~wxAutomationObject ()
| Destructor. More...
wxVariant | CallMethod (const wxString &method, int noArgs, wxVariant args[]) const
| Calls an automation method for this object. More...
wxVariant | CallMethod (const wxString &method,...) const
bool | CreateInstance (const wxString &progId) const
| Creates a new object based on the progID, returning true if the object was successfully created, or false if not. More...
bool | IsOk () const
| Checks if the object is in a valid state. More...
WXIDISPATCH * | GetDispatchPtr () const
| Gets the `IDispatch` pointer. More...
bool | GetInstance (const wxString &progId, int flags=wxAutomationInstance_CreateIfNeeded) const
| Retrieves the current object associated with the specified ProgID, and attaches the `IDispatch` pointer to this object. More...
bool | GetObject (wxAutomationObject &obj, const wxString &property, int noArgs=0, wxVariant args[]=NULL) const
| Retrieves a property from this object, assumed to be a dispatch pointer, and initialises obj with it. More...
wxVariant | GetProperty (const wxString &property, int noArgs, wxVariant args[]) const
| Gets a property value from this object. More...
wxVariant | GetProperty (const wxString &property,...) const
bool | Invoke (const wxString &member, int action, wxVariant &retValue, int noArgs, wxVariant args[], const wxVariant *ptrArgs[]=0) const
| This function is a low-level implementation that allows access to the `IDispatch` Invoke function. More...
bool | PutProperty (const wxString &property, int noArgs, wxVariant args[])
| Puts a property value into this object. More...
bool | PutProperty (const wxString &property,...)
void | SetDispatchPtr (WXIDISPATCH *dispatchPtr)
| Sets the `IDispatch` pointer, does not check if there is already one. More...
WXLCID | GetLCID () const
| Returns the locale identifier used in automation calls. More...
void | SetLCID (WXLCID lcid)
| Sets the locale identifier to be used in automation calls performed by this object. More...
long | GetConvertVariantFlags () const
| Returns the flags used for conversions between wxVariant and OLE `VARIANT`, see wxOleConvertVariantFlags. More...
void | SetConvertVariantFlags (long flags)
| Sets the flags used for conversions between wxVariant and OLE `VARIANT`, see wxOleConvertVariantFlags. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to NULL the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## Additional Inherited Members
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Constructor & Destructor Documentation

## ◆ wxAutomationObject()

wxAutomationObject::wxAutomationObject | ( | WXIDISPATCH * | dispatchPtr = `NULL` | ) |

Constructor, taking an optional `IDispatch` pointer which will be released when the object is deleted.

## ◆ ~wxAutomationObject()

wxAutomationObject::~wxAutomationObject | ( |  | ) |

Destructor.

If the internal `IDispatch` pointer is non-null, it will be released.

## Member Function Documentation

## ◆ CallMethod() [1/2]

wxVariant wxAutomationObject::CallMethod | ( | const wxString & | method,
|  | int | noArgs,
|  | wxVariant | args[]
| ) |  | const

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:

wxVariant res = obj.CallMethod("Sum", wxVariant(1.2), wxVariant(3.4));
wxVariant res = obj.CallMethod("Sum", 1.2, 3.4);
wxVariant
The wxVariant class represents a container for any type.
Definition: variant.h:163

Note that method can contain dot-separated property names, to save the application needing to call GetProperty() several times using several temporary objects. For example:

object.CallMethod("ActiveWorkbook.ActiveSheet.Protect", "MyPassword");

## ◆ CallMethod() [2/2]

wxVariant wxAutomationObject::CallMethod | ( | const wxString & | method,
|  |  | ...
| ) |  | const

## ◆ CreateInstance()

bool wxAutomationObject::CreateInstance | ( | const wxString & | progId | ) | const

Creates a new object based on the progID, returning true if the object was successfully created, or false if not.

See also
  GetInstance()

## ◆ GetConvertVariantFlags()

long wxAutomationObject::GetConvertVariantFlags | ( |  | ) | const

Returns the flags used for conversions between wxVariant and OLE `VARIANT`, see wxOleConvertVariantFlags.

The default value is wxOleConvertVariant_Default for compatibility but it can be changed using SetConvertVariantFlags().

Notice that objects obtained by GetObject() inherit the flags from the one that created them.

Since
  3.0

## ◆ GetDispatchPtr()

WXIDISPATCH* wxAutomationObject::GetDispatchPtr | ( |  | ) | const

Gets the `IDispatch` pointer.

Notice that the return value of this function is an untyped pointer but it can be safely cast to `IDispatch`.

## ◆ GetInstance()

bool wxAutomationObject::GetInstance | ( | const wxString & | progId,
|  | int | flags = `wxAutomationInstance_CreateIfNeeded`
| ) |  | 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 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 Microsoft Excel running. Which object is referenced cannot currently be specified.

Parameters

  progId | COM ProgID, e.g. "Excel.Application"
  flags | The creation flags (this parameters was added in wxWidgets 2.9.2)

See also
  CreateInstance()

## ◆ GetLCID()

WXLCID wxAutomationObject::GetLCID | ( |  | ) | const

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

## ◆ GetObject()

bool wxAutomationObject::GetObject | ( | wxAutomationObject & | obj,
|  | const wxString & | property,
|  | int | noArgs = `0`,
|  | wxVariant | args[] = `NULL`
| ) |  | const

Retrieves a property from this object, assumed to be a dispatch pointer, and initialises 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 also
  GetProperty()

## ◆ GetProperty() [1/2]

wxVariant wxAutomationObject::GetProperty | ( | const wxString & | property,
|  | int | noArgs,
|  | wxVariant | args[]
| ) |  | 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:

wxVariant res = obj.GetProperty("Range", wxVariant("A1"));
wxVariant res = obj.GetProperty("Range", "A1");

Note that property can contain dot-separated property names, to save the application needing to call GetProperty several times using several temporary objects.

See also
  GetObject(), PutProperty()

## ◆ GetProperty() [2/2]

wxVariant wxAutomationObject::GetProperty | ( | const wxString & | property,
|  |  | ...
| ) |  | const

## ◆ Invoke()

bool wxAutomationObject::Invoke | ( | const wxString & | member,
|  | int | action,
|  | wxVariant & | retValue,
|  | int | noArgs,
|  | wxVariant | args[],
|  | const wxVariant * | ptrArgs[] = `0`
| ) |  | 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.

Parameters

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

Returns
  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.

## ◆ IsOk()

bool wxAutomationObject::IsOk | ( |  | ) | 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 also
  GetDispatchPtr()

## ◆ PutProperty() [1/2]

bool wxAutomationObject::PutProperty | ( | const wxString & | property,
|  | int | noArgs,
|  | wxVariant | args[]
| ) |  |

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:

obj.PutProperty("Value", wxVariant(23));
obj.PutProperty("Value", 23);

Note that property can contain dot-separated property names, to save the application needing to call GetProperty() several times using several temporary objects.

## ◆ PutProperty() [2/2]

bool wxAutomationObject::PutProperty | ( | const wxString & | property,
|  |  | ...
| ) |  |

## ◆ SetConvertVariantFlags()

void wxAutomationObject::SetConvertVariantFlags | ( | long | flags | ) |

Sets the flags used for conversions between wxVariant and OLE `VARIANT`, see wxOleConvertVariantFlags.

The default value is wxOleConvertVariant_Default.

Since
  3.0

## ◆ SetDispatchPtr()

void wxAutomationObject::SetDispatchPtr | ( | WXIDISPATCH * | dispatchPtr | ) |

Sets the `IDispatch` pointer, does not check if there is already one.

You may need to cast from `IDispatch*` to `WXIDISPATCH*` when calling this function.

## ◆ SetLCID()

void wxAutomationObject::SetLCID | ( | WXLCID | lcid | ) |

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