TWebBrowser OleObject and Document data

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/workshop/author/dhtml/reference/objects.asp.

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
WebBrowser.OleObject.Document.All
WebBrowser.OleObject.Document.bgColor
WebBrowser.OleObject.Document.Body.Style.overflowX
WebBrowser.OleObject.Document.Body.Style.overflowY
WebBrowser.OleObject.Document.Body.Style.zoom
WebBrowser.OleObject.Document.cookie
WebBrowser.OleObject.Document.documentElement.innerHTML
WebBrowser.OleObject.Document.documentElement.innerText
WebBrowser.OleObject.Document.FileSize
WebBrowser.OleObject.Document.Frames
WebBrowser.OleObject.Document.Images
WebBrowser.OleObject.Document.LastModified
WebBrowser.OleObject.Document.Links
WebBrowser.OleObject.Document.Location.Protocol
WebBrowser.OleObject.Document.ParentWindow
WebBrowser.OleObject.Document.ParentWindow.ScrollBy(iX: Integer; iY: Integer)
WebBrowser.OleObject.Document.selection
WebBrowser.OleObject.Document.Title
WebBrowser.OleObject.Document.URL

--------------------------------------------------------------------------------

WebBrowser.OleObject.Document
Provides information on the document display. For details see http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_document.asp.

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:

var
 document: IHTMLDocument2;
 docAll: IHTMLElementCollection;
begin
 document := WebBrowser.Document as IHTMLDocument2;
 if Assigned(document)
   docAll := document.all;

--------------------------------------------------------------------------------

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 that the document equivalent returns the file size as a string and it will throw an exception if no page is loaded.


--------------------------------------------------------------------------------

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

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:

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.
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);

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. This is the same as the property LocationName.


--------------------------------------------------------------------------------

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


--------------------------------------------------------------------------------

See also:

http://msdn.microsoft.com/workshop/author/dhtml/reference/objects.asp
http://msdn.microsoft.com/workshop/author/dhtml/reference/objects/obj_document.asp.
http://www.swissdelphicenter.com/en/tipsbycomp.php?component=Webbrowser
http://members.shaw.ca/iedelphi/webbrowser.htm

--------------------------------------------------------------------------------

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.