INFO: Behavior of Forms in an ActiveX Document

• Microsoft Visual Basic Professional and Enterprise Editions for Windows, version 5.0

SUMMARY

As a developer, you need to consider several aspects of form behavior when developing an ActiveX document application that uses forms. Because the ActiveX document application will always be run within a container application, forms may behave differently than when within a standard Visual Basic project. This article will describe the key considerations that must be taken when developing forms for an ActiveX application.

MORE INFORMATION

Although an ActiveX document can be displayed in varying containers, this article will focus on using Internet Explorer as the container.

Client Navigation

Users of Internet Explorer have the freedom of navigating to different pages when they visit your ActiveX document. They can navigate forward, backward, or to a specific URL address. If a Visual Basic form is open when a user navigates to a new page, the form will remain open, visible on the Windows desktop behind Internet Explorer. The form will remain open until the user or the application closes it, even after the ActiveX document has been terminated.

You cannot prevent a user from navigating. However, you can program your application to detect when navigation occurs. The UserDocument Hide event will fire when a user navigates to a new page from your ActiveX document application. This event may then be used to handle your forms behavior when a user navigates off your page.

For example, you could create a Public boolean variable named flagIsFormOpen to keep track of when the form was open. This variable would need to be declared in the General Declarations section of a standard code module native to your ActiveX document project:

   Public flagFormIsOpen As Boolean

   Private Sub Form_Load()
      flagFormIsOpen = True
   End Sub

   Private Sub Form_Unload(Cancel As Integer)
      flagFormIsOpen = False
   End Sub

   Private Sub UserDocument_Hide()
       If flagFormIsOpen Then
          frmDetails.Visible = False
       End If
   End Sub

Next, determine if a user returns to the page before the ActiveX document application is terminated and display the form to the user. If a user navigates back to the ActiveX document before it is terminated, the UserDocument's Show event fires:

   Private Sub UserDocument_Show()
      If flagFormIsOpen then
         frmDetails.Visible = True
      End if
   End Sub

   Private Sub UserDocument_Terminate()
      If flagFormIsOpen Then
         Unload frmDetails
      End If
   End Sub

Modal Forms

The behavior of modal forms in ActiveX Documents is inconsistent between different versions of Internet Explorer, on different operating systems, and between in-process (DLL) and out-of-process (EXE) servers. When a modal form is opened within an ActiveX document, the desired behavior would be to have the form modal to the UserDocument and the container application. However, this is not always the case. The chart below shows the varying behavior of modal forms:

                IE3/95    IE3/NT   IE4/95   IE4/NT
                ------------------------------------
ActiveX EXE     Partial   Partial  Partial  Partial
ActiveX DLL     Modal     Modal    Modal    Modeless

"Modeless" means the modal form behaved just like a modeless form.

"Partial" means the modal form behaved in some ways like a modal form. In certain partial cases, modal forms were modal to the UserDocument and only objects created by the UserDocument. The modal form was not modal to the container or any other frames displayed by Internet Explorer. In other cases, the form appeared to work as a modal form but the Refresh button on the IE toolbar was still accessible.

The behavior of modal forms is the responsibility of the container. Therefore, the chart above is subject to change with future releases of Internet Explorer.

Note that regardless of the value of the ShowInTaskBar property, modal forms will not appear in the Windows Task Bar.

Modeless Forms

You cannot use modeless forms in some containers, including Internet Explorer, when the server is in-process. If you attempt to use a non-modal form, the following error may be received:

   "Run-time error '406':  Non-modal forms cannot be displayed in
   this host application from an ActiveX DLL, ActiveX Control or
   Property Page."

   If App.NonModalAllowed Then
      frmModeless.Show vbModeless
   Else
      frmModeless.Show vbModal
   End If

Unlike modal forms, modeless forms will appear in the Windows TaskBar if the ShowInTaskBar property is set to true.

Avoiding Forms

In ActiveX Document applications, it is recommended that forms be avoided. Instead, use other UserDocuments to achieve the same tasks. As described above, the behavior of forms may make your application difficult to use or confusing for clients. UserDocuments can achieve most of the same tasks as forms and can be manipulated much more easily than forms in an ActiveX document application.

If you have some existing forms that you would like to convert to UserDocuments, Visual Basic 5.0 ships with the "VB ActiveX Document Migration Wizard" that allows you to convert Visual Basic forms to UserDocuments easily. To access the "VB ActiveX Migration Wizard," choose Add-In Manager from the Add-Ins menu in Visual Basic. From within the Add- In Manager, select the "VB ActiveX Migration Wizard" and choose OK. Now choose the Wizard from the Add-Ins menu. (If the "VB ActiveX Migration Wizard" was not an available selection in the Add-In Manager, you may need to add it by running the Visual Basic 5 installation program).

In an ActiveX document application you can add additional UserDocuments to your project. These will become individual .VBD files when the application is compiled. You can then navigate to the .VBD files using the NavigateTo method of the Hyperlink object, as in the following example:

   Private Sub_Command1_Click()
      HyperLink.NavigateTo "UserDocument2.Vbd"
   End Sub

Keywords          : vb5all VBKBAutomation VBKBAX VBKBComp VBKBDLL VBKBInet
Technology        : internet
Version           : WINDOWS:5.0
Platform          : WINDOWS
Hardware          : x86
Issue type        : kbinfo