Brian Cryer

Cry about...
Delphi Programming with TWebBrowser

TWebBrowser
OleObject and Document data

Introduction

The OleObject property exposes the objects internal to TWebBrowser. For full details of the objects accessible see http://msdn.microsoft.com/en-us/library/system.windows.forms.webbrowser_properties.aspx.

Everything that is accessible via the OleObject property is also accessible via the Document property. In general obtaining data via the Document property route is more cumbersome, because it involves using other classes/interfaces, but it does offer better error checking.

The purpose of this page is not to provide comprehensive documentation on OleObject, but to describe those members that I have found useful in the past. For most of these I have aimed to provide the corresponding Document access method. Code fragments are included for illustration only.

Significant or interesting object attributes:

WebBrowser.OleObject.Document

Provides information on the document display. For details see http://msdn.microsoft.com/en-us/library/system.windows.forms.htmldocument.aspx (but be aware that that Microsoft article does not refer to Delphi).

Document equivalent:

WebBrowser.Document as IHTMLDocument2

Note:

  • If no document has been loaded then (WebBrowser.Document as IHTMLDocument2) will be nil. To avoid a run-time exception check the value before using it, for example:
var
  document: IHTMLDocument2;
begin
  document := WebBrowser.Document as IHTMLDocument2;
  if Assigned(document) then
    .
    .
  • For brevity, not all of the examples on this page include this error checking.

WebBrowser. OleObject. Document. All

Array of all the items/objects in the document. This includes images, links, text etc.

.Length Returns the number of elements in the array.
.Item(0) Returns the first document element.
.Item(n).InnerText Read/write the text between the start and end tags of the item.
.Item(n).ScrollIntoView(bAlignToTop: Boolean) Scrolls item 'n' into view. bAlignToTop = true to align it with the top of the window. bAlignToTop = false to align with the bottom of the window.

Document equivalent (including retrieving the first item):

var
  document: IHTMLDocument2;
  docAll: IHTMLElementCollection;
  firstElement: IHTMLElement;
begin
  document := WebBrowser.Document as IHTMLDocument2;
  if Assigned(document) then
  begin
    docAll := document.all;
    firstElement := docAll.Item(0,'') as IHTMLElement;

WebBrowser. OleObject. Document. bgColor

Sets or retrieves the background colour for the document. For example to set the background colour to white:

WebBrowse.OleObject.Document.bgColor := '#FFFFFF';

or to set it to black:

WebBrowse.OleObject.Document.bgColor := '#000000';

WebBrowser. OleObject. Document. Body. Style. overflowX

Read/write string value specifying whether horizontal scroll bar is shown. Values are:

visible Default. No scroll bar. Display is clipped to visible area.
scroll Scroll bar always visible - whether required or not.
hidden No scroll bar. Content outside of visible area is hidden.
auto Content is clipped and scroll bar is displayed if required.

WebBrowser. OleObject. Document. Body. Style. overflowY

As for WebBrowser.OleObject.Document.Body.Style.overflowX but for the vertical scroll bar.

WebBrowser. OleObject. Document. Body. Style. zoom

Sets or retrieves the magnification used. Default is 1, for no magnification. To show at half its normal size use 0.5. To show at twice its normal size use 2.

WebBrowser. OleObject. Document. cookie

Returns a string holding all browser cookies - these are the cookies stored locally and not server side cookies.

Document equivalent:

var
  document: IHTMLDocument2;
  cookies: String;
begin
  document := WebBrowser.Document as IHTMLDocument2;
  if Assigned(document) then
    cookies := document.cookie;

Cookies are represented in the string in the form:

name = value

Note:

  • If there is more than one name/value pair then these are separated by a semi-colon (';').
  • Some characters may be 'escaped' - that is represented by a percent symbol followed by a two digit hexadecimal number representing the ASCII code of the character. For a list of ASCII codes click here.

WebBrowser.OleObject. Document. documentElement. innerHTML

For HTML documents returns the document including its HTML.

WebBrowser.OleObject. Document. documentElement. innerText

Returns the text content of the document - without any (HTML) formatting.

WebBrowser. OleObject. Document. FileSize

Returns the size of the html document in bytes.

Document equivalent:

(WebBrowser.Document as IHTMLDocument2).FileSize

Note:

  1. The document equivalent returns the file size as a string.
  2. It will throw an exception if no page is loaded or if the file is not available in the cache. This means that if the document headers request that the file is not cached then calling FileSize will throw an exception.

WebBrowser.OleObject.Document.Forms

Returns the collection of forms on the page.

.Length Returns the number of forms in the document.
.Item(0) Returns the first form.

Document equivalent:

var
  htmlDoc: IHTMLDocument2;
  allForms: IHTMLElementCollection;
  firstForm: IHTMLFormElement;
begin
  htmlDoc := WebBrowser.Document as IHTMLDocument2;
  allForms := htmlDoc.Forms;
  firstForm := allForms.Item(0,'') as IHTMLFormElement;

See also: How to read and write form elements

WebBrowser. OleObject. Document. Frames

Array of frames in the document.

.Length Returns the number of frames in the document.
.Item(0) Returns the first frame.
.Item(0).Document Returns the document object representing the frame.
.Item(0).Document.URL Returns the URL of the first frame.

Document equivalent:

(WebBrowser.Document as IHTMLDocument2).Frames

for example, to obtain information about a frame as (an IHTMLWindow2 or IHTMLDocument2):

