Brian Cryer

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):

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: 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.