Creating a Reference to an Object

See Also

Before you can use an object's properties, methods, and events in your application, you must declare an object variable, then assign an object reference to the variable. How you assign an object reference depends on two factors:

Whether the ActiveX component supplies a type library. An ActiveX component's type library contains definitions of all the objects the component provides, including definitions for all available methods, properties, and events. If an ActiveX component provides a type library, you need to add a reference to the type library in your Visual Basic project before you can use the library's objects.
Whether the object is a top-level, externally creatable object, or a dependent object. You can assign a reference to an externally created object directly, while references to dependent objects are assigned indirectly.

If an object is externally creatable, you can assign an object reference to a variable by using the New keyword, CreateObject, or GetObject in a Set statement from outside the component. If the object is a dependent object, you assign an object reference by using a method of a higher-level object in a Set statement.

In Microsoft Excel, for example, an Application object is an externally creatable object — you can assign a reference to it directly from your Visual Basic application by using the New keyword, CreateObject, or GetObject in a Set statement. A Range object, by contrast, is a dependent object — you assign a reference to it by using the Cells method of a Worksheet object in a Set statement. For more information on externally creatable and dependent objects, see "Navigating Object Models" later in this chapter.

If the object's class is included in a type library, you can make your application run faster by creating an object reference using a variable of that specific class. Otherwise, you must use a variable of the generic Object class, which results in late binding. For more information, see "Speeding Object References."

To create a reference to an object defined in a type library

From the Project menu, choose References.
In the References dialog box, select the name of the ActiveX component containing the objects you want to use in your application.
You can use the Browse button to search for the type library file containing the object you need. Type libraries can have a .tlb or .olb file-name extension. Executable (.exe) files and dynamic link libraries (dlls) can also supply type libraries, so you can also search for files with these file-name extensions.
If you are not sure if an application is ActiveX-enabled and supplies a type library, try adding a reference to it using the Browse button. If the reference fails, Visual Basic displays the error message, "Can't add a reference to the specified file," indicating that the type library doesn't exist. For more information about working with objects that aren't associated with a type library, see "Creating a Reference to an Object."
From the View menu, choose Object Browser to view the referenced type library. Select the appropriate type library from the Project/Library list. You can use all the objects, methods, and properties listed in the Object Browser in your application.
For more information See "Browsing ActiveX Component Type Libraries."
Declare an object variable of the object's class. For example, you could declare a variable of the class Excel.Chart to refer to a Microsoft Excel Chart object.
```
Dim xlChart As Excel.Chart
```
For more information See "Declaring an Object Variable" later in this chapter.
Assign an object reference to the variable by using the New keyword, CreateObject, or GetObject in a Set statement. For more information, see "Assigning an Object Reference to a Variable" later in this chapter.
If the object is a dependent object, assign an object reference by using a method of a higher-level object in a Set statement.

To create a reference to an object not defined in a type library

Declare an object variable of the Object data type.
Because the object isn't associated with a type library, you won't be able to use the Object Browser to view the properties, methods, and events of the object. You need to know what properties, methods, and events the object provides, including any methods for creating a reference to a dependent object.
For more information See "Declaring an Object Variable" later in this chapter.
Assign an object reference to the variable by using CreateObject or GetObject in a Set statement. For more information, see "Assigning an Object Reference to a Variable" later in this chapter.
If the object is a dependent object, assign an object reference by using a method of a higher-level object in a Set statement.

Ambiguous References and Reference Priority

When you refer to a constant or object in code, Visual Basic searches for the constant or object class in each type library selected in the References dialog box in the order the type libraries are displayed. If two type libraries contain constants or classes with identical names, Visual Basic uses the definition provided by the type library listed higher in the Available References box.

Figure 10.1 The References dialog box

The best way to handle potentially ambiguous references is to explicitly specify the type library that supplies the constant or class when you use it. For example, the constant vbCancel evaluates to different values in the Visual Basic and Visual Basic for Applications type libraries. The following code shows fully qualified and ambiguous references to the constant vbCancel:

' Print the Visual Basic vbCancel.
Debug.Print "VB.vbCancel = "; VB.vbCancel
' Print the Visual Basic for Applications vbCancel.
Debug.Print "VBA.vbCancel = "; VBA.vbCancel
' Ambiguous reference prints the value of vbCancel
' that appears highest in the type library highest
' in the Available References list.
Debug.Print "vbCancel = "; vbCancel

The following code example shows fully qualified and ambiguous declarations for an Application object variable. If Microsoft Word appears higher in the Available References box than Microsoft Excel, xlApp2 is declared using the Microsoft Word Application class rather than the Microsoft Excel Application class.

' Fully qualified object variable declaration.
Dim xlApp1 As Excel.Application
' Ambiguous object variable declaration.
Dim xlApp2 As Application

' Assign an object reference.
Set xlApp1 = New Excel.Application
' The following generates a type mismatch error.
Set xlApp2 = xlApp1

You may be tempted to handle potentially ambiguous references by changing the order in which Visual Basic searches for references. The References dialog box includes two Priority buttons that let you move a type library higher in the list, so that its constants and classes will be found sooner than constants or classes with identical names lower on the list. However, changing the priority order can cause unexpected problems in your applications if there are other ambiguous references. In general, it's better to explicitly specify the type library in any references.

Note The Excel.Application syntax for referring to the Microsoft Excel Application class is not supported in versions prior to Microsoft Excel 97. To refer to the Microsoft Excel Application class in Microsoft Excel 5.0 and Microsoft Excel 95, use the syntax [_ExcelApplication] instead. For example:

Set xlApp = New [_ExcelApplication]