var
  document: IHTMLDocument2;
  ole_index: OleVariant;
  doc_all: IHTMLElementCollection;
  frame_dispatch: IDispatch;
  frame_win: IHTMLWindow2;
  frame_doc: IHTMLDocument2;
begin
  document := WebBrowser.Document as IHTMLDocument2;
  ole_index := 0;
  frame_dispatch := document.Frames.Item(ole_index);
  if frame_dispatch <> nil then
  begin
    frame_win := frame_dispatch as IHTMLWindow2;
    frame_doc := frame_win.document;
      .
      .

WebBrowser. OleObject. Document. Images

Array of images contained in the document.

.Length Returns the number of images in the document.
.Item(0) Returns the first image.
.Item(0).Src Read or write the path to the first image.

WebBrowser. OleObject. Document. LastModified

Returns when the document was last modified, as a string. Officially the format is "MM/DD/YY hh:mm:ss", but in my experience it is normally "MM/DD/YYYY hh:mm:ss" - so the format may well be specific to the local locale settings.

Document equivalent:

var
  htmlDoc: IHTMLDocument2;
  dateString: String;
begin
  htmlDoc := WebBrowser.Document as IHTMLDocument2;
  if Assigned(htmlDoc)
    dateString := html_doc.LastModified;

WebBrowser. OleObject. Document. Links

Array of all links (i.e. "<a href...>" elements).

.Length Returns the number of links.
.Item(0) Returns the first link.
.Item(0).href Returns the address of the first link.
.Item(0).TagName Returns the name of the type of the first link. For links this is always 'A'.

Document equivalent:

var
  htmlDoc: IHTMLDocument2;
  allLinks: IHTMLElementCollection;
  firstLink: IHTMLElement;
  url: String;
begin
  htmlDoc := WebBrowser.Document as IHTMLDocument2;
  allLinks := htmlDoc.Links;
  firstLink := allLinks.Item(0,'') as IHTMLElement;
  url := firstLink.toString;

WebBrowser. OleObject. Document. Location. Protocol

Returns a string representing the 'protocol' portion of the URL. This will (typically) be one of:

Protocol Value Meaning
file: Local or network file.
ftp: FTP.
gopher: Gopher session.
http: Hypertext Transfer Protocol
https: Secure Hypertext Transfer Protocol.
javascript: JavaScript code.
mailto: Client e-mail.
news: Newsgroup.
res: Resource file.
telnet: Telnet terminal login.

WebBrowser.OleObject. Document. ParentWindow

Returns a (read-only) reference to the container window.

WebBrowser. OleObject. Document. ParentWindow. ScrollBy(iX: Integer; iY: Integer)

Scrolls the window horizontally by 'iX' pixels - a negative value scrolls left, a positive value scrolls right. Scrolls the window vertically by 'iY' pixels - a negative value scrolls up and a positive value scrolls down.

Document equivalent:

var
  document: IHTMLDocument2;
  begin
    document := webBrowser.Document as IHTMLDocument2;
    if Assigned(document) then
      document.parentWindow.scrollBy(iX,iY);

Note:

  1. The window will not scroll up/down if it has already reached its normal top/bottom limit. Similarly it will not scroll left/right if it has already reached its normal left/right limit. So for example, when a document is first loaded trying to scroll it by -1,-1 will have no affect.
  2. This has implications for a framed document since typically the top-level document will not scroll even though the frames it contains will. The following procedure illustrates how to scroll every document and frame, including embedded frames:

    procedure ScrollBrowserWindowBy(const window: IHTMLWindow2; iX:Integer; iY:Integer);
    var
      index: Integer;
      oleIndex: OleVariant;
      frameDispatch: IDispatch;
      childWindow: IHTMLWindow2;
      document: IHTMLDocument2;
    begin
      if Assigned(window) then
      try
        window.scrollBy(iX,iY);
        // If there are any frames then try scrolling them.
        document := window.Document as IHTMLDocument2;
        if Assigned(document) then
          for index := 1 to document.Frames.Length do
          begin
            oleIndex := index-1;
            frameDispatch := document.Frames.Item(oleIndex);
            if Assigned(frameDispatch) then
            begin
              childWindow := frameDispatch as IHTMLWindow2;
              ScrollBrowserWindowBy(childWindow,iX,iY);
            end;
          end;
      except
      on E: Exception do begin end;
      end;
    end;

    and to invoke it:

    var
      document: IHTMLDocument2;
    begin
      document := webBrowser.Document as IHTMLDocument2;
      if Assigned(document) then
        ScrollBrowserWindowBy(document.parentWindow,5,10);

  3. If you attempt to call 'scrollBy' for a window frame containing an off-site page then it will throw an "access denied" exception, hence the "try .. except" in the above example.

WebBrowser. OleObject. Document. selection

Provides access to the currently selected portion of the document.

For example, to access the currently selected text:

var
  document: IHTMLDocument2;
  selectionObj: IHTMLSelectionObject;
  selectionRange: IHtmlTxtRange;
  selectedText: String;
begin
  document := WebBrowser.Document as IHTMLDocument2;
  selectionObj := document.selection;
  selectionRange := selectionObj.CreateRange as IHtmlTxtRange;
  selectedText := selectionRange.text;
    .
    .

Note: The above example would need to be modified slightly for a document with frames.

WebBrowser. OleObject. Document. Title

The title of the current document. It will be empty if the HTML in the document does not specify a title.

WebBrowser. OleObject. Document. URL

The URL of the current document. This is the same as the property LocationURL.

See also:

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.