Manipulation of Objects with Automation

Article
10/23/2006

OLE objects in your forms or programs, or ActiveX controls inside OLE Container controls, can be manipulated through code in the same way that you can program native Visual FoxPro objects.

Manipulating Extrinsic Object Properties

In code, you can manipulate an object using its properties. The way you reference a property depends on whether the object stands alone or is part of a container, such as the OLE Container control or OLE Bound control.

Note ActiveX controls are always part of an OLE Container control.

An object in a container has two parts: the object itself and a container around the object. Both the object and the container have properties, and sometimes they have the same property names. To ensure you reference the object's properties, always append the container's Object property to the object's name. For example, the following code refers to the object's Left property:

frm1.olecontrol1.Object.Left = 25  && Object's Left

If you omit the Object property, you reference the container's Left property instead:

frm1.olecontrol1.Left= 25  && Container's Left property

For example, suppose you have an application that sends mail when the user clicks on a compose command button. If you've added a Microsoft MAPI message control to a form as olecontrol1, the code associated with the Click event of the command button might be:

THISFORM.olecontrol1.Object.Compose
THISFORM.olecontrol1.Object.Send(.T.)

In addition to using the Object property to reference properties of the contained object, you can use other properties of the container control. For example, you can reference the read-only OLEClass property to identify the type of object in the container and the Sizable property to prevent users from changing the size of an object. For details about container control properties, see OLE Container Control.

In the Form and Class Designers, the properties of ActiveX controls are displayed in the Visual FoxPro Properties window, but most ActiveX controls also have their own interface for setting common properties. You can see this properties interface by selecting the object-specific Properties option from the ActiveX control's shortcut menu. For example, to open the Properties dialog box for a rich text control, choose Microsoft RichText Control Properties from the shortcut menu.

Using Extrinsic Object Methods

In addition to setting and retrieving properties of objects, you can manipulate an object using methods it supports. For example, you can use the Add method of a Microsoft Excel collection object to create a new Microsoft Excel workbook.

The following Automation example uses the Add method to create an Excel workbook, the Save method to save the workbook, and the Quit method to end Excel:

Code	Comments
`oleApp = CREATEOBJECT("Excel.Application")`	Start Excel.
`OleApp.Visible=.T.`	Display Excel.
`OleApp.Workbooks.Add`	Create a workbook.
`OleApp.Cells(1,1).Value=7`	Set a cell's value.
`OleApp.ActiveWorkbook.SaveAs("C:\TEMP.XLS")`	Save the workbook.
`OleApp.Quit`	Quit Excel.

If you create an object using the OLE Container control or OLE Bound control, you can use the DoVerb method of the control to execute a verb on the object. For example, use DoVerb(0) to execute the default verb, DoVerb(– 1) to activate the object for visual editing, and DoVerb(– 2) to open the object in a separate window.

Note See an application's documentation to determine what Automation commands it supports. For example, Microsoft Excel add-in components are not available for Automation.

Setting Time Outs

When you pass a request to an OLE object, the Automation server processes it. You don't have much control over the server processing, but you can specify how long you'll wait for a process to finish by setting the OLERequestPendingTimeout and OLEServerBusyTimeout properties. You can determine what happens when that time has expired by setting the OLEServerBusyRaiseError property.

Accessing Collections of Objects

An object type can represent a single object or a collection of related objects. For example, a Microsoft Excel Workbook object represents a single workbook, whereas the Workbooks object represents all the workbooks currently loaded. Because the Workbooks object represents a collection of objects, it's called a collection object.

In code, a collection is an unordered list in which the position of an object can change whenever objects are added to or removed from the collection. You access an object in a collection by iterating through the collection, using the Count property of the collection. The Count property returns the number of items in the collection. You can also use the Item method to return an item in a collection.

For example, to display the names of worksheets in a Microsoft Excel workbook, use the following code:

oleApp = CREATEOBJECT("Excel.Application")
oleApp.Workbooks.Add
FOR EACH x IN oleApp.Workbooks
 ? x.Name
ENDFOR

You can also access a collection within a collection. For example, you can access a cells collection within a range using the following code:

oleApp = CREATEOBJECT("Excel.sheet")
oleApp.Workbooks.Add
oleApp.Range(oleApp.Cells(1,1),oleApp.Cells(10,10)).Value=100
oleApp.Visible=.T.

Using Arrays of Objects

You can pass arrays to methods, and you can receive arrays back. However, you must pass arrays by reference by prefixing the array name with the @ sign.

For example, to send a Visual FoxPro array to Microsoft Excel, consider the following code. It creates an array in Visual FoxPro, assigns the array some values, starts Microsoft Excel, creates a workbook, sets a value to the first cell of a worksheet, and then copies that value to the other sheets in the array:

DIMENSION aV(3)
aV(1) = "Sheet1"
aV(2) = "Sheet2"
aV(3) = "Sheet3"
oleApp=CREATEOBJECT("Excel.Application")
oleApp.Workbooks.Add
oleI=oleApp.Workbooks.Item(1)
oleI.Sheets.Item(1).Cells(1,1).Value = 83
oleI.Sheets(@aV).;
 FillAcrossSheets(oleI.Worksheets("Sheet1").Cells(1,1))

oleApp.Visible = .T.

Alternatively, the following example returns an array to Visual FoxPro and then displays the contents of the array:

oleApp = CREATEOBJECT("Excel.Application")
aOleArray = oleApp.GetCustomListContents(3)
FOR nIndex = 1 to ALEN(aOleArray)
   ? aOleArray(nIndex)
ENDFOR

Note With Visual FoxPro, you cannot pass arrays larger than two dimensions to OLE objects. For more information about working with arrays in Visual FoxPro, see Object-Oriented Programming and Overview of the Language.

Releasing Extrinsic Objects

An Automation server is automatically released if it is not visible and no variables in scope reference the object. You can use the RELEASE command to release the variable associated with an object. If the server is visible, use the Quit method to release it.

Share via