Q176468: INFO: Behavior of Forms in an ActiveX Document
Article: Q176468
Product(s): Microsoft Visual Basic for Windows
Version(s):
Operating System(s):
Keyword(s): kbVBp500 kbVBp600 kbGrpDSVB
Last Modified: 11-JAN-2001
-------------------------------------------------------------------------------
The information in this article applies to:
- Microsoft Visual Basic Professional Edition for Windows, versions 5.0, 6.0
- Microsoft Visual Basic Enterprise Edition for Windows, versions 5.0, 6.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
The forms Load and Unload events could then be used to set the value of
flagIsFormOpen to True or False:
Private Sub Form_Load()
flagFormIsOpen = True
End Sub
Private Sub Form_Unload(Cancel As Integer)
flagFormIsOpen = False
End Sub
Next, check for the value of the variable in the Hide event of the UserDocument,
and handle the forms behavior appropriately:
Private Sub UserDocument_Hide()
If flagFormIsOpen Then
frmDetails.Visible = False
End If
End Sub
In the example above, 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 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
Finally, as a general rule, forms should be unloaded when the object that created
them terminates. Therefore, the ActiveX document should unload any open forms it
created when the ActiveX document terminates. The ActiveX document may terminate
in various scenarios. The Terminate event of the UserDocument can be used to
unload the form if it is still open:
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 will be Unloaded
automatically when the Terminate event fires. When this occurs, however, the
QueryUnload event of the form does not fire and the Cancel argument of the
Unload event is ignored.
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
In the chart above, "modal" means the modal form behaved as a true modal form.
"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, 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, you can code all of your forms to open as modal (being
aware of the issues stated above) or you can test for the behavior of the
container, using the App object, before opening the form:
If App.NonModalAllowed Then
frmModeless.Show vbModeless
Else
frmModeless.Show vbModal
End If
If you do use modeless forms, users will be able navigate away from your ActiveX
document and the form will drop to the background if navigation takes place.
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 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 click 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 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 : kbVBp500 kbVBp600 kbGrpDSVB
Technology : kbVBSearch kbAudDeveloper kbZNotKeyword6 kbZNotKeyword2 kbVB500Search kbVB600Search kbVBA500 kbVBA600 kbVB500 kbVB600
Hardware : x86
Issue type : kbinfo
=============================================================================
THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.
Copyright Microsoft Corporation 1986-2002.