You are currently viewing a snapshot of taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to, please file a bug.

1.Table of Contents

1.     Table of Contents. 1

2.     Introduction. 2

1.1       Overview.. 2

1.2       Principal embedding objects. 4

1.2.1        Docshell Object 5

1.2.2        WebBrowser Object 6

1.2.3        Webbrowser site object 7

2      Major Interfaces. 8

2.1       Interface: nsIBaseWindow.. 8

2.1.1        Implemented by. 8

2.1.2        Source. 8

2.2       Interface: nsIContentViewerContainer 8

2.2.1        Notes. 8

2.2.2        Implemented by. 9

2.2.3        Source. 9

2.3       Interface: nsIDocShell 9

2.3.1        Implemented by. 9

2.3.2        Source. 9

2.4       Interface: nsIDocShellTreeItem.. 9

2.4.1        Implemented by. 9

2.4.2        Source. 9

2.5       Interface: nsIDocShellTreeNode. 9

2.5.1        Implemented by. 9

2.5.2        Source. 9

2.6       Interface: nsIDocShellTreeOwner 9

2.6.1        Implemented by. 9

2.6.2        Source. 9

2.7       Interface: nsIInterfaceRequestor 9

2.7.1        Implemented by. 9

2.7.2        Source. 9

2.8       Interface: nsIPrompt 10

2.8.1        Implemented by. 10

2.8.2        Source. 10

2.9       Interface: nsIRefreshURI 10

2.9.1        Implemented by. 10

2.9.2        Source. 10

2.10     Interface: nsIScriptGlobalObjectOwner 10

2.10.1      Implemented by. 10

2.10.2      Source. 10

2.11     Interface: nsIScrollable. 10

2.11.1      Implemented by. 10

2.11.2      Source. 10

2.12     Interface: nsIStreamObserver 10

2.12.1      Implemented by. 10

2.12.2      Source. 10

2.13     Interface: nsITextScroll 10

2.13.1      Implemented by. 10

2.13.2      Source. 10

2.14     Interface: nsIWebBrowser 10

2.14.1      Implemented by. 11

2.14.2      Source. 11

2.15     Interface: nsIWebBrowserChrome. 11

2.15.1      Implemented by. 11

2.15.2      Source. 11

2.16     Interface: nsIWebNavigation. 11

2.16.1      Implemented by. 11

2.16.2      Source. 11

2.17     Interface: nsIWebProgress. 11

2.17.1      Implemented by. 11

2.17.2      Source. 11

2.18     Interface: nsIWebProgressListener 11

2.18.1      Implemented by. 11

2.18.2      Source. 11

3      Developing third party applications using the embedding interfaces. 11

3.1.1        Header files and libraries. 11

3.1.2        Initialisation. 11

3.1.3        Closing down. 12

3.1.4        Creating the WebBrowser object 12

3.1.5        Getting the root docshell 12

3.1.6        Subscribing to events. 12

3.1.7        Browsing to a URL. 12

3.1.8        Clipboard operations. 12

3.1.9        Receiving context menu notifications. 12


This document describes the programmable interface for embedding Gecko into third party applications.

It discusses the webbrowser and docshell objects and the interfaces that must be used control them.

Terms such as XPCOM, CID, interface and IDL are sprinkled liberally throughout. If you are unfamiliar with XPCOM then read through to get an idea with what the terms mean. Windows programmers familiar with COM/ActiveX should be understand XPCOM because the two are closely related.

Italics are used to represent draft notes.

1.1    Overview

When you start Mozilla, a browser window appears. This is made up of frames representing the chrome, content, side panel, buttons and so on. Frames are nested inside other frames to form a hierarchy. The root frame represents the browser window with sub-frames managing each discrete component. Each frame is associated with a document which is it's content.

Content is trusted or untrusted. Trusted content is known as chrome, usually loaded from local store with greater privileges to interact with the host machine. Usually the topmost frames are chrome and contain a content sub-frames.

