You are currently viewing a snapshot of www.mozilla.org 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 www.mozilla.org, please file a bug.

Skip to main content

NGLayout Embedding APIs

Last updated by Rick Potts on 10/25/98

Document activation...

NGLayout provides a simple, extensible document activation framework which allows heterogeneous data viewers to be hosted by a generic container (such as the WebShell).

Document activation involves interactions between three distinct components. A content viewer (nsIContentViewer interface) which is capable of processing the given content type.  The content viewer container (nsIContentViewerContainer interface) which will host the particular nsIContentViewer instance. And the document loader factory (nsIDocumentLoaderFactory interface) which is used to instantiate the content viewer.

In general, document activation involves the following steps:

  1. The appropriate nsIDocumentLoaderFactory::CreateInstance(...) is called with a content type, command and nsIContentViewerContainer.

  2. The factory creates a content viewer instance and returns both the nsIContentViewer and an nsIStreamListener which acts as the data sink.

  3. At this point the new content viewer can be embedded in the container by calling nsIContentViewerContainer::Embed(...)
The diagram below illustrates these interactions:

Activation commands...

When activating a document, an activation command is provided in addition to the content type of the data.  This command specifies an action to perform on the data and is represented as a character string. Currently, this action is always View and acts as a place holder.  However, in the future more commands may be added such as the following:

    • Edit

    • Print

    • etc...

Document loader factory...

For each supported data type a factory object is registered which supports the nsIDocumentLoaderFactory interface.  This factory is responsible for the following:

  1. Instantiating a content viewer capable of handling the specified content type and command.  In most cases a document object will be created to process the input data.  However, this document abstraction is an implementation detail of the content viewer and is not exposed by the document activation APIs.

  2. Binding the document and its content viewer together (if necessary).

  3. Returning a nsIStreamListener which will accept data from the input stream.

  4. Returning a nsIContentViewer which is responsible for rendering the data.

Negotiations between the content viewer and its container...

Communication between a content viewer and its container is performed via the QueryCapability(...) method on the nsIContentViewerContainer interface. This method allows the content viewer to ask its container if it can supply an implementation of a given interface.  The rules for QueryCapability() are less restrictive than those for nsISupports::QueryInterface(...) in that the returned interface is not necessarily implemented (or aggregated) by the container.  This means that the returned interface, it is not necessarily capable of returning the original container by calling nsISupports::QueryInterface(...).

nsIContentViewer Interface

Init Initialize a content viewer instance.  The content viewer is made a child of the given native window.
SetContainer Set the nsIContentViewerContainer for the content viewer.
GetContainer Returns the nsIContentViewerContainer.
GetBounds Returns the current bounding rectangle.
SetBounds Set the bounding rectangle for the viewer.
Move Move the viewer within the container.
Show Make the content viewer visible.
Hide Make the content viewer invisible.

nsIContentViewerContainer Interface

QueryCapability Asks the container whether it (or a delegate) implements the requested interface.  This is similar to nsISupports::QueryInterface(...) however, its semantics are less restrictive.  The returned component is not necessarily aggregated by the ContentViewerContainer.  Therefore, it is not assumed that one can QueryInterface(...) back to the container...
Embed Embed the specified content viewer into the container.

nsIDocumentLoaderFactory Interface

CreateInstance Create a content viewer instance (based on the specified content type and command) and return an nsIStreamListener capable of consuming the input data.

Document loader...

NGLayout provides a Document Loader component which orchestrates the activation process for a collection of related URLs which represent a document. This allows related URLs to have the same attributes applied when they are loaded and to provide notifications when the entire document has been loaded.

Document loaders may be nested depending on the structure of the document which they represent.  For example, if the document being loaded contains an HTML frame set, then child document loaders will be created for each frame.

