<< Click to Display Table of Contents >> OLE Automation |
With help from OLE Automation, suitable applications (such as TextMaker or PlanMaker) can be controlled from SoftMaker Basic scripts.
Tip: Detailed information on programming TextMaker and PlanMaker can be found in the chapters BasicMaker and TextMaker and BasicMaker and PlanMaker, respectively.
What is an OLE Automation object?
Every OLE Automation-capable program provides specific objects for scripting the application. The type of these objects depends on the application. A word processor like TextMaker provides objects which, for example, show the number of currently open documents or the formatting of the currently selected text.
OLE Automation objects offers two ways of access:
▪The properties of OLE Automation objects are values that can be read and/or written and describe a certain characteristic of an object. A document window of a word processor has for example the following properties: name (of the opened document), width and height of the window, etc.
▪Methods are functions that trigger an action in an OLE Automation object. An open document has for example a method to save it to disk.
Accessing OLE Automation objects
To access an OLE Automation object, you first must declare a variable of the type Object.
Example:
Dim MyObj As Object
This must then be "connected" to the application. There are two functions for this: While CreateObject starts the application automatically if it is not already running, GetObject can only connect to an instance of an application that is already running.
Example:
Set MyObj = CreateObject("TextMaker.Application")
The variable MyObj now contains a reference to the main OLE Automation object of the application and incidentally its name is always Application. You can access its child objects through dot notation – for example MyObj.Application.Documents (see also the next section).
If the OLE Automation connection is no longer needed, the variable should be separated from the object by setting its value to Nothing:
Example:
Set MyObj = Nothing ' Detach variable from object
Properties
To access the properties of an object, use dot notation in the style Object.Property.
Example:
x = MyObj.Application.Width ' Retrieve the width of the program window
Or:
MyObj.Application.Width = 5 ' Set the width of the program window
Methods
When calling methods, dot notation is also used: Object.Method
Example:
MyObj.Application.Quit ' Exit from the application
Using collections
Apart from simple objects, there are also collections of objects.
TextMaker, for example, offers the collection Documents (a collection of all open documents). A collection is itself an object that is usually accessible through a property of its parent object.
You can use the For Each Next statement to enumerate all elements of a collection.
All collections offer the following properties and methods by default:
Count | Returns the number of elements (read-only). |
Item(i) | Provides the i-th element. |
Add | Adds a new object to the collection. |
Example
Let us conclude with an example that demonstrates the use of OLE Automation in practice. The example uses TextMaker's Documents collection which represents all currently open documents. In the first step, it is determined how many documents are currently open. Then the names of the opened documents are output. Finally, the documents are closed.
Tip: Detailed information on the subjects BasicMaker and TextMaker and BasicMaker and PlanMaker can be found in their respective chapters.
Sub Main
Dim tm As Object
Set tm = CreateObject("TextMaker.Application")
tm.Visible = True ' Make TextMaker visible
tm.Activate ' Bring TextMaker to the foreground
tm.Documents.Add ' Create three new documents
tm.Documents.Add
tm.Documents.Add
Print tm.Documents.Count & " open documents"
Dim x As Object
For Each x in tm.Documents
Print x.Name ' Output the names of the documents
Next
tm.Documents.Close ' Close all documents
Set tm = Nothing ' Cut the connection to TextMaker
End Sub