Events
Reference for Visual Basic Developers

Events

This section describes the events associated with the WebBrowser control.


BeforeNavigate2 Event

Description

Occurs when the WebBrowser control is about to navigate to a different URL, which may happen as a result of external automation, internal automation from a script, or the user clicking a link or typing in the address bar. The container has an opportunity to cancel the pending navigation.

Syntax

Private Sub object_BeforeNavigate2(ByVal pDisp As Object, ByVal URL As String,
ByVal Flags As Long, ByVal TargetFrameName As String, PostData As Variant,
ByVal Headers As String, Cancel As Boolean)

ValueDescription
object Required. An object expression that evaluates to an object in the Applies To list.
pDisp An object that evaluates to the top-level or frame WebBrowser object corresponding to the navigation.
URL A string expression that evaluates to the URL to which the browser is navigating.
Flags Reserved for future use.
TargetFrameName A string expression that evaluates to the name of the frame in which the resource will be displayed, or NULL if no named frame is targeted for the resource.
PostData Data to send to the server if the HTTP POST transaction is being used.
Headers A value that specifies the additional HTTP headers to send to the server (HTTP URLs only). The headers can specify things like the action required of the server, the type of data being passed to the server, or a status code.
Cancel A Boolean value that the container can set to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, Navigate2, NavigateComplete2


CommandStateChange Event

Description

Occurs when the enabled state of a command changes.

Syntax