The Document Loader performs the following steps during a document activation...

  1. When nsIDocumentLoader::LoadDocument() is called, the loader initiates an asynchronous request to load the specified URL.

  2. Once the content type of the URL has been determined the document loader is notified.  It tries to locates a nsIDocumentLoaderFactory for the given content type..

  3. This factory is asked to provide nsIContentViewer and nsIStreamListener interfaces...

  4. The nsIStreamListener interface is associated with the network request. As data is received for the URL, notifications are sent to the nsIStreamListener.

  5. The nsIContentViewerContainer is told to embed the nsIContentViewer.

  6. When the last URL associated with the document loader has been loaded (or aborted) an OnConnectionsComplete notification is fired via the nsIDocumentLoaderObserver interface.

nsIURLGroup Interface

CreateURL Create a new nsIURL component which belongs to this nsIURLGroup. The new URL will inherit the same nsILoadAttribs as those for the nsIURLGroup.
OpenStream Initiate an asynchronous URL load for one of the URLs belonging to this nsIURLGroup.
GetDefaultLoadAttributes Returns the nsILoadAttribs which represents the current default load attributes for all URLs in the nsIURLGroup.
SetDefaultLoadAttributes Set the default nsILoadAttribs.
AddChildGroup Add a new nsIURLGroup as a child of the current nsIURLGroup. Each child group receives the same default load attributes as its parent.
RemoveChildGroup Remove a child from the nsIURLGroup.

nsIDocumentLoader Interface

LoadDocument Initiate the loading of a document.
Stop Stop the loading of any URLs associated with the current document.
IsBusy Returns whether the document loader or any of its children are currently loading any URLs.
CreateDocumentLoader Create a child document loader.
SetDocumentFactory
AddObserver Add a observer for nsIDocumentLoaderObserver notifications.
RemoveObserver Remove an existing observer...

nsIDocumentLoaderObserver Interface

OnConnectionsComplete Notification that all of the URLs associated with a document have been loaded.

WebShell component...

The WebShell is an extensible document container which is currently capable of hosting NGLayout documents.  The WebShell is designed to be easily embedded in host applications.  It also provides much of the default behavior expected of a Web Browser.

The WebShell encapsulates the underlying NGLayout subsystems and exposes a collection of interfaces which allow developers to customize its behavior.

The WebShell itself is a chromeless window.  However, in certain circumstances it is necessary to access the outer chrome of the window which contains the WebShell.  For example, this type of access is necessary for javascript manipulation of window chrome. This access is accomplished via the nsIBrowserWindow interface which the WebShell will occasionally call...  The nsIBrowserWindow is an interface which abstractly represents the top level window containing the outermost WebShell instance.

It is important to remember that while there may be many nested WebShells representing a document only the outermost WebShell container supports the nsIBrowserWindow interface.  Below is a diagram which illustrates the relationships between nested documents, WebShells and document loaders.


nsIWebShell Interface