Until recently the object responsible for managing a frame and the associated document was called the webshell. The topmost webshell was controlled by the host application and each child was managed in turn by its parent webshell.

Figure 1: How it used to be done

The webshell had methods for child and parent webshell traversal. It also had methods for sizing and positioning, loading and refreshing documents, back and forward navigation, chrome, registering progress callbacks, setting preferences and much more besides. As you can imagine, webshell became very complicated and bloated.  Even worse, all the exposed methods were defined on a single interface! The nsIWebShell interface had over 30 methods and properties and it was practically impossible to make it immutable because it kept changing so much. It was clear that Mozilla would be much better if webshell could be rewritten.

Take a look here to see how many methods were added to nsIWebShell between during its lifetime. You may also notice that nsIWebShell was defined in C++ rather than being generated from IDL. This prevented it from being used by XPConnect, lead to all kinds of XPCOM abuses and meant the in/out semantics of the methods were vague to say the least.

Travis Bogard initiated a redesign of the webshell object and the nsIWebShell interface. Methods were broken out into new, more logical interfaces and functionality from webshell was rewritten cleanly into a new base class called the docshell. Embedding-specific functionality was moved into a new object called the webbrowser.

The docshell is a clean replacement for webshell focussing on functionality required by each node in the hierarchy. The webbrowser object is used by client applications that want to do embedding.

The name docshell is a more suitable name for an object that manages a document rather than a webshell, which implies an HTML document. A docshell can hold any type of document though that normally it holds one that can be parsed and represented by a DOM. HTML or XML that is parsed into a DOM, is managed by a docshell during its lifetime.

Figure 2:  Docshell hierarchy

The new design splits the embedding specific stuff away from the document traversal interfaces, so that only the topmost document that directly touches the embedding client app contains the subscription and notification code needed to keep the client informed of what is going on.

Each docshell manages one document that is set onto the docshell during or after it has been loaded. Loading is initiated by navigation interface methods on the docshell. The docshell specifies the presentation area and context into which the document is drawn, whether the context has scroll bars, whether it represents chrome or content, whether it supports plugins, and whether it has parent and child docshells.

Webshell has not gone away entirely but is slowly atrophying as more and more stuff is moved into the docshell base class. Eventually the webshell object and the nsIWebShell interface will disappear. Neither webshell or nsIWebShell are documented here to discourage their use.

1.2    Principal embedding objects

Here is an overview of the principle embedding objects.

Figure 3 Embedding objects and their principal interfaces

1.2.1    Docshell Object  Class: nsDocShell

The docshell XPCOM object is implemented by the nsDocShell C++ class.

This class is responsible for initiating the loading and viewing of a document.

In the case of loading a URI, the docshell creates a URI loader object, instructs it to fetch content and listens content arriving via a helper object nsDSURIContentListener. When the first content arrives, the docshell creates a content viewer object that is responsible for rendering it.

When SetDocument is called on the docshell, specifying a new DOM to display, it creates a new document and document view to manage it and then associates the viewer with docshell. Next it associates the root node of the DOM with the document object through each presentation shell of the document sizing the presshell to be the same size as the docshell. Once completed it fires an EndDocumentLoad event to notify observers that a document has loaded.

A docshell is an XPCOM object controlled via the interfaces it exposes. It possesses methods to load new content, to change the current document it holds onto, to see the current scroll bar positions and affect the scroll view methods, to get its parent and child docshells to be re  Sequence diagrams

TODO Add more sequence diagrams

When a document is requested (e.g. by telling the docshell to load a particular URL), the docshell kicks off the process that ultimately leads to a content viewer being created that displays the document content into a presentation shell.

Figure 4 Loading Sequence  Interfaces implemented by docshell

  • nsIDocShell
  • nsIDocShellTreeItem
  • nsIDocShellTreeNode
  • nsIWebNavigation
  • nsIWebProgress
  • nsIBaseWindow
  • nsIScrollable
  • nsITextScroll
  • nsIContentViewerContainer
  • nsIInterfaceRequestor
  • nsIScriptGlobalObjectOwner
  • nsIRefreshURI