Private Sub object_CommandStateChange (ByVal Command As Long,
ByVal Enable As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
Command A long integer specifying the identifier of the command that changed. It can be one of the following constants or values.
Constant Value Meaning
CSC_UPDATECOMMANDS -1 The enabled state of a toolbar button may have changed; the Enable parameter should be ignored.
CSC_NAVIGATEFORWARD 1 The enabled state of the Forward button has changed.
CSC_NAVIGATEBACK 3 The enabled state of the Back button has changed.
Enable A Boolean value that is TRUE if the command is enabled, or FALSE if not.

Applies To

InternetExplorer, WebBrowser


DocumentComplete Event

Description

Occurs when the document that is being navigated to reaches the READYSTATE_COMPLETE state.

Syntax

Private Sub object_DocumentComplete(ByVal pDisp As Object, URL As Variant)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
pDisp An object that evaluates to the top-level or frame WebBrowser object corresponding to the event.
URL A string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by DocumentComplete will be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

Remarks

For a document without frames, this event will fire once when the document is finished loading. On a document containing multiple frames, this event is fired once for each frame. When the multiple-frame document has finished loading, the top-level frame fires the event one final time. To detect the last DocumentComplete event of a multiple-frame document, compare the pDisp object returned from the event to the WebBrowser object itself. The following example indicates how to trap the final DocumentComplete event.

Private Sub WebBrowser1_DocumentComplete(ByVal pDisp As Object, URL As Variant)
    If (pDisp Is WebBrowser1.Object) Then
        Debug.Print "Document is finished loading."
    End If
End Sub

Applies To

InternetExplorer, WebBrowser

See Also

BeforeNavigate2, Navigate, Navigate2, READYSTATE


DownloadBegin Event

Description

Occurs when a navigation operation is beginning. This event is fired shortly after the BeforeNavigate2 event, unless the navigation is canceled. Any animation or "busy" indication that the container needs to display should be connected to this event. Note that any DownloadBegin event will have a corresponding DownloadComplete event.

Syntax

Private Sub object_DownloadBegin

ValueDescription
object An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, ProgressChange


DownloadComplete Event

Description

Occurs when a navigation operation finishes, is halted, or fails. Unlike NavigateComplete2, which is fired only when a URL is successfully navigated to, this event is always fired after a navigation starts. Any animation or "busy" indication that the container needs to display should be connected to this event. Note that any DownloadBegin event will have a corresponding DownloadComplete event.

Syntax

Private Sub object_DownloadComplete

ValueDescription
object An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer, WebBrowser

See Also

Navigate, Navigate2, ProgressChange


NavigateComplete2 Event

Description

Occurs after the browser has successfully navigated to a new location. The document might still be downloading (and in the case of HTML, images may still be downloading), but at least part of the document has been received from the server, and the viewer for the document has been created.

Syntax

Private Sub object_NavigateComplete2(ByVal pDisp As Object, URL As Variant)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
pDisp An object that evaluates to the top-level or frame WebBrowser object corresponding to the event.
URL A string expression that evaluates to the URL, UNC file name, or PIDL that was navigated to. Note that this URL can be different from the URL that the browser was told to navigate to. One reason is that this URL is the canonicalized and qualified URL; for example, if an application specified a URL of "www.microsoft.com" in a call to the Navigate or Navigate2 method, the URL passed by NavigateComplete2 will be "http://www.microsoft.com/". Also, if the server has redirected the browser to a different URL, the redirected URL will be reflected here.

Applies To

InternetExplorer, WebBrowser

See Also

BeforeNavigate2


NewWindow2 Event

Description

Occurs when a new window is to be created for displaying a resource. Some actions that can cause this include the user shift-clicking on a link, the user right-clicking on a link and choosing "open in new window", or a targeted navigation to a frame name that does not yet exist. Your browser application can also trigger this event by calling the Navigate or Navigate2 method with the navOpenInNewWindow flag. The WebBrowser control has an opportunity to handle the new window creation itself. If it does not, a top-level Internet Explorer window is created as a separate (nonhosted) process.

Syntax

Private object_NewWindow2 (ByVal ppDisp As Object, ByVal Cancel As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
ppDisp An object expression that, optionally, receives a new, hidden WebBrowser or InternetExplorer object with no URL loaded.
Cancel A Boolean value that, when set to True, is used to cancel the new window creation and attempt the navigation in the current window.

Remarks

The application processing this notification can respond in one of three ways:

  1. Create a new, hidden, non-navigated WebBrowser or InternetExplorer object that is returned in ppDisp. Upon return from this event, the object that fired this event will then configure and navigate (including a BeforeNavigate2 event) the new object to the target location.
  2. Cancel the new window creation by setting Cancel to true. No object is created and the navigation is attempted on the current window (with an accompanying BeforeNavigate2 event).
  3. Do nothing and do not set ppDisp to any value. This will cause the object that fired the event to create a new InternetExplorer object to handle the navigation.

Applies To

InternetExplorer, WebBrowser

See Also

NavigateComplete2


OnFullScreen Event

Description

Occurs when the FullScreen property is changed.

Syntax

Private Sub object_OnFullScreen(ByVal FullScreen As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
FullScreen If TRUE, the browser window is maximized; if FALSE, it is not.

Remarks

An application hosting the WebBrowser control should respond to this event by enlarging or reducing the window size. When using scripting in an HTML page, this event corresponds to the size properties passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnMenuBar Event

Description

Occurs when the MenuBar property is changed.

Syntax

Private Sub object_OnMenuBar(ByVal MenuBar As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
MenuBar If TRUE, the menu bar is shown; if FALSE, the menu bar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the menu bar, if applicable. When using scripting in an HTML page, this event corresponds to the menu bar property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnQuit Event

Description

Occurs before the Internet Explorer application quits.

Syntax

Private Sub object_OnQuit()

ValueDescription
object An object expression that evaluates to an object in the Applies To list.

Applies To

InternetExplorer

See Also

Quit


OnStatusBar Event

Description

Occurs when the StatusBar property is changed.

Syntax

Private Sub object_OnStatusBar(ByVal StatusBar As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
StatusBar If TRUE, the status bar is shown; if FALSE, the status bar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the status bar, if applicable.

Applies To

InternetExplorer, WebBrowser


OnTheaterMode Event

Description

Occurs when the TheaterMode property is changed.

Syntax

Private Sub object_OnTheaterMode(ByVal TheaterMode As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
TheaterMode If TRUE, the browser is in theater mode; if FALSE, the browser is in normal viewing mode. The default value is FALSE.

Remarks

Theater mode uses the entire screen to display the URL.

Applies To

InternetExplorer, WebBrowser


OnToolBar Event

Description

Occurs when the ToolBar property is changed.

Syntax

Private Sub object_OnToolBar(ByVal ToolBar As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
ToolBar If TRUE, the toolbar is shown; if FALSE, the toolbar is hidden.

Remarks

An application hosting the WebBrowser control should respond to this event by hiding or showing the toolbar, if applicable. When using scripting in an HTML page, this event corresponds to the toolbar property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser


OnVisible Event

Description

Occurs when the Visible property is changed.

Syntax

Private Sub object_OnVisible(ByVal Visible As Boolean)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
Visible If TRUE, the WebBrowser window should be shown; if FALSE, the window should be hidden.

Applies To

InternetExplorer, WebBrowser


ProgressChange Event

Description

Occurs when the progress of a download operation is updated.

Syntax

Private Sub object_ProgressChange(ByVal Progress As Long, ByVal ProgressMax As Long)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
Progress A long integer that specifies the amount of total progress to show, or -1 when progress is complete.
ProgressMax A long integer that specifies the maximum progress value.

Remarks

The container can use the information provided by this event to display the number of bytes downloaded so far or to update a progress indicator.

To calculate the percentage of progress to show in a progress indicator, multiply the value of Progress by 100 and divide by the value of ProgressMax (unless Progress is -1, in which case the container can indicate that the operation is finished or hide the progress indicator).

Applies To

InternetExplorer, WebBrowser

See Also

DownloadBegin, DownloadComplete, Navigate


PropertyChange Event

Description

Occurs when the PutProperty method changes the value of a property.

Syntax

Private Sub object_PropertyChange(ByVal szProperty As String)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
szProperty A string expression that contains the name of the property whose value has changed.

Applies To

InternetExplorer

See Also

GetProperty


StatusTextChange Event

Description

Occurs when the status bar text has changed.

Syntax

Private Sub object_StatusTextChange(ByVal Text As String)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
Text A string containing the new status bar text.

Remarks

The container can use the information provided by this event to update the text of a status bar. When using scripting in an HTML page, this event corresponds to the status property passed in the window.open method.

Applies To

InternetExplorer, WebBrowser

See Also

StatusBar, StatusText


TitleChange Event

Description

Occurs when the title of a document in the WebBrowser control becomes available or changes. Because the title might change while an HTML page is downloading, the URL of the document is set as the title. After the title specified in the HTML page, if there is one, is parsed, the title is changed to reflect the actual title.

Syntax

Private Sub object_TitleChange(ByVal Text As String)

ValueDescription
object An object expression that evaluates to an object in the Applies To list.
Text A string containing the new document title.

Applies To

InternetExplorer, WebBrowser

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.