wxRuby Documentation Home

# Wx::AutomationObject

The AutomationObject 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 Variant 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.

AutomationObject excelObject; if (excelObject.GetInstance(“Excel.Application”)) excelObject.PutProperty(“ActiveCell.Font.Bold”, true);

Note that this class obviously works under Windows only.

## Derived from

Object

## See also

Variant

## Methods

- AutomationObject.new
- AutomationObject#call_method
- AutomationObject#create_instance
- AutomationObject#get_dispatch_ptr
- AutomationObject#get_instance
- AutomationObject#get_object
- AutomationObject#get_property
- AutomationObject#invoke
- AutomationObject#put_property
- AutomationObject#set_dispatch_ptr

### AutomationObject.new

AutomationObject.new(%(arg-type)IDISPATCH% dispatchPtr = nil)

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

destructor()

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

### AutomationObject#call_method

Variant call_method(%(arg-type)String% method, Integer noArgs, Variant args[]) Variant call_method(%(arg-type)String% method, … )

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:

Variant res = obj.CallMethod(“Sum”, Variant(1.2), Variant(3.4)); Variant res = obj.CallMethod(“Sum”, 1.2, 3.4);

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(“ActiveCell.Font.ShowDialog”, “My caption”);

### AutomationObject#create_instance

Boolean create_instance(%(arg-type)String% classId)

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

### AutomationObject#get_dispatch_ptr

IDispatch get_dispatch_ptr()

Gets the IDispatch pointer.

### AutomationObject#get_instance

Boolean get_instance(%(arg-type)String% classId)

Retrieves the current object associated with a class id, and attaches the IDispatch pointer
to this object. 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.

### AutomationObject#get_object

Boolean get_object(%(arg-type)AutomationObject% obj String property, Integer noArgs = 0, Variant args[] = nil)

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 AutomationObject#get_property when retrieving objects
from other objects.

Note that an IDispatch pointer is stored as a void* pointer in Variant objects.

#### See also

AutomationObject#get_property

### AutomationObject#get_property

Variant get_property(%(arg-type)String% property, Integer noArgs, Variant args[]) Variant get_property(%(arg-type)String% property, … )

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:

Variant res = obj.GetProperty(“Range”, Variant(“A1”)); Variant 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.

### AutomationObject#invoke

Boolean invoke(%(arg-type)String% member, Integer action, Variant retValue, Integer noArgs, Variant args[], Variant ptrArgs[] = 0)

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

#### Return value

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.

### AutomationObject#put_property

Boolean put_property(%(arg-type)String% property, Integer noArgs, Variant args[]) Boolean put_property(%(arg-type)String% property, … )

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”, Variant(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.

### AutomationObject#set_dispatch_ptr

set_dispatch_ptr(%(arg-type)IDISPATCH% dispatchPtr)

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.

[This page automatically generated from the Textile source at 2023-06-09 00:45:31 +0000]