Visual Basic Concepts

Using the Global Object in TestThing

TestThing will call the ShowDialog method to display a modal dialog in its Form_Load event procedure, as the application is starting. It will also show a modeless dialog when the main form is clicked.

Note   This topic is part of a series that walks you through creating a sample ActiveX DLL. It begins with the topic Creating an ActiveX DLL.

To add code to call the ShowDialog method

1. In the Project Explorer window, click Form1 to select it, then press F7 — or click the Code button on the Project Explorer window toolbar — to open the code window for the form. Place the following code in the Form_Load event.

   Sub Form_Load()
      Me.Caption = ShowDialog(Me.Caption)
   End Sub
   

   Notice that no object variable is declared, and that the ShowDialog method is called as if it were an ordinary function procedure. This is possible because the Dialogs object’s Instancing property is set to GlobalMultiUse.

2. In the Declarations section, add the following code:

   Private WithEvents mdgs As Dialogs
   

   The variable is declared WithEvents, so that Form1 can handle the NotifyClients events raised by the Dialogs object.

3. In the Object box, select mdgs to show the event procedure. Add the following code:

   Private Sub mdgs_NotifyClients(Byval Data As String)
      Me.Caption = Data
   End Sub
   

   Whenever the NotifyClients event is received, Form1 assigns the data to its caption property. The modeless dialog box thus controls the form’s caption.

4. To show the modeless dialog and start event handling, add the following code to the Form_Click event procedure:

   Private Sub Form_Click()
      If mdgs Is Nothing Then
         Set mdgs = New Dialogs
      End If
      mdgs.ShowDialog Me.Caption, False
   End Sub
   

   Important   The Dialogs object created here is not the global instance used to show the modal dialog in the Load event. The global instance will be created automatically when the ShowDialog method is invoked in Form_Load, and will be used for any subsequent method invocations that omit the object variable. The instance used to show the modeless dialog box is explicitly created and assigned to the WithEvents variable, so its NotifyClients event can be handled.

Okay! The Dialogs object creates and manipulates a dlgForm object, and receives its NotifyClients event. Form1 creates two different Dialogs objects, one implicitly (the global instance used to show the modal dialog) and one explicitly (used to show the modeless dialog).

The modeless dialog communicates with the Dialogs object by raising a NotifyClients event. The Dialogs object responds by raising its own NotifyClients event, which Form1 handles by assigning the data to its Caption property. Time to see if it all works!

To see if it all works

1. Press CTRL+F5 to run the project group. The first thing you’ll see is the dialog box, containing the caption of Form1:

   

2. Enter a new caption, and close the dialog box. The main form appears, showing its new caption.

3. Click on the main form to create another Dialogs object, which will show a modeless dialog box containing the current caption of the main form. Enter another caption, and observe that with each keystroke the main form’s caption changes:

   

   Each change to the contents of the text box raises a NotifyClients event from dlgDemo to the Dialogs object. The Dialogs object then raises its own NotifyClients event, which the main form receives.

You may find it instructive to run the project again, pressing F8 this time to step through the code one line at a time. You can clearly see that two different Dialogs objects are involved, because you’ll step through their separate Initialize events.

Among the interesting things you’ll notice is that the modal dialog box raises NotifyClients events, just as the modeless dialog box does. Form1 doesn’t have a WithEvents variable containing a reference to the global Dialogs object, so it’s unable to handle these events.

Important   The "global" in "global object" simply means that the methods and properties of the object added to the global name space of your project, so that they can be used without first declaring an object variable. It does not mean that there is only one such object, or that multiple client applications can share a single object. An instance of the class will be created for each client that uses methods of the class without qualifying them. Only one such global object will be created for each client.

Client Support for Modeless Forms

The display of modeless forms from in-process components requires communication with the client’s message loop. Not all clients support this. For an explanation of this limitation, see "Displaying Forms from Code Components," in "Building Code Components."

For More Information   Global objects are discussed in "Instancing for Classes Provided by ActiveX Components" in "General Principles of Component Design," and in "Building Code Components."

Step by Step

This topic is part of a series that walks you through creating a sample ActiveX DLL.