Class

# OLEObject

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Used to automate COM servers. Use the `WordApplication</api/windows/wordapplication>`, `ExcelApplication</api/windows/excelapplication>`, and `PowerPointApplication</api/windows/powerpointapplication>` classes to automate Microsoft Office applications. OLE is supported on the Windows platform only.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                       | Type                                        | Read-Only | Shared |
|----------------------------|---------------------------------------------|-----------|--------|
| `Handle<oleobject.handle>` | `Ptr</api/data_types/additional_types/ptr>` |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                   | Parameters                                                                                             | Returns                              | Shared |
|----------------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------|--------|
| `Constructor<oleobject.constructor0>`  | disp As `COM.IDispatch</api/windows/idispatch>`                                                        |                                      |        |
| `Constructor<oleobject.constructor1>`  | objToCopy As OLEObject                                                                                 |                                      |        |
| `Constructor<oleobject.constructor2>`  | programID As `String</api/data_types/string>`                                                          |                                      |        |
| `Constructor<oleobject.constructor3>`  | programID As `String</api/data_types/string>`, newInstance As `Boolean</api/data_types/boolean>`       |                                      |        |
| `Invoke<oleobject.invoke>`             | name As `String</api/data_types/string>`                                                               |                                      |        |
|                                        | name As `String</api/data_types/string>`                                                               | `Variant</api/data_types/variant>`   |        |
|                                        | nameOfFunction As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>` |                                      |        |
|                                        | nameOfFunction As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>` | `Variant</api/data_types/variant>`   |        |
| `TypeName<oleobject.typename>`         |                                                                                                        | `String</api/data_types/string>`     |        |
| `Value<oleobject.value>`               | PropertyName As `String</api/data_types/string>`                                                       | `Variant</api/data_types/variant>`   |        |
| `ValueArray<oleobject.valuearray>`     | name As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`           | `Variant()</api/data_types/variant>` |        |
| `ValueArray2D<oleobject.valuearray2d>` | name As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`           | `Variant()</api/data_types/variant>` |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                       | Parameters                                                                                        | Returns                            |
|--------------------------------------------|---------------------------------------------------------------------------------------------------|------------------------------------|
| `EventTriggered<oleobject.eventtriggered>` | eventName As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>` | `Variant</api/data_types/variant>` |

## Property descriptions

<div id="oleobject.handle">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.Handle

**Handle** As `Ptr</api/data_types/additional_types/ptr>`

> Returns a pointer to the `IDispatch</api/windows/idispatch>` interface that is being used.

## Method descriptions

<div id="oleobject.constructor0">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.Constructor

**Constructor**(disp As `COM.IDispatch</api/windows/idispatch>`)

> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> `Constructors</api/language/constructor>` are special methods called when you create an object with the `New</api/language/new>` keyword and pass in the parameters above.
>
> </div>
>
> Creates an <span class="title-ref">OLEObject</span> based upon the `COM.IDispatch</api/windows/idispatch>` interface passed.

<div id="oleobject.constructor1">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

**Constructor**(objToCopy as OLEObject)

> Creates a copy of the <span class="title-ref">OLEObject</span>.

<div id="oleobject.constructor2">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

**Constructor**(programID as `String</api/data_types/string>`)

> Creates a new <span class="title-ref">OLEObject</span> 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.

<div id="oleobject.constructor3">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

**Constructor**(programID as `String</api/data_types/string>`, newInstance as `Boolean</api/data_types/boolean>`)

> Creates a new <span class="title-ref">OLEObject</span> 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</api/language/true>`) or try to use an existing one if it is running (`False</api/language/false>`).
>
> The following example automates Internet Explorer.
>
> ``` xojo
> 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
> ```

<div id="oleobject.invoke">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.Invoke

**Invoke**(name As `String</api/data_types/string>`)

> Invokes the method *name* of the COM server.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

**Invoke**(name As `String</api/data_types/string>`) As `Variant</api/data_types/variant>`

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

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

**Invoke**(nameOfFunction As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`)

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

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

**Invoke**(nameOfFunction As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`) As `Variant</api/data_types/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.

<div id="oleobject.typename">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.TypeName

**TypeName** As `String</api/data_types/string>`

> Returns a `String</api/data_types/string>` that provides `Variant</api/data_types/variant>` subtype information about the object.

<div id="oleobject.value">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.Value

**Value**(PropertyName As `String</api/data_types/string>`) As `Variant</api/data_types/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.,
>
> ``` xojo
> OLEObject.Value(NameOfProperty As String, params() As Variant) = value
> ```
>
> If the optional parameter ByValue is `True</api/language/true>`, property assignment is by value.

<div id="oleobject.valuearray">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.ValueArray

**ValueArray**(name As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`) As `Variant()</api/data_types/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.

<div id="oleobject.valuearray2d">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.ValueArray2D

**ValueArray2D**(name As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`) As `Variant()</api/data_types/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

<div id="oleobject.eventtriggered">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

OLEObject.EventTriggered

**EventTriggered**(eventName As `String</api/data_types/string>`, parameters() As `Variant</api/data_types/variant>`) As `Variant</api/data_types/variant>`

> Occurs when the <span class="title-ref">OLEObject</span> 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</api/data_types/variant>`.

## Notes

By default, <span class="title-ref">OLEObject</span> 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</api/language/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</api/data_types/string>` to preserve precision.

Since <span class="title-ref">OLEObject</span> uses `Operator Lookup</api/language/operators/operator_overloads/operator_lookup>`, you can also use dot notation to access OLEProperties.

## Sample code

The following code automates Internet Explorer.

``` xojo
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 <span class="title-ref">OLEObject</span> class supports setting indexed properties. For example the Word.Document.Compatibility property is an indexed property. Here is an example.

``` xojo
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 <span class="title-ref">OLEObject</span> using the copy constructor and opens a new Word document.

``` xojo
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.

``` xojo
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</api/deprecated/movieplayer>` CurrentPosition using both dot notation and function calls:

``` xojo
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:

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

## Compatibility

|                       |                       |
|-----------------------|-----------------------|
| **Project Types**     | Console, Desktop, Web |
| **Operating Systems** | Windows               |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `ExcelApplication</api/windows/excelapplication>`, `Office</api/windows/office>`, `DesktopXAMLContainer</api/user_interface/desktop/desktopxamlcontainer>`, `OLEParameter</api/windows/oleparameter>`, `PowerPointApplication</api/windows/powerpointapplication>`, `WordApplication</api/windows/wordapplication>` classes; `OLEException</api/exceptions/oleexception>` error.

</div>