Cry about...
Delphi Programming with TWebBrowser
TWebBrowser - Events
TWebBrowser supports the following event handlers (this list is taken from the events listed within Object Inspector):
- OnBeforeNavigate2
- OnClientToHost
- OnCommandStateChange
- OnDocumentComplete
- OnDownloadBegin
- OnDownloadComplete
- OnDragDrop
- OnDragOver
- OnEndDrag
- OnEnter
- OnExit
- OnFileDownload
- OnFullScreen
- OnMenuBar
- OnNavigateComplete2
- OnNavigateError
- OnNewWindow2
- OnPrintTemplateInstallation
- OnPrintTemplateTeardown
- OnPrivacyImpactStateChange
- OnProgressChange
- OnPropertyChange
- OnQuit
- OnSetSecureLockIcon
- OnStartDrag
- OnStatusBar
- OnStatusTextChange
- OnTheaterMode
- OnTitleChange
- OnToolBar
- OnUpdatePage
- OnUpdatePageStatus
- OnVisible
- OnWindowClosing
- OnWindowSetHeight
- OnWindowSetLeft
- OnWindowSetResizeable
- OnWindowSetTop
- OnWindowSetWidth
- PopupMenu
Note: There are some differences between TWebBrowser v1 (which is compatible with Internet Explorer 4 and later) and TWebBrowser (which is compatible with Internet Explorer 5 and later).
OnBeforeNavigate2
Called before navigation (to a URL) begins - this could be either for a window or for a frame.
procedure YourForm.OnBeforeNavigate2(
Sender: TObject;
const pDisp: IDispatch;
var URL, Flags, TargetFrameName, PostData, Headers: OleVariant;
var Cancel: WordBool);
Arguments:
- Sender
- The TWebBrowser component for which the event is being generated.
Usage:(Sender as TWebBrowser)
- pDisp
- The IWebBrowser component for which the event is being generated. This is the top level browser if:
(pDisp as IWebBrowser) = (Sender as TWebBrowser).DefaultInterface
- URL
- The URL that is to be navigated to.
- Flags
- Not currently used.
- TargetFrameName
- Name of the frame in which the URL is to be displayed (if named), otherwise nil.
- PostData
- Data sent to the server when responding to a form using POST.
- Headers
- Additional HTTP headers to send to the server.
- Cancel
- Flag allowing the browse operation to be cancelled or blocked. Set True to cancel the browse, False to allow it to go ahead. Has the value False on entry.
OnClientToHost
TBD
procedure YourForm.WebBrowser_OnClientToHost( Sender: TObject; var CX, CY: Integer);
TBD
OnCommandStateChange
Indicates whether certain command functionality is available.
procedure YourForm.WebBrowser_OnCommandStateChange( Sender: TObject; Command: Integer; Enable: WordBool);
Arguments:-
Command is one of:
type TCommandStateChangeConstants =( CSC_UPDATECOMMANDS = $FFFFFFFF, CSC_NAVIGATEFORWARD = $000000001, CSC_NAVIGATEBACK = $00000002);
CSC_UPDATECOMMANDS
- The state of one of the toolbar buttons may have changed. Check status of each toolbar button relevant to your application and whether the toolbar is visible.
CSC_NAVIGATEFORWARD
- Indicates whether there is "forward" history.
CSC_NAVIGATEBACK
- Indicates whether there is "backwards" history.
Note: It seems fairly common to use OnCommandStateChange
to control directly whether the "Back" and "Forward" buttons should be available:
procedure YourForm.WebBrowser_OnCommandStateChange( Sender: TObject; Command: Integer; Enable: WordBool); begin case Command of CSC_NAVIGATEBACK: BackBtn.Enabled := Enable; CSC_NAVIGATEFORWARD: ForwardBtn.Enabled := Enable; end; end;
OnDocumentComplete
Called when the document or a frame has finished loading.
procedure YourForm.OnDocumentComplete( Sender: TObject; const pDisp: IDispatch; var URL: OleVariant);
To test whether a frame or the entire document have finished loading either:
- Test the ReadyState
property, if it is
READYSTATE_COMPLETE
then the document has finished loading.
or
- Use the following code fragment:
procedure YourForm.OnDocumentComplete(
Sender: TObject;
const pDisp: IDispatch;
var URL: OleVariant);
var
currentBrowser: IWebBrowser;
topBrowser: IWebBrowser;
document: OleVariant;
windowName: string;
begin
currentBrowser := pDisp as IWebBrowser;
topBrowser := (Sender as TWebBrowser).DefaultInterface;
if currentBrowser = topBrowser then
ShowMessage('Complete document was loaded')
else
begin
document := currentBrowser.Document;
windowName := document.ParentWindow.Name;
ShowMessage(Format('Frame "%s" was loaded', [windowName]));
end;
end;
OnDownloadBegin
TBD
OnDownloadComplete
Called when a navigation operation has completed or been interrupted. Downloading should not be confused with rendering of the page (see also OnDocumentComplete).
procedure YourForm.WebBrowser_OnDownloadComplete( Sender: TObject);
OnDragDrop
TBD
procedure YourForm.WebBrowser_OnDragDrop( Sender, Source: TObject; X, Y: Integer);
TBD
OnDragOver
TBD
procedure YourForm.WebBrowser_OnDragOver( Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean);
TBD
OnEndDrag
TBD
procedure YourForm.WebBrowser_OnEndDrag( Sender, Target: TObject; X, Y: Integer);
TBD
OnEnter
TBD
procedure YourForm.WebBrowser_OnEnter( Sender: TObject);
OnExit
TBD
procedure YourForm.WebBrowser_OnExit( Sender: TObject);
TBD
OnFileDownload
Called before a file download commences. This event is called before any necessary download dialog appears.
procedure YourForm.OnFileDownload( Sender: TObject; var Cancel: WordBool);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
Cancel
- Set True to cancel the file download. False to allow it to continue.
Note:
It has been observed that on a Delphi 7 installation, the TWebBrowser component does not appear to support the OnFileDownload event. This is because the interface to TWebBrowser that comes with Delphi 7 is old. To get around this uninstall the existing TWebBrower component (Component > Install Packages... and remove "Internet Explorer Components") and then follow the notes here on "How to install TWebBrowser".
OnFullScreen
TBD
procedure YourForm.WebBrowser_OnFullScreen( Sender: TObject; FullScreen: WordBool);
TBD
OnMenuBar
TBD
procedure YourForm.WebBrowser_OnMenuBar( Sender: TObject; MenuBar: WordBool);
TBD
OnNavigateComplete2
Called when navigation via a hyperlink has completed.
procedure YourForm.WebBrowser_OnNavigateComplete2( Sender: TObject; const pDisp: IDispatch; var URL: OleVariant);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
pDisp
- The IWebBrowser component for which the event is being generated. Usage:
(pDisp as IWebBrowser)
URL
- The URL that has been navigated to.
OnNavigateError
Called when navigation to a url fails.
procedure YourForm.WebBrowser_OnNavigateError( Sender: TObject; const pDisp: IDispatch; var URL, Frame, StatusCode: OleVariant; var Cancel: WordBool);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
pDisp
- The IWebBrowser component for which the event is being generated. Usage:
(pDisp as IWebBrowser)
URL
- The URL for which navigation failed.
Frame
- The name of the frame involved, or nil if no frame involved.
StatusCode
- An error status indicating why the navigation failed. Not always available.
Cancel
- Specifies (on exit) whether to cancel the navigation and display an error page (False) or to continue to an "auto-search" page (True).
OnNewWindow2
Called when a new window is about to be created.
procedure YourForm.WebBrowser_OnNewWindow2( Sender: TObject; var ppDisp: IDispatch; var Cancel: WordBool);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
ppDisp
- Optional - can use to provide a new WebBrowser object to use for the new window. If left unchanged then a new Internet Explorer window will be created.
Cancel
- Set true to cancel the new window, False to allow the new window to open.
For example, to open a new new custom browser form:
procedure YourForm.WebBrowser_OnNewWindow2( Sender: TObject; var ppDisp: IDispatch; var Cancel: WordBool); var new_form: THarvesterForm; begin Application.CreateForm(YourForm,new_form); new_form.WebBrowser.RegisterAsBrowser := true; ppDisp := new_form.WebBrowser.Application; end;
OnPrintTemplateInstallation
TBD
OnPrintTemplateTeardown
TBD
OnPrivacyImpactStateChange
TBD
OnProgressChange
Called to indicate an update in the progress of a download operation.
procedure YourForm.WebBrowser_OnProgressChange( Sender: TObject; Progress, ProgressMax: Integer);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
Progress
- Total progress made so far (number of bytes). -1 if complete.
ProgressMax
- Maximum progress value (number of bytes.)
OnPropertyChange
TBD
procedure YourForm.WebBrowser_OnPropertyChange( Sender: TObject; const szProperty: WideString);
TBD
OnQuit
Called before the browse control terminates.
procedure YourForm.OnQuit(Sender: TObject);
OnSetSecureLockIcon
TBD
procedure YourForm.WebBrowser_OnSetSecureLockIcon( Sender: TObject; SecureLockIcon: Integer);
TBD
OnStartDrag
TBD
procedure YourForm.WebBrowser_OnStartDrag( Sender: TObject; var DragObject: TDragObject);
TBD
OnStatusBar
TBD
procedure YourForm.WebBrowser_OnStatusBar( Sender: TObject; StatusBar: WordBool);
TBD
OnStatusTextChange
Called when the status bar text of the component changes. Informs your application of the message that internet explorer would display in the status bar.
procedure YourForm.OnStatusTextChange( Sender: TObject; const Text: WideString);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
Text
- Text (message) to display in the status bar.
OnTheaterMode
TBD
procedure YourForm.WebBrowser_OnTheaterMode( Sender: TObject; TheaterMode: WordBool);
TBD
OnTitleChange
Called when the title of the page changes.
procedure YourForm.WebBrowser_OnTitleChange( Sender: TObject; const Text: WideString);
Arguments:
Sender
- The TWebBrowser component for which the event is being generated. Usage:
(Sender as TWebBrowser)
Text
- New title bar text.
OnToolBar
TBD
procedure THarvesterForm.WebBrowser_OnToolBar( Sender: TObject; ToolBar: WordBool);
TBD
OnUpdatePage
TBD
OnUpdatePageStatus
TBD
procedure YourForm.WebBrowser_OnUpdatePageStatus( Sender: TObject; const pDisp: IDispatch; var nPage, fDone: OleVariant);
TBD
OnVisible
Called when the Visible property changes.
procedure YourForm.OnVisible( Sender: TObject; Visible: WordBool);
OnWindowClosing
TBD
procedure YourForm.WebBrowser_OnWindowClosing( Sender: TObject; IsChildWindow: WordBool; var Cancel: WordBool);
TBD
OnWindowSetHeight
TBD
procedure YourForm.WebBrowser_OnWindowSetHeight( Sender: TObject; Height: Integer);
TBD
OnWindowSetLeft
Called when the browser wants to change its position (such as when JavaScript code requires the Window to reposition itself).
procedure YourForm.WebBrowser_OnWindowSetLeft( Sender: TObject; Left: Integer);
OnWindowSetResizeable
TBD
procedure YourForm.WebBrowser_OnWindowSetResizeable( Sender: TObject; Resizable: WordBool);
TBD
OnWindowSetTop
TBD
procedure YourForm.WebBrowser_OnWindowSetTop( Sender: TObject; Top: Integer);
TBD
OnWindowSetWidth
TBD
procedure YourForm.WebBrowser_OnWindowSetWidth( Sender: TObject; Width: Integer);
TBD
PopupMenu
TBD
See also: http://msdn.microsoft.com/en-us/library/system.windows.forms.webbrowser_events.aspx.
To report any errors or omissions please e-mail me (brian@cryer.co.uk).
These notes are believed to be correct for Delphi 6 and Delphi 7 with Internet Explorer 6, and may apply to other versions as well.
About the author: Brian Cryer is a dedicated software developer and webmaster. For his day job he develops websites and desktop applications as well as providing IT services. He moonlights as a technical author and consultant.