Adding a Form to the ThingDemo Project

See Also

In-process components can serve as libraries of procedures and dialog boxes, saving you programming time and giving your applications a consistent look and feel.

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.

The procedures in this topic demonstrate the way objects can be used to control modal or modeless dialog boxes. The same form is used for both cases, as shown in Figure 2.3.

Figure 2.3 The dlgDemo dialog box

To add a form to the ThingDemo project

In the Project Explorer window, click ThingDemo to make it the active project.
Important Whenever you’re working with a project group, make sure the right project is active before adding a new module.
On the Project menu, click Add Form to open the Add Form dialog box. Double-click the Form icon to add a form.

Design the form as you would any Visual Basic form, and save it as ThingDemo_dlgDemo.frm. The following table lists property settings for the objects in the form.

Object	Property	Setting
Form	Name BorderStyle Caption	dlgDemo Fixed Dialog Dialog Box
TextBox	Name Text	txtDemo (Empty)

The dialog box is not invoked directly from the client, because forms are private classes. Clients cannot create instances of private classes, and you should never pass instances of private classes to client applications. This is discussed in "Data Types Used in Properties and Methods" in "General Principles of Component Design."

To display the dialog box, clients will call the ShowDialog method of a global Dialogs object, which will create and show the dlgDemo form.

To add code to the dlgDemo form

Double-click on dlgDemo to open its code window, and add the following code.
```
' Declare an event.
Event NotifyClients(ByVal Data As String)
```
Add the following code to the Change event of the text box. When the contents of the text box change, the NotifyClients event is raised with the new contents as its argument.
```
Private Sub txtDemo_Change()
   RaiseEvent NotifyClients(txtDemo.Text)
End Sub
```

To prevent the dialog box from being closed without the knowledge of the Dialogs object, place the following code in the QueryUnload event procedure.

Private Sub Form_QueryUnload(Cancel As Integer, _
      UnloadMode As Integer)
   ' If the Close button was pressed, hide the 
   '   dialog box instead of unloading it.
   If UnloadMode = vbFormControlMenu Then
      Cancel = True
      Me.Visible = False
   End If
End Sub

If dlgDemo is shown as a modal dialog, hiding the dialog rather than unloading it allows the ShowDialog method of the Dialogs class to retrieve the value in the text box.

To create the Dialogs class

From the Project menu, choose Add Class Module to open the Add Class Module dialog box. Double-click the Blank Class Module icon to add a class module to the project.
In the Properties window, change the Name property of the class to Dialogs.
In the Properties window, change the Instancing property to GlobalMultiUse, so that you can call the ShowDialog method without explicitly creating a Dialogs object.
To create a WithEvents variable that can handle the NotifyClients event of dlgDemo, and to create an event that Dialogs object can raise for its own clients, add the following code to the Declarations section:
```
Private WithEvents mdlg As dlgDemo
Event NotifyClients(ByVal Data As String)
```
In the Object box, select mdlg to show the event procedure for the NotifyClients event raised by dlgDemo. Add the following code:
```
Private Sub mdlg_NotifyClients(ByVal Data As String)
   RaiseEvent NotifyClients(Data)
End Sub
```
The Dialogs object receives the NotifyClients event from its dlgDemo form whenever the contents of the dialog’s text box changes. The Dialogs object immediately raises its own NotifyClients event, passing along the data to its own client.
In the code window, select Class from the Object box. In the Procedure box, select Initialize and add the following code to the Class_Initialize event procedure:
```
Private Sub Class_Initialize()
   Debug.Print "Dialogs object created"
   Set mdlg = New dlgDemo
End Sub
```
In the Procedure box, select Terminate and add the following code to the Class_Terminate event procedure:
```
Private Sub Class_Terminate()
   Debug.Print "Dialogs object terminated"
   Unload mdlg
   Set mdlg = Nothing
End Sub
```
When terminating, an object that controls a form should always unload the form and set its reference to the form to Nothing, to avoid tying up resources with orphaned forms.

On the Tools menu, click Add Procedure to open the Add Procedures dialog box. In the Name box, type ShowDialog. Click Function and Public, then click OK.

In the code window, change the newly created Function procedure to appear as follows:

Public Function ShowDialog( _
      Optional ByVal Text As String = "", _
      Optional ByVal Modal As Boolean = True) _
      As String
   With mdlg
      .txtDemo.Text = Text
      If Modal Then
         .Caption = "Modal Dialog Box"
         .Show vbModal
         ShowDialog = .txtDemo.Text
      Else
         .Caption = "Modeless Dialog Box"
         .Show vbModeless
      End If
   End With
End Function

Typed optional arguments let the compiler catch type mismatch errors, instead of waiting until run-time errors occur. Typed optional arguments are discussed in "Programming Fundamentals" in the Visual Basic Programmer’s Guide.

Save the class module as ThingDemo_Dialogs.cls.

The ShowDialog method that displays the dialog has two optional arguments:

The initial text it’s going to display
A Boolean argument that determines whether the dialog is modal

The Text argument is assigned to the text box on dlgDemo before the dialog box is shown. The default value of the Modal argument is True, so omitting it causes the dialog to be modal.

If the dialog is shown Modal, the ShowDialog method returns the contents of the txtDemo text box after the dialog has been dismissed by the user.

If the dialog is shown Modeless nothing is returned, because the client received a NotifyClients event whenever the contents of the text box changed.

For More Information Events are discussed in "Adding Events to Classes" in "General Principles of Component Design."

Step by Step

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

To	See
Go to the next step	Using the Global Object in TestThing
Start from the beginning	Creating an ActiveX DLL.