Microsoft KB Archive/176468

= INFO: Forms Behavior in an ActiveX Document =

Article ID: 176468

Article Last Modified on 7/30/2003

-

APPLIES TO


 * Microsoft Visual Basic 5.0 Professional Edition
 * Microsoft Visual Basic 6.0 Professional Edition
 * Microsoft Visual Basic 5.0 Enterprise Edition
 * Microsoft Visual Basic 6.0 Enterprise Edition

-



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.



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:

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

Keywords: kbinfo kbactivedocs kbdocs kbforms KB176468

-

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

© Microsoft Corporation. All rights reserved.