The important events for Active Document event management are very similar
to those of an ActiveX control. It is also important to note that the firing and
sequencing of these events will not be the same for your Active Document in different
container types. The important Active Document events are listed in the following
sections followed by a discussion of the typical sequencing of events in an Active
Document running under different container types.
The Scroll event is discussed in a separate section called "Managing
Active Document Scrolling."
The Initialize event is always the first event fired
in a session with the Active Document regardless of container type. It fires when
the document loads into its container.
You might use the Initialize event to set certain
behavioral properties of the UserDocument, as in Listing
14.2.
LISTING 14.2
CODING THE INITIALIZE EVENT PROCEDURE
Private Sub UserDocument_Initialize()
UserDocument.ContinuousScroll = False
UserDocument.HScrollSmallChange = 20
UserDocument.VScrollSmallChange = 20
UserDocument.MinHeight = 10000
UserDocument.MinWidth = 10000
End Sub
Note that the Initialize event will typically fire
more often under Internet Explorer than under Office Binder. This is because Internet
Explorer will unload your document whenever the user has navigated to four other
documents after loading your document (see the section called "Terminate
Event"). Therefore, IE will need to reload your document if the user wishes
to return to it, thus firing the Initialize event.
InitProperties Event (Back
to Top)
InitProperties event fires only when the container brings up a brand-new instance
of your object. If the container has already saved information about your object
once in its .vbd file, then InitProperties won't fire.
You use InitProperties, therefore, in a similar manner
to the way you use the InitProperties event of the
ActiveX Custom Control: to assign default initial values. In the example of Listing
14.3, you can manipulate the custom property named UserID,
whose value is delegated by the Text1 TextBox control.
LISTING 14.3
THE INITPROPERTIES EVENT PROCEDURE
[General Declarations]
Option Explicit
Private Const m_def_UserID = "YOWSA"
Private Sub UserDocument_InitProperties()
Text1.Text = m_def_UserID
End Sub
In the General Declarations of the UserDocument,
the UserID's default value is defined in the constant
m_def_UserID. In the InitProperties event procedure,
you can assign the value of this constant to the TextBox that
delegates the UserID property.
EnterFocus event fires when the user first sets
focus anywhere in your document. The event fires in both Internet Explorer and
Office Binder.
In Office Binder, Show event does not normally fire.
In Internet Explorer, it fires when the user navigates to this document from another
page during the same Internet Explorer session.
The
ReadProperties Event and ReadProperty Method (Back
to Top)
You use the ReadProperties in a similar way to the
ReadProperties event of the UserControl object
in an ActiveX control project: to retrieve persistent information from the
Property Bag and store it appropriately within your running application.
Note that Active Documents cooperate with their containers in using a .vbd file
to store and retrieve their persistent properties.
Unlike the use of ReadProperties in an ActiveX control
project, however, you don't use ReadProperties to persist
design-time information to runtime property values. Instead, you use
ReadProperties to persist property values between sessions of the container
applications. The PropBag object for Active Documents typically stores its information
in a .vbd (Visual Basic Document) file between container application sessions.
In Listing 14.4, the ReadProperties event procedure
uses the Property Bag's ReadProperty
method to get the stored value for the UserID property
and then assigns this value to the text box that delegates the
UserID property. As you'll recall from the discussion of Chapter
13, the second argument to ReadProperty is a fallback—it
supplies a default value in case a value for UserID is
missing from the Property Bag.
LISTING 14.4
THE READPROPERTIES EVENT PROCEDURE
Private Sub UserDocument_ReadProperties _
(PropBag As PropertyBag)
Text1.Text = _
PropBag.ReadProperty _
("UserID", m_def_UserID)
End Sub
The WriteProperties
Event and the WriteProperty Method (Back to Top)
You use the WriteProperties event in a parallel
way to the way that you use the WriteProperties event
of the UserControl object in an ActiveX control project:
to store persistent information from your running application to the
Property Bag. Note that Active Documents cooperate with their containers
in using a .vbd file to store and retrieve their persistent
properties.
Unlike the use of WriteProperties in an ActiveX
control project, however, you don't use WriteProperties to
persist design-time information to runtime property values. Instead, you use
WriteProperties to persist property values between sessions of the container
applications. The PropBag object for Active Documents
typically stores its information in a .vbd (Visual
Basic Document) file between container application sessions.
In Listing 14.5, the WriteProperties event procedure
uses the Property Bag's WriteProperty
method. The method is used to store to the Property
Bag the value for the UserID property from the
Textbox that delegates the UserID property.
As you'll recall from the discussion in
Chapter 13, the third argument to WriteProperty is
a fallback—it supplies a default value in case a value for
UserID is missing from the TextBox.
LISTING 14.5
AN ACTIVE DOCUMENT'S WRITEPROPERTY EVENT PROCEDURE
Private Sub _
UserDocument_WriteProperties _
(PropBag As PropertyBag)
PropBag.WriteProperty _
"UserID", Text1.Text, m_def_UserID
End Sub
For a more extensive treatment of WriteProperties, see
Chapter 13.
This event fires when the user first sets focus anywhere outside your document
to another document in the container application. The event fires in both Internet
Explorer and Office Binder.
In Office Binder, this event does not normally fire. In Internet Explorer,
it fires when the user navigates from this document to another Web page during
the same Internet Explorer session.
The Terminate event happens when the container is
about to destroy the current instance of your document.
In Office Binder, this event fires upon a user action to close the binder containing
this document, or when the user removes this document from its binder.
In Internet Explorer, this event can fire more often: Internet Explorer will
fire the Terminate event when it removes this document
from the active History list during the current session. In IE 3.0 and 4.0, only
the four most recently accessed documents are on the History list. So your document
will receive a Terminate event if the user navigates
to four other documents after this one.
