BeforeNavigate2 event
Fires before navigation occurs in the given object (on either a window element or a frameset element).
Syntax
| HTML Attribute | <element BeforeNavigate2 = "handler(event)"> |
| attachEvent Method | object.attachEvent("BeforeNavigate2", handler) |
Event information
| Synchronous | No |
| Bubbles | No |
| Cancelable | No |
Event handler parameters
pDisp [in]
| C++ | A pointer to the IDispatch interface for the WebBrowser object that represents the window or frame. This interface can be queried for the IWebBrowser2 interface. |
| VB | IDispatch that evaluates to the top-level or frame WebBrowser object corresponding to the navigation. |
Url [in, ref]
| C++ | A pointer to a VARIANT structure of type VT_BSTR that contains the URL to navigate to. |
| VB | BSTR expression that evaluates to the URL to which the browser is navigating. |
Flags [in, ref]
Type: Variant
A pointer to a VARIANT of type VT_I4 that contains the following flag, or zero.
beforeNavigateExternalFrameTarget (&H0001)
Internet Explorer 7 or later. This navigation is the result of an external window or tab that targets this browser.
TargetFrameName [in, ref]
| C++ | A pointer to a VARIANT structure of type VT_BSTR that contains the name of the frame in which to display the resource, or NULL, if no named frame is targeted for the resource. |
| VB | BSTR 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 [in, ref]
| C++ | A pointer to a VARIANT structure of type VT_BYREF|VT_VARIANT that contains the data to send to the server if the HTTP POST transaction is used. |
| VB | Data to send to the server if the HTTP POST transaction is being used. |
Headers [in, ref]
| C++ | A pointer to a VARIANT structure of type VT_BSTR that contains additional HTTP headers to send to the server (HTTPURLs only). The headers can specify information, such as the action required of the server, the type of data passed to the server, or a status code. |
| VB | Value that specifies the additional HTTP headers to send to the server (HTTP URLs only). The headers can specify such things as the action required of the server, the type of data being passed to the server, or a status code. |
Cancel [in, out, ref]
| C++ | A pointer to a VARIANT structure of type VARIANT_BOOL that contains the cancel flag. An application can set this parameter to VARIANT_TRUE to cancel the navigation operation, or to VARIANT_FALSE to allow the navigation operation to proceed.
Note The
Cancel parameter is an OUT parameter to cancel or allow navigation as above. However, because there is a chain of event handlers, Cancel is also an IN parameter to provide notification of the value set by the previous handler.
|
| VB | VARIANT_BOOL value that the container can set to TRUE to cancel the navigation operation, or to FALSE to allow it to proceed. |
Remarks
The post data specified by PostData is passed as a SAFEARRAY structure. The variant should be of type VT_BYREF|VT_VARIANT, which points to a SAFEARRAY. The SAFEARRAY should be of element type VT_UI1, dimension one, and have an element count equal to the number of bytes of post data.
The url parameter can be a pointer to an item identifier list (PIDL) in the case of a Shell namespace entity for which there is no URL representation.
The BeforeNavigate2 event replaces the BeforeNavigate and FrameBeforeNavigate events, which should no longer be used. The pDisp parameter that specifies the corresponding WebBrowser object identifies where the navigation is to occur. Microsoft Internet Explorer 3.0 required the FrameBeforeNavigate and a target frame name to identify the target of navigation. However, this solution was ambiguous, because frame names are not unique.
Note Microsoft Internet Explorer 4.0 and later continue to fire the BeforeNavigate and FrameBeforeNavigate events for compatibility with Internet Explorer 3.0.
The pDisp parameter specifies the WebBrowser object of the top-level frame that corresponds to the navigation. Navigation to a different URL might occur as a result of external automation, internal automation from a script, or the user clicking a link or typing in the address bar. The processing of this navigation can be modified by setting the Cancel parameter to VARIANT_TRUE, and ignoring or resending a modified navigation method to the WebBrowser object.
When you resend a navigation for the WebBrowser object, the Stop method must first be executed for pDisp. This prevents a web page that declares a canceled navigation from appearing while the new navigation is being processed.
See also
Reference