Manipulating Objects with Automation
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 Arrays and Object and Member Arrays.
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.
See Also
Tasks
How to: Add OLE Objects to Applications
Reference
Object Property (Visual FoxPro)