Init Initialization function for a WebShell instance.  This method provides information needed by the WebShell to embed itself inside of a native window provided by the caller. It is assumed that this function will be called only once.
Destroy Notify the WebShell that its parent's window is being destroyed. After being destroyed, a WebShell is no longer visible and can no longer display documents.
GetBounds Return the current dimensions of the WebShell.
SetBounds Resize the WebShell to the given dimensions.
MoveTo
Show Make the WebShell visible.
Hide Make the WebShell invisible.
SetFocus Give the WebShell window focus.
RemoveFocus
Repaint Force the WebShell to repaint its window.
SetContentViewer Set the nsIContentViewer for the WebShell.
GetContentViewer Return the current nsIContentViewer embedded within the WebShell.
SetContainer Set the nsIWebShellContainer for the WebShell.
GetContainer Return the current nsIWebShellContainer.
SetObserver Set the nsIStreamObserver which receives all notifications from URLs loaded by the document.
GetObserver Return the current nsIStreamObserver.
SetPrefs Set the nsIPref used to get/set preference values...
GetPrefs Return the current nsIPref interface.
GetRootWebShell Return the root WebShell instance.  Since WebShells can be nested (when frames are present for example) this instance represents the outermost WebShell.
SetParent Set the parent WebShell.
GetParent Return the parent WebShell.
GetChildCount Return the current number of WebShells which are immediate children of the current WebShell.
AddChild Add a new child WebShell.
ChildAt Return the child WebShell at the requested index.
GetName Return the name of the current WebShell.
SetName Set the name of the current WebShell.
FindChildWithName Return the child WebShell with the specified name.
GetDocumentLoader Return the nsIDocumentLoader associated with the WebShell.
LoadURL Load the document associated with the specified URL into the WebShell.
Stop Stop loading the current document.
Reload Reload the current document.
CanBack Return whether the current WebShell can go back in its history list.
Back Load the previous document in the history list.
CanForward Return whether the current WebShell can go forward in its history list.
Forward Load the next document in the history list.
GoTo Load the document at the specified index in the history list.
GetHistoryIndex Return the current index in the history list.
GetURL Return the name of the URL at the specified history index.
GetTitle Return the title of the nsIBrowserWindow containing the WebShell.
SetTitle Set the title of the nsIBrowserWindow containing the WebShell.
GetMarginWidth
SetMarginWidth
GetMarginHeight
SetMarginHeight

nsIWebShellContainer Interface

WillLoadURL Notification that a URL load has been requested.  The URL load may be modified or canceled.
BeginLoadURL Notification that a URL load has begun.
ProgressLoadURL Progress notification for the URL load.
EndLoadURL Notification that a URL load has been completed.
NewWebShell Create a new top level WebShell.
FindWebShellWithName Find a WebShell with the specified name.

nsIBrowserWindow Interface

Init
MoveTo Move the top level window to the specified location.
SizeTo Resize the top level window to the specified size.
GetBounds
GetWindowBounds
Show Show the top level window.
Hide Hide the top level window.
Close Close the top level window.
SetChrome Toggles the presence of various pieces of chrome on the top level window. (i.e.. toolbar, status bar, ...)
GetChrome Return the current chrome mask which describes which types of window chrome are currently available.
SetTitle Set the title of the top level window.
GetTitle Return the current title of the top level window.
SetStatus Set the status text for the top level window.
GetStatus Return the current status text...
SetProgress Set the progress bar on the top level window.
GetWebShell Return the outermost nsIWebShell which is contained in the top level window.

Some future API changes...

  • Split the nsIWebShell interface into two distinct interfaces.  The base interface should derive from nsIContentViewerContainer and implement the methods necessary for nested content viewer support.  The history and other APIs should move to either distinct interfaces or a higher level interface which derives from nsIWebShell.

  • Unify the naming and arguments for:

    • GetBounds(...)

    • SetBounds(...), SizeTo(...), Move(...) and MoveTo(...)

    • Show(...)

    • Hide(...)

  • Remove nsIWebShell::RemoveFocus(...).

  • Remove nsIWebShell::SetContentViewer(...).  This is currently only being used to clear the content viewer...  nsIWebShell::Destroy(...) should be used instead.

  • Move nsIContentViewer::BindToDocument(...) into the nsIDocumentViewer interface.

  • Remove the nsIStreamListener** argument from nsIDocumentLoaderFactory::CreateInstance(...).

  • Add a GetStreamListener(...) method to the nsIContentViewer interface.

  • Add a RemoveChild(...) method to nsIWebShell.

  • Rename the nsIRefreshUrl interface to nsIRefreshURL.

  • Rename nsIWebShell::GetURL(...) to something like GetURLAtIndex(...).

  • Remove the localIP argument from nsIWebShell::LoadURL(...).  Move this functionality into the nsILoadAttribs interface.

Some open API issues...

  • Should the URL notifications in the nsIWebShellContainer move to the nsiDocumentLoaderObserver interface?

  • Should the nsIDocumentLoader be derived from the nsIURLGroup interface?

  • Should there be a nsIWebShell::GetBrowserWindow(...) method?