INFO: Forms Behavior in an ActiveX Document (176468)


The information in this article applies to:

  • Microsoft Visual Basic Professional Edition for Windows 5.0
  • Microsoft Visual Basic Professional Edition for Windows 6.0
  • Microsoft Visual Basic Enterprise Edition for Windows 5.0
  • Microsoft Visual Basic Enterprise Edition for Windows 6.0
This article was previously published under Q176468

SUMMARY

When you develop a Microsoft ActiveX document application that uses forms, the forms may behave differently than they behave when they run in a standard Microsoft Visual Basic project. This varied behavior occurs because the ActiveX document application always runs in a container application. This article describes some of the things to consider when you develop forms for an ActiveX application.

Note Although an ActiveX document can be displayed in different containers, this article focuses on using Microsoft Internet Explorer as the container.

MORE INFORMATION

Client Navigation

Internet Explorer users can navigate to different pages when they visit your ActiveX document. They can navigate forward, navigate backward, or navigate to a specific URL address. If a Visual Basic form is open when a user navigates to a new page, the form remains open. The form is visible on the Windows desktop, behind Internet Explorer. The form remains open until the user closes it 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 a user navigates. The UserDocument Hide event fires when a user navigates to a new page from your ActiveX document application. You can then use this event to handle the behavior of your form when a user navigates off your page. For example, you can create a public Boolean variable named flagFormIsOpen to track when the form is open. The following variable must be declared in the General Declarations section of a standard code module that is native to your ActiveX document project: 
   Public flagFormIsOpen As Boolean
You can now use the Load event and the Unload event of the form to set the value of flagIsFormOpen to True or to False, as in the following example: 
   Private Sub Form_Load()
      flagFormIsOpen = True
   End Sub

   Private Sub Form_Unload(Cancel As Integer)
      flagFormIsOpen = False
   End Sub
Next, look for the value of the variable in the Hide event of the UserDocument, and then handle the behavior of the forms appropriately, as follows: 
   Private Sub UserDocument_Hide()
       If flagFormIsOpen Then
          frmDetails.Visible = False
       End If
   End Sub
Note In this example, the name of the form is frmDetails. When a user navigates away from the UserDocument, the Hide event checks for the value of the flagFormIsOpen variable. If the form is open, hide the form.

Next, determine if a user returns to the page before the ActiveX document application is terminated, and then display the form to the user. If a user returns to the page before the ActiveX document is terminated, the Show event of the UserDocument fires, as follows: 
   Private Sub UserDocument_Show()
      If flagFormIsOpen then
         frmDetails.Visible = True
      End if
   End Sub
Finally, a form will typically be unloaded when the object that created the form terminates. Therefore, the ActiveX document should unload any open forms that it created when the ActiveX document terminates. The ActiveX document may terminate in various scenarios. You can use the Terminate event of the UserDocument to unload the form if the form is still open, as follows: 
   Private Sub UserDocument_Terminate()
      If flagFormIsOpen Then
         Unload frmDetails
      End If
   End Sub
Note If the visible property a form is set to False, the form is automatically unloaded when the Terminate event fires. However, the QueryUnload event of the form does not fire and the Cancel argument of the Unload event is ignored by the Terminate event of the form when this behavior occurs.

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. Based on the browser and the operating system combination, the modal behavior of a control in a form is not consistent. When a modal form is opened in an ActiveX document, you may expect to have the form modal to the UserDocument and to the container application. However, this does not always occur. The following chart shows the varying behavior of modal forms:

IE3/95IE3/NTIE4/95IE4/NTIE5/2KIE6/2KIE6/XP
ActiveX EXE PartialPartialPartialPartialPartialPartialPartial
ActiveX DLL ModalModalModalModelessModalModalModal

Note The container is responsible for the modal behavior. Therefore, this chart may change with future releases of Internet Explorer.

In this chart, "Modal" indicates that the modal form behaved as a true modal form. "Modeless" indicates that the modal form behaved as a modeless form. "Partial" indicates that the modal form partially behaves like a modal form. Sometimes modal forms are only modal to the UserDocument and to objects that the UserDocument creates. The modal form is not modal to the container or to any other frames that Internet Explorer displays. In other cases, the form appears to work as a modal form, but the Refresh button on the Internet Explorer toolbar is still accessible.

Note Regardless of the ShowInTaskBar property value, modal forms do not appear in the Microsoft Windows Task Bar.

Modeless Forms

You cannot use modeless forms in some containers (including Internet Explorer) when the server is in-process. If you try to use a non-modal form, you might receive the following error message:
Run-time error '406': Non-modal forms cannot be displayed in
this host application from an ActiveX DLL, ActiveX Control or
Property Page.
To avoid this problem, code all your forms to open as modal (be aware of the issues that are mentioned in this article), or test for the behavior of the container by using the App object before you open the form, as follows: 
   If App.NonModalAllowed Then
      frmModeless.Show vbModeless
   Else
      frmModeless.Show vbModal
   End If
If you use modeless forms, users can navigate away from your ActiveX document. The form drops to the background if a user navigates.

Unlike modal forms, modeless forms appear in the Windows Task Bar if you set the ShowInTaskBar property to True.

Avoiding Forms

Instead of using forms in ActiveX document applications, Microsoft recommends that you use other UserDocuments to get the same results. As described in this article, the inconsistent behavior of forms may cause confusion for clients. UserDocuments can offer many of the same features as forms. UserDocuments have easier manipulation than forms in an ActiveX document application.

Visual Basic includes the Microsoft Visual Basic ActiveX Document Migration Wizard. If you have existing forms that you want to convert to UserDocuments, the Visual Basic ActiveX Document Migration Wizard allows you to easily convert Visual Basic forms to UserDocuments. To access the Visual Basic ActiveX Document Migration Wizard, follow these steps:
  1. In Visual Basic, click Add-In Manager on the Add-Ins menu.
  2. From Add-In Manager, click Visual Basic ActiveX Migration Wizard, and then click OK.
  3. Click the Visual Basic ActiveX Migration Wizard on the Add-Ins menu.

    Note If the Visual Basic ActiveX Migration Wizard is not an available choice in Add-In Manager, you may have to run the Visual Basic installation program to add the Visual Basic ActiveX Migration Wizard.
In an ActiveX document application, you can add additional UserDocuments to your project. These UserDocuments become individual .vbd files when you compile the application. You can then navigate to the .vbd files by using the NavigateTo method of the Hyperlink object, as in the following example: 
   Private Sub_Command1_Click()
      HyperLink.NavigateTo "UserDocument2.Vbd"
   End Sub
Modification Type:MajorLast Reviewed:7/30/2003
Keywords:kbForms kbDocs kbActiveDocs kbinfo KB176468 kbAudDeveloper
©2003 Microsoft Corporation. All rights reserved.