Chapter 6

See Graphic

OLE Automation





OLE Automation

PerfectScript can send commands to Corel WordPerfect, Corel Presentations and Corel Quattro Pro. Through a Windows standard interface known as OLE Automation, PerfectScript can also send commands to programs such as Microsoft Excel and Microsoft Word. These programs are called OLE Automation servers. PerfectScript is an OLE Automation controller. OLE Automation is not limited to these programs. PerfectScript can send commands and control any OLE Automation server.

OLE Automation servers define objects. These objects have names that are registered with Windows (refer to a program’s documentation for the names of objects they define).

OLE objects can have methods and properties. A method is a command or function that performs an action on that object. A property is a value that the object has (like system variables in Corel WordPerfect). This value can be retrieved and set. An example of a method for the "Excel.Application" object follows: 

Worksheets ().Activate

A property of the "Excel.Application" object follows: 

ActiveSheet.Name

Methods, like product commands, may require parameters, and may or may not return values. Unlike system variables in Corel WordPerfect, properties can be set by placing the property name on the left-hand side of an assignment statement. Properties can also take parameters when being retrieved or when being set. This makes the retrieval of a property very similar to a method call.

Object Support

Support for OLE Automation objects is provided through the following commands:

Before using an OLE object in PerfectScript, the Object statement must be used. The Object statement is similar to the Application statement for products. This statement defines an object prefix variable that is used to call methods, and to retrieve and set object properties. The name of the object is also specified, along with whether this prefix is to be used as the default object for non-prefixed method calls and properties.

The object prefix variable specified in the Object statement identifies a variable that will contain an instance handle to the object at run time. As a variable, it can be used in many places where other macro variables can be used, but not all. For example, the macro language operators "+" and "-" cannot be used with object variables, and automatic type conversions are not defined for object variables. Object variables can be assigned to other object variables of the same type, and they can be passed as parameters to user-defined macro routines.

As with other macro variables, object variables exist at run time in a specific macro variable pool. Specify this pool with Declare, Local, Global and Persist statements. If the object variable is not specified, it exists in the local variable pool (unless PersistAll is in effect, and then the object variable exists in the persistent variable pool).

Before making a call to an object’s methods, and before an object’s properties can be retrieved or set, an instance handle to a specific object must be obtained through the CreateObject or GetObject statement. These statements return an instance handle to a specific instance of an object. Because many OLE Automation servers support multiple instances of the objects they define, an instance handle to a specific object must be obtained to distinguish instances of the same object. Multiple object variables can be created, and multiple instances can be obtained if the OLE Automation server supports multiple instances.

After getting an instance handle, an object variable is said to be connected to the OLE Automation server. Like other variables, the Exists statement can be used on object variables to find out if an object variable exists, and which variable pool it exists in. Even though an object variable exists, it may not be currently connected to the OLE Automation server. This information may be obtained from the ObjectInfo command.

When an instance of an OLE object is no longer needed, the connection can be terminated with the Discard statement. Like other variables, OLE object variables are automatically discarded when the macro terminates, or when the user-defined routine ends in which the variable is defined. If connected, this automatically disconnects the object from an OLE Automation server.

After an object is connected to its OLE Automation server, the methods and properties of that object can be accessed. This is done by prefixing the method or property name with the OLE object prefix variable name and a ".". If the OLE object variable is the default object variable (specified by Default! in the Object statement, or specified in a With statement), the object prefix variable can be omitted. It is replaced by two leading periods (".."). Leading periods are necessary to inform the macro compiler that the method name being called is not the name of a user-defined macro routine, but the method name (or property) of the current default OLE object.

To establish a new default object for a localized block of code, use the With/EndWith compound statement. The object prefix variable is specified in the With statement, and all statements to access methods, and properties preceded by ".." until the EndWith statement are assumed to be references to that object.

The NewDefault statement can be used to establish a new default object variable prefix for the remainder of the macro (or until the macro encounters another NewDefault statement).

PerfectScript Macro Example 

Object (Doc; "SomeObject.Document")
Object (Ss; "SomeOtherObject.SpreadSheet"; Default!)

Doc := CreateObject (SomeObject.Document")
If (not Exists (Ss))
	Ss := GetObject ("SomeOtherObject.SpreadSheet")
EndIf
RecalculateCells ()
..SelectCell ("A1")

Doc.MarginTop := 1.5"
With (Doc)
	Doc.MarginBottom := 2.0"
	..MarginLeft := 1.5"
	..MarginRight := 0.5"
	..Type ("First line")
	Ss.SelectCell ("A12")
	With (Ss)
		..Copy ()
		Doc.Paste ()
	EndWith
	a := ..MarginLeft
	Prompt ("The first line has been entered")
	Pause
EndWith

Discard (Doc)
Quit