Class

OLEObject

Description

Used to automate COM servers. Use the WordApplication, ExcelApplication, and PowerPointApplication classes to automate Microsoft Office applications. OLE is supported on the Windows platform only.

Properties

Name

Type

Read-Only

Shared

Handle

Ptr

Methods

Name

Parameters

Returns

Shared

Constructor

disp As COM.IDispatch

Constructor

objToCopy As OLEObject

Constructor

programID As String

Constructor

programID As String, newInstance As Boolean

Invoke

name As String

name As String

Variant

nameOfFunction As String, parameters() As Variant

nameOfFunction As String, parameters() As Variant

Variant

TypeName

String

Value

PropertyName As String

Variant

ValueArray

name As String, parameters() As Variant

Variant()

ValueArray2D

name As String, parameters() As Variant

Variant()

Events

Name

Parameters

Returns

EventTriggered

eventName As String, parameters() As Variant

Variant

Property descriptions

OLEObject.Handle

Handle As Ptr

Returns a pointer to the IDispatch interface that is being used.

Method descriptions

OLEObject.Constructor

Constructor(disp As COM.IDispatch)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates an OLEObject based upon the COM.IDispatch interface passed.

Constructor(objToCopy as OLEObject)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a copy of the OLEObject.

Constructor(programID as String)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new OLEObject using the passed programID is the COM server's program ID as stored in the registry. It can also be the Class ID (in curly braces). This constructor will try to find a previous instance of the COM server if it is running. Otherwise, it will create a new instance.

Constructor(programID as String, newInstance as Boolean)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates a new OLEObject using the passed ProgramID is the COM server's program ID as stored in the registry. The NewInstance parameter specifies whether to create a new instance of the COM server (True) or try to use an existing one if it is running (False).

The following example automates Internet Explorer.

Try
  Var obj As OLEObject
  Var v As Variant
  Var params(1) As Variant

  obj = New OLEObject("InternetExplorer.Application", True)
  obj.Value("Visible") = True
  params(1) = "https://www.xojo.com"
  v = obj.Invoke("Navigate", params)
Catch err As OLEException
  MessageBox(err.Message)
End Try

OLEObject.Invoke

Invoke(name As String)

Invokes the method name of the COM server.

Invoke(name As String) As Variant

Invokes the method name of the COM server. The value returned is the value returned by the function invoked.

Invoke(nameOfFunction As String, parameters() As Variant)

Invokes the method nameOfFunction of the COM server, and passes the array of parameters to the method.

Invoke(nameOfFunction As String, parameters() As Variant) As Variant

Invokes the method nameOfFunction of the COM server, and passes the array of parameters to the method. The value returned is the value returned by the function invoked.

Make sure to correctly dimension the array, as this will determine the number of parameters that get passed to the method. The first parameter begins at 1.

OLEObject.TypeName

TypeName As String

Returns a String that provides Variant subtype information about the object.

OLEObject.Value

Value(PropertyName As String) As Variant

Used to get or set a value of the object.

The parameter PropertyName is the name of the property to assign a new value to or to get the value. The value property can optionally take a list of properties when assigning a value, i.e.,

OLEObject.Value(NameOfProperty As String, params() As Variant) = value

If the optional parameter ByValue is True, property assignment is by value.

OLEObject.ValueArray

ValueArray(name As String, parameters() As Variant) As Variant()

Used to get or set a value of the object.

The Name parameter is the name of the property to assign a new value to or to get the value. ValueArray can accept a list of parameters to pass to the automation object. The parameters array is assumed to be 1-based.

OLEObject.ValueArray2D

ValueArray2D(name As String, parameters() As Variant) As Variant()

Used to get or set a value of the object for two-dimensional arrays.

The Name parameter is the name of the property to assign a new value to or to get the value. ValueArray2D can accept a list of parameters to pass to the automation object. The Parameters array is assumed to be 1-based.

Event descriptions

OLEObject.EventTriggered

EventTriggered(eventName As String, parameters() As Variant) As Variant

Occurs when the OLEObject receives an event from the automation server. The event name is passed as the first parameter and the parameters for the event are passed as an array of variants.

Notes

By default, OLEObject will make the property assignment by value. If it encounters an error it will try by reference if the property is an object. If the optional ByValue parameter is True, the property assignment is by value (i.e., a copy); otherwise the assignment is by reference (i.e., a pointer copy). In Visual Basic, an assignment by reference is done using the Set command, but since Xojo doesn't provide that feature, you will need to use the ByValue parameter when you know the assignment should be by reference.

Currency types are treated as String to preserve precision.

Since OLEObject uses Operator Lookup, you can also use dot notation to access OLEProperties.

Sample code

The following code automates Internet Explorer.

Try
  Var obj As OLEObject
  Var v As Variant
  Var params(1) As Variant

  obj = New OLEObject("InternetExplorer.Application", True)
  obj.Value("Visible") = True
  params(1) = "http://www.wikipedia.org/"
  v = obj.invoke("Navigate", params)
Catch err As OLEException
  MessageBox(err.Message)
End Try

The OLEObject class supports setting indexed properties. For example the Word.Document.Compatibility property is an indexed property. Here is an example.

Var word As New OLEObject("Word.Application")
Var doc As OLEObject

word.Visible = True
doc = word.Documents.Add

Var params(1) As Variant
params(1) = Office.wdNoTabHangIndent

doc.Value("Compatibility", params) = True
' or
' doc.Compatibility(Office.wdNoTabHangIndent)=True

The following code creates a copy of the passed OLEObject using the copy constructor and opens a new Word document.

Var word As New OLEObject("word.Application")
Var wordCopy As OLEObject
wordCopy = New OLEObject(word)
wordCopy.Visible = True
wordCopy.Documents.Add

This code automates Microsoft Word.

Try
  Var obj As OLEObject
  Var docs As OLEObject
  Var doc As OLEObject
  Var range As OLEObject
  Var v As Variant

  obj = New OLEObject("Word.Application", True)

  ' make it visible
  obj.Value("Visible") = True

  v = obj.Value("Documents")
  If v.ObjectValue IsA OLEObject Then
    docs = OLEObject(v.ObjectValue)
    v = docs.Invoke("Add")
    If v.ObjectValue IsA OLEObject Then
      doc = OLEObject(v.ObjectValue)
      v = doc.Invoke("Range")
      If v.ObjectValue IsA OLEObject Then
        range = OLEObject(v.ObjectValue)
        range.Value("Text") = "This is a sentence."
      End If
    End If
  End If
Catch err As OLEException
  MessageBox(err.Message)
End try

This code shows how to get the MoviePlayer CurrentPosition using both dot notation and function calls:

Var o As OLEObject = MoviePlayer1.MovieController
Var v As Variant = o.Value("Controls")
If v IsA OLEObject Then
  Var pos As Double = OLEObject(v).Value("CurrentPosition")
End If

And with dot notation:

Try
  Var pos As Double = MoviePlayer1.MovieController.Controls.CurrentPosition
Catch e As OLEException
  MessageBox("OLE access error.")
End Try

Compatibility

Desktop projects on the Windows operating system.