1.2.2    WebBrowser Object  Class: nsWebBrowser

The webbrowser object is implemented by the C++ class nsWebBrowser. Embedding clients must create an instance of this class to embed Gecko into their applications.

The principle interface on this object is nsIWebBrowser. This interface has methods and attributes that client may use to load content and register callback interfaces to receive progress and navigation notifications.

Functionality is broken down into separate interfaces, so that web navigation functionality is distinct for that used to position or size the webbrowser component which is different from that used to scroll the display. This is in contrast to the monolithic nsIWebShell where everything was on the one interface.

For every webbrowser that client instantiates, it must also create a companion container/site object that handles callbacks that the webbrowser needs to function correctly.

The webbrowser site object is an XPCOM object that receives calls through the interfaces it implements when the before/during/after loading, when the webbrowser wants the site to be resize, for progress notifications and so on.  Sequence diagrams


getting docshell

registering listeners  Interfaces implemented by WebBrowser

  • nsIWebBrowser
  • nsIWebNavigation
  • nsIBaseWindow
  • nsIWebProgress
  • nsIScrollable
  • nsITextScroll
  • nsIDocShellTreeItem

1.2.3    Webbrowser site object

This object must be implemented by the client application to interact with the webbrowser object. It’s referred to here as a site object but is sometimes called a container elsewhere.

The interfaces on this object make it the owner of the docshell hierarchy and capable of receiving callbacks when a document is being loaded or when the content wishes to display some user interaction such as to display a message box.

Figure 5: The webbrowser and the associated site  Sequence diagrams

TODO  Implemented by the webbrowser site

 Most of these interfaces should be optional but they are not. Webbrowser and docshell should be modified to be more tolerant of missing interface on the site object because it is such a pain for embedders to write one.

  • nsIBaseWindow - I’m not sure why this interface is needed
  • nsIWebBrowserChrome -
  • nsIWebProgressListener
  • nsIStreamObserver
  • nsIURIContentListener
  • nsIDocumentLoaderObserver - Obselete
  • nsIDocShellTreeOwner
  • nsIInterfaceRequestor
  • nsIPrompt - Optional

2      Major Interfaces

2.1    Interface: nsIBaseWindow

Widget containers implement this interface. It contains methods for creating, destroying, initialising, resizing and moving a window.

2.1.1    Implemented by

  • Webbrowser
  • Webbrowser site

2.1.2    Source

2.2    Interface: nsIContentViewerContainer

A content viewer container implements this interface. It contains a single method that is called when to insert a content viewer object into the container.

2.2.1    Notes

Not defined as an IDL file when it should be!

2.2.2    Implemented by

  • Docshell

2.2.3    Source

2.3    Interface: nsIDocShell

The docshell object implements this interface. The interface contains methods to set the contained document, load a URI, register handlers and listeners.

2.3.1    Implemented by

  • Docshell

2.3.2    Source

2.4    Interface: nsIDocShellTreeItem

Items in the docshell tree hierarchy implement this interface. It contains methods for getting the parent item and named children. It also contains properties to indicate whether the item represents chrome or content.

2.4.1    Implemented by

  • Webbrowser
  • Docshell

2.4.2    Source

2.5    Interface: nsIDocShellTreeNode

Items in the docshell tree hierarchy implement this interface. It contains methods to add, remove and enumerate through child nodes.

2.5.1    Implemented by

  • Webbrowser
  • Docshell

2.5.2    Source

2.6    Interface: nsIDocShellTreeOwner

The owner of a docshell tree hierarchy implements this interface. The interface contains methods to locate named docshells, callbacks to request sizing. Implemented by the owner of the docshell tree.

2.6.1    Implemented by

  • Webbrowser site

2.6.2    Source

2.7    Interface: nsIInterfaceRequestor

The nsIInterfaceRequestor allows an object to return

2.7.1    Implemented by

  • Webbrowser site

2.7.2    Source

2.8    Interface: nsIPrompt

Allows the client to implement its own version of the dialogs that Gecko may need to display such as when a user goes from a secure to a non-secure page, or when page loading times out.

2.8.1    Implemented by

  • Webbrowser site – or a helper object via nsIInterfaceRequestor

2.8.2    Source

2.9    Interface: nsIRefreshURI

Docshell objects implement this interface. It contains methods to set and cancel content refresh timers.

2.9.1    Implemented by

  • Docshell

2.9.2    Source

2.10   Interface: nsIScriptGlobalObjectOwner

Method to return the global script object

2.10.1Implemented by

  • Docshell


2.11   Interface: nsIScrollable

Methods for obtaining the current scrollbar positions and properties for affecting their behavior.

2.11.1Implemented by

  • Docshell


2.12   Interface: nsIStreamObserver

2.12.1Implemented by

  • Webbrowser site


2.13   Interface: nsITextScroll

Methods to scroll the display up or down by lines or pages.

2.13.1Implemented by

  • Docshell


2.14   Interface: nsIWebBrowser

Properties for the client to register listeners and to obtain the nsIDocShell of the root object.

2.14.1Implemented by

  • Webbrowser


2.15   Interface: nsIWebBrowserChrome

The content may request that your container behaves in a certain way, such as to show itself modally, or to hide certain decorations, such as status bars. This is the interface that such requests will be made through.

2.15.1Implemented by

  • Webbrowser site


2.16   Interface: nsIWebNavigation

Interface used for web navigation. Contains methods for loading new URIs, stopping loading, reloading, back/forward history, properties indicating the current URI, the root document.

2.16.1Implemented by

  • Webbrowser
  • Docshell


2.17   Interface: nsIWebProgress

Methods to register an nsIWebProgressListener interface that will be called with notification of the current state of downloads.

2.17.1Implemented by

  • Webbrowser
  • Webbrowser site


2.18   Interface: nsIWebProgressListener

This interface is called during loading to indicate the current loading progress.

2.18.1Implemented by

  • Webbrowser site


3      Developing third party applications using the embedding interfaces

3.1.1    Header files and libraries


3.1.2    Initialisation

Before you can create a browser object, you must initialise your application for embedding:


If your application runs outside the Mozilla bin directory. You must specify the path as a parameter so that Gecko can locate the components it needs to work.

For example:

const char *szPath = “/usr/local/mozilla/bin”;

3.1.3    Closing down



3.1.4    Creating the WebBrowser object

The webbrowser component is instantiated via its class ID (CID) or its program ID (PROGID). The PROGID is a human-readable character string equivalent to the CID for scripting languages who cannot represent a CID as a primitive. Generally speaking the CID should be used in C++ since it is a non-ambiguous way to specify an object.

3.1.5    Getting the root docshell

The root docshell is the topmost frame of content. You need this if you want to load content from a particular URI, parse the DOM and pretty much everything else. The webbrowser manages this object so you don’t have to, but you need to store it to do anything useful.

3.1.6    Subscribing to events

It was already been shown that docshells are nested and that the embedding client connects to the topmost one via the webbrowser. The client application must register a site object with the webbrowser that contains callbacks XXXX

3.1.7    Browsing to a URL

Use the nsIWebNavigation interface off of the root docshell to load a specified URL.

Call LoadURI(), passing the URL as a parameter, e.g.

nsCOMPtr<nsIWebNavigation> webNav = do_QueryInterface(mRootDocShell);

3.1.8    Clipboard operations

Clipboard operations are available from the context viewer. The nsIContentViewerEdit interface has methods for copying, pasting, cutting and selecting text, e.g.

nsCOMPtr<nsIContentViewer> viewer;
nsCOMPtr<nsIContentViewerEdit> edit(do_QueryInterface(viewer));

3.1.9    Receiving context menu notifications

Some clients need to be notified when a user right-mouse clicks on a link or other element so that a popup menu can be displayed. A client can receive this notification by implementing nsIContextMenuListener on their webbrowser site object, or providing it via the nsIInterfaceRequestor interface.