Language elements of SoftMaker Basic

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

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

tm.Documents.Close ' Close all documents

Set tm = Nothing ' Cut the connection to TextMaker

End Sub