mazilla mozilla
Introduction
What's mozilla
Purpose of this page
Characteristics of mozilla
Survey of mozilla
Module
Web tool
Technology of mozilla
Other resource
Building mozilla
Construction of environment
for building
Checkout of source
Procedure for building
Image of after-building
Execute mozilla
Embedding
What's embedding
Concept of embedding
Structure of PPBrowser
Analysis of PPBrowser
Structure of embedding
Structure of marbrow
Analysis of marbrow
Fizzilla
What's fizzilla
Build fizzilla
Embedding of fizzilla
FAQ
Talk with Mr. Yatsugi

Structure of embedding

Let's sort out embedding !!


On this section, I sort out the structure, procedure, some notices and so on of embedding on the basis of the result of analyzing PPBrowser.


Initializing

Initializing process necessary to embedding is

  • to initialize Macintosh Toolbox related matters
  • to initialize embedding library

Initializing association with Toolbox

PPBrowser initializes Macintosh Toolbox for itself. But, in nsStdLib.shlb, there is a convenient function "InitializeMacToolbox()" and it is better to use it. Its source is in macstdlibextras.c of mozilla/lib/mac/NSStdLib/NSStdLib.mcp.

void InitializeMacToolbox(void)
{
    // once only, macintosh specific initialization
    static Boolean alreadyInitialized = false;
    if (!alreadyInitialized)
    {
        long CMMavail = 0;

        alreadyInitialized = true;
#if !TARGET_CARBON
// pinkerton - don't need to init toolbox under Carbon.
// They finally do that for us!
        InitGraf(&qd.thePort);
        InitFonts();
        InitWindows();
        InitMenus();
        TEInit();
        InitDialogs(0);
        InitCursor();
        Gestalt(gestaltContextualMenuAttr, &CMMavail);
        if ((CMMavail == gestaltContextualMenuTrapAvailable) &&
            ((long)InitContextualMenus != kUnresolvedCFragSymbolAddress))
          InitContextualMenus();

        InitTSMAwareApplication();
    
        // init QuickTime if we have it
        if ((long)EnterMovies != kUnresolvedCFragSymbolAddress)
            EnterMovies();
#endif
#if DEBUG
        InitializeSIOUX(false);
#endif
    }
}

#if DEBUG

#include <SIOUX.h>

void InitializeSIOUX(unsigned char isStandAlone)
{
    SIOUXSettings.initializeTB = isStandAlone;
    SIOUXSettings.standalone = isStandAlone;
    SIOUXSettings.setupmenus = isStandAlone;
    SIOUXSettings.autocloseonquit = true;
    SIOUXSettings.asktosaveonclose = false;
    SIOUXSettings.showstatusline = false;

    if (isStandAlone)
    {
        SIOUXSettings.toppixel = 42;
        SIOUXSettings.leftpixel = 6;
        SIOUXSettings.rows = 40;
        SIOUXSettings.columns = 82;
    }
    else
    {
        SIOUXSettings.toppixel = 480;
        SIOUXSettings.leftpixel = 4;
        SIOUXSettings.rows = 20;
        SIOUXSettings.columns = 100;
    }

    //InstallConsole();
}

#endif

Initializing embedding library

For initializing/terminating embedding library,

nsresult NS_InitEmbedding(nsILocalFile *mozBinDirectory,
                           nsIDirectoryServiceProvider *appFileLocProvider);

nsresult NS_TermEmbedding();

are used.

These definitions are in nsEmbedAPI.h and these entities are in EmbedAPI.o and EmbedAPIDebug.o. Because these are not created by default building of mozilla itself, after building mozilla, you must build these for yourself by

mozilla/embedding/base/macbuild/EmbedAPI.mcp

Once, these processes must be done all manually, but now, it becomes convenient.

Their source is in nsEmbedAPI.cpp of the above-mentioned project. For reference, I show its contents below. It's the good example of initializing XPCOM, getting singleton services and so on.

nsresult NS_InitEmbedding(nsILocalFile *mozBinDirectory,
                          nsIDirectoryServiceProvider *appFileLocProvider)
{
    nsresult rv;

    // Reentrant calls to this method do nothing except increment a counter
    sInitCounter++;
    if (sInitCounter > 1)
        return NS_OK;

    // Initialise XPCOM
#ifdef HACK_AROUND_NONREENTRANT_INITXPCOM
    // Can't call NS_InitXPCom more than once or things go boom!
    if (!sXPCOMInitializedFlag)
#endif
    {
        // Initialise XPCOM
        NS_InitXPCOM(&sServiceManager, mozBinDirectory);
        if (!sServiceManager)
            return NS_ERROR_NULL_POINTER;
        
        // Hook up the file location provider - make one if nsnull was passed
        if (!appFileLocProvider)
        {
            appFileLocProvider = new nsAppFileLocationProvider;
            if (!appFileLocProvider)
                return NS_ERROR_OUT_OF_MEMORY;
            NS_ADDREF(appFileLocProvider);
        }
        NS_WITH_SERVICE(nsIDirectoryService, directoryService, NS_DIRECTORY_SERVICE_CONTRACTID, &rv);
        if (NS_FAILED(rv))
            return rv;
        rv = directoryService->RegisterProvider(appFileLocProvider);
        if (NS_FAILED(rv))
            return rv;
        NS_RELEASE(appFileLocProvider); // RegisterProvider did AddRef - It owns it now 
        
#ifdef HACK_AROUND_NONREENTRANT_INITXPCOM
        sXPCOMInitializedFlag = PR_TRUE;
        sXPCOMCleanupHack.mCleanOnExit = PR_TRUE;
#endif
    }

    // Register components
    if (!sRegistryInitializedFlag)
    {
        // XXX hack method
        NS_SetupRegistry();
        
        rv = nsComponentManager::AutoRegister(nsIComponentManager::NS_Startup,
                                              NULL /* default */);
        if (NS_FAILED(rv))
        {
            NS_ASSERTION(PR_FALSE, "Could not AutoRegister");
            return rv;
        }

        sRegistryInitializedFlag = PR_TRUE;
    }

    // Create the Event Queue for the UI thread...
    //
    // If an event queue already exists for the thread, then 
    // CreateThreadEventQueue(...) will fail...
    // CreateThread0ueue(...) will fail...
    nsCOMPtr<nsIEventQueueService> eventQService;
    rv = sServiceManager->GetService(NS_EVENTQUEUESERVICE_CONTRACTID, 
                                     nsIEventQueueService::GetIID(), 
                                     getter_AddRefs(eventQService));
    if (NS_FAILED(rv))
      return rv;

    eventQService->CreateThreadEventQueue();

#ifdef HACK_AROUND_THREADING_ISSUES
    // XXX force certain objects to be created on the main thread
    nsCOMPtr<nsIStringBundleService> sBundleService;
    rv = sServiceManager->GetService(NS_STRINGBUNDLE_CONTRACTID,
                                     nsIStringBundleService::GetIID(), 
                                     getter_AddRefs(sBundleService));
    if (NS_SUCCEEDED(rv))
    {
        nsCOMPtr<nsIStringBundle> stringBundle;
        char*  propertyURL = "chrome://necko/locale/necko.properties";
        nsILocale *locale = nsnull;
        rv = sBundleService->CreateBundle(propertyURL, locale,
                                          getter_AddRefs(stringBundle));
    }
#endif

    // Init the chrome registry.
    nsCOMPtr<nsIChromeRegistry> chromeReg;
    rv = sServiceManager->GetService("@mozilla.org/chrome/chrome-registry;1", 
                                     nsIChromeRegistry::GetIID(), 
                                     getter_AddRefs(chromeReg));
    if (chromeReg)
    {
        // Ignore the return value here.  If chrome is already initialized
        // this call will return an error even though nothing is wrong.
        (void) chromeReg->CheckForNewChrome();
    }
    return NS_OK;

}

nsresult NS_TermEmbedding()
{
    // Reentrant calls to this method do nothing except decrement a counter
    if (sInitCounter > 1)
    {
        sInitCounter--;
        return NS_OK;
    }
    sInitCounter = 0;

    {
        nsCOMPtr<nsIEventQueueService> eventQService;
        sServiceManager->GetService(NS_EVENTQUEUESERVICE_CONTRACTID, 
                                    nsIEventQueueService::GetIID(), 
                                    getter_AddRefs(eventQService));
        if (eventQService)
            eventQService->DestroyThreadEventQueue();
    }

    NS_RELEASE(sServiceManager);

    // Terminate XPCOM & cleanup
#ifndef HACK_AROUND_NONREENTRANT_INITXPCOM
    NS_ShutdownXPCOM(sServiceManager);
#endif

    return NS_OK;
}


Initializing the browser

In PPBrowser, the procedure of initializing the browser is dispersed into various classes (CBrowserWindow, CBrowserShell, CWebBrowserChrome). So, its sequential procedure is not so clear. Hence, here I sort out the procedure as the sequential process.

Creating an instance of Base widget (CBrowserWindow constructor)

   // Make the base widget
   mWindow = do_CreateInstance(kWindowCID, &rv);
   NS_ENSURE_SUCCESS(rv, NS_ERROR_FAILURE);

Creating an instance of the chrome (CBrowserWindow constructor)

   // Make our CWebBrowserChrome
   mBrowserChrome = new CWebBrowserChrome;
   NS_ENSURE_TRUE(mBrowserChrome, NS_ERROR_OUT_OF_MEMORY);
   NS_ADDREF(mBrowserChrome);
   mBrowserChrome->BrowserWindow() = this;

Creating an instance of the browser (nsWebBrowser) (CBrowserShell@constructor)

    mWebBrowser = do_CreateInstance(NS_WEBBROWSER_CONTRACTID, &rv);
    NS_ENSURE_SUCCESS(rv, NS_ERROR_FAILURE);

    nsCOMPtr<nsIBaseWindow> baseWin(do_QueryInterface(mWebBrowser));
    NS_ENSURE_TRUE(baseWin, NS_ERROR_FAILURE);
    mWebBrowserAsBaseWin = baseWin;

    nsCOMPtr<nsIWebNavigation> webNav(do_QueryInterface(mWebBrowser));
    NS_ENSURE_TRUE(webNav, NS_ERROR_FAILURE);
    mWebBrowserAsWebNav = webNav;

Creating Base widget (CBrowserWindow::FinishCreate)

    nsresult rv = mWindow->Create((nsNativeWidget)GetMacPort(), r,
        nsnull, nsnull, nsnull, nsnull, nsnull);
    if (NS_FAILED(rv))
       Throw_(NS_ERROR_GET_CODE(rv));

Initializing, creating & making layout of the browser (CBrowserShell::FinishCreateSelf)

    mWebBrowserAsBaseWin->InitWindow(aWidget->GetNativeData(NS_NATIVE_WIDGET)
      , nsnull, r.x, r.y, r.width, r.height);
    mWebBrowserAsBaseWin->Create();
   
    AdjustFrame();

Associating the chrome with the brower(CBrowserShell::SetTopLevelWindow)

    mWebBrowser->SetContainerWindow(aTopLevelWindow);  

    /*
    In case we needed to do something with the underlying docshell...   

    nsCOMPtr<nsIDocShell> ourDocShell(do_GetInterface(mWebBrowser));
    NS_ENSURE_TRUE(ourDocShell, NS_ERROR_FAILURE);
    */

Associating the browser with the chrome & initializing every control (CBrowserWindow::FinishCreateSelf)

    mBrowserShell = dynamic_cast<CBrowserShell*
                       >(FindPaneByID(paneID_WebShellView));
    ThrowIfNULL_(mBrowserShell);  // Curtains if we don't have this

    // Tell our CBrowserShell about the chrome 
    mBrowserShell->SetTopLevelWindow(mBrowserChrome);
    // Tell our chrome about the CBrowserShell 
    mBrowserChrome->BrowserShell() = mBrowserShell;

    // Find our subviews - When we have a way of creating this
    // window with various chrome flags, we may or may not have
    // all of these subviews so don't fail if they don't exist
    mURLField = dynamic_cast<LEditText*>(FindPaneByID(paneID_URLField));
    if (mURLField)
        SwitchTarget(mURLField);

    mStatusBar = dynamic_cast<LStaticText*>(FindPaneByID(paneID_StatusBar));
    mThrobber = dynamic_cast<CThrobber*>(FindPaneByID(paneID_Throbber));
    mProgressBar = dynamic_cast<LProgressBar*
                       >(FindPaneByID(paneID_ProgressBar));
    if (mProgressBar)
       mProgressBar->Hide();

    mBackButton = dynamic_cast<LBevelButton*>(FindPaneByID(paneID_BackButton));
    if (mBackButton)
        mBackButton->Disable();
    mForwardButton = dynamic_cast<LBevelButton*
                       >(FindPaneByID(paneID_ForwardButton));
    if (mForwardButton)
        mForwardButton->Disable();
    mStopButton = dynamic_cast<LBevelButton*>(FindPaneByID(paneID_StopButton));
    if (mStopButton)
        mStopButton->Disable();

Web browser

Needless to say, the core of embedding process is this web browser object (nsWebBrowser).

Web browser is a XPCOM object. So, in the case of requesting it to do something, you should get the interface which has the method you want by QueryInterface() and call this method via gotten interface pointer.

The interfaces implemented by web browser are such as

  • nsIWebBrowser
  • nsIWebNavigation
  • nsIWebProgress
  • nsIWebBrowserSetup
  • nsIDocShellTreeItem
  • nsIBaseWindow
  • nsIScrollable
  • nsITextScroll
  • nsIInterfaceRequestor
  • nsIWebBrowserPersist

I show methods defined by each interfaces below.

nsIWebBrowser

  /* void addWebBrowserListener (in nsIInterfaceRequestor listener); */
  NS_IMETHOD AddWebBrowserListener(nsIInterfaceRequestor *listener) = 0;

  /* void removeWebBrowserListener (in nsIInterfaceRequestor listener); */
  NS_IMETHOD RemoveWebBrowserListener(nsIInterfaceRequestor *listener) = 0;

  /* attribute nsIWebBrowserChrome containerWindow; */
  NS_IMETHOD GetContainerWindow(nsIWebBrowserChrome * *aContainerWindow) = 0;
  NS_IMETHOD SetContainerWindow(nsIWebBrowserChrome * aContainerWindow) = 0;

  /* attribute nsIURIContentListener parentURIContentListener; */
  NS_IMETHOD GetParentURIContentListener(nsIURIContentListener * *aParentURIContentListener) = 0;
  NS_IMETHOD SetParentURIContentListener(nsIURIContentListener * aParentURIContentListener) = 0;

  /* readonly attribute nsIDOMWindow contentDOMWindow; */
  NS_IMETHOD GetContentDOMWindow(nsIDOMWindow * *aContentDOMWindow) = 0;

nsIWebNavigation

  /* readonly attribute boolean canGoBack; */
  NS_IMETHOD GetCanGoBack(PRBool *aCanGoBack) = 0;

  /* readonly attribute boolean canGoForward; */
  NS_IMETHOD GetCanGoForward(PRBool *aCanGoForward) = 0;

  /* void goBack (); */
  NS_IMETHOD GoBack(void) = 0;

  /* void goForward (); */
  NS_IMETHOD GoForward(void) = 0;

  /* void gotoIndex (in long index); */
  NS_IMETHOD GotoIndex(PRInt32 index) = 0;

  enum { LOAD_FLAGS_NONE = 0U };

  enum { LOAD_FLAGS_MASK = 65535U };

  enum { LOAD_FLAGS_IS_REFRESH = 16U };

  enum { LOAD_FLAGS_IS_LINK = 32U };

  enum { LOAD_FLAGS_BYPASS_HISTORY = 64U };

  enum { LOAD_FLAGS_REPLACE_HISTORY = 128U };

  enum { LOAD_FLAGS_BYPASS_CACHE = 256U };

  enum { LOAD_FLAGS_BYPASS_PROXY = 512U };

  /* void loadURI (in wstring uri, in unsigned long loadFlags); */
  NS_IMETHOD LoadURI(const PRUnichar *uri, PRUint32 loadFlags) = 0;

  /* void reload (in unsigned long reloadFlags); */
  NS_IMETHOD Reload(PRUint32 reloadFlags) = 0;

  /* void stop (); */
  NS_IMETHOD Stop(void) = 0;

  /* readonly attribute nsIDOMDocument document; */
  NS_IMETHOD GetDocument(nsIDOMDocument * *aDocument) = 0;

  /* readonly attribute nsIURI currentURI; */
  NS_IMETHOD GetCurrentURI(nsIURI * *aCurrentURI) = 0;

  /* attribute nsISHistory sessionHistory; */
  NS_IMETHOD GetSessionHistory(nsISHistory * *aSessionHistory) = 0;
  NS_IMETHOD SetSessionHistory(nsISHistory * aSessionHistory) = 0;

nsIWebProgress

  /* void addProgressListener (in nsIWebProgressListener listener); */
  NS_IMETHOD AddProgressListener(nsIWebProgressListener *listener) = 0;

  /* void removeProgressListener (in nsIWebProgressListener listener); */
  NS_IMETHOD RemoveProgressListener(nsIWebProgressListener *listener) = 0;

nsIWebBrowserSetup

  enum { SETUP_ALLOW_PLUGINS = 1U };

  /* void setProperty (in unsigned long aId, in unsigned long aValue); */
  NS_IMETHOD SetProperty(PRUint32 aId, PRUint32 aValue) = 0;

nsIDocShellTreeItem

  /* attribute wstring name; */
  NS_IMETHOD GetName(PRUnichar * *aName) = 0;
  NS_IMETHOD SetName(const PRUnichar * aName) = 0;

  enum { typeChrome = 0 };

  enum { typeContent = 1 };

  enum { typeContentWrapper = 2 };

  enum { typeChromeWrapper = 3 };

  /* attribute long itemType; */
  NS_IMETHOD GetItemType(PRInt32 *aItemType) = 0;
  NS_IMETHOD SetItemType(PRInt32 aItemType) = 0;

  /* attribute nsIDocShellTreeItem parent; */
  NS_IMETHOD GetParent(nsIDocShellTreeItem * *aParent) = 0;
  NS_IMETHOD SetParent(nsIDocShellTreeItem * aParent) = 0;

  /* readonly attribute nsIDocShellTreeItem sameTypeParent; */
  NS_IMETHOD GetSameTypeParent(nsIDocShellTreeItem * *aSameTypeParent) = 0;

  /* readonly attribute nsIDocShellTreeItem rootTreeItem; */
  NS_IMETHOD GetRootTreeItem(nsIDocShellTreeItem * *aRootTreeItem) = 0;

  /* readonly attribute nsIDocShellTreeItem sameTypeRootTreeItem; */
  NS_IMETHOD GetSameTypeRootTreeItem(nsIDocShellTreeItem * *aSameTypeRootTreeItem) = 0;

  /* nsIDocShellTreeItem findItemWithName (in wstring name, in nsISupports aRequestor); */
  NS_IMETHOD FindItemWithName(const PRUnichar *name, nsISupports *aRequestor
                , nsIDocShellTreeItem **_retval) = 0;

  /* attribute nsIDocShellTreeOwner treeOwner; */
  NS_IMETHOD GetTreeOwner(nsIDocShellTreeOwner * *aTreeOwner) = 0;
  NS_IMETHOD SetTreeOwner(nsIDocShellTreeOwner * aTreeOwner) = 0;

  /* attribute long childOffset; */
  NS_IMETHOD GetChildOffset(PRInt32 *aChildOffset) = 0;
  NS_IMETHOD SetChildOffset(PRInt32 aChildOffset) = 0;

nsIBaseWindow

  /* [noscript] void initWindow (in nativeWindow parentNativeWindow, i
n nsIWidget parentWidget, in long x, in long y, in long cx, in long cy); */
  NS_IMETHOD InitWindow(nativeWindow parentNativeWindow, nsIWidget 
*  parentWidget, PRInt32 x, PRInt32 y, PRInt32 cx, PRInt32 cy) = 0;

  /* void create (); */
  NS_IMETHOD Create(void) = 0;

  /* void destroy (); */
  NS_IMETHOD Destroy(void) = 0;

  /* void setPosition (in long x, in long y); */
  NS_IMETHOD SetPosition(PRInt32 x, PRInt32 y) = 0;

  /* void getPosition (out long x, out long y); */
  NS_IMETHOD GetPosition(PRInt32 *x, PRInt32 *y) = 0;

  /* void setSize (in long cx, in long cy, in boolean fRepaint); */
  NS_IMETHOD SetSize(PRInt32 cx, PRInt32 cy, PRBool fRepaint) = 0;

  /* void getSize (out long cx, out long cy); */
  NS_IMETHOD GetSize(PRInt32 *cx, PRInt32 *cy) = 0;

  /* void setPositionAndSize (in long x, in long y, in long cx, in long cy, in boolean fRepaint); */
  NS_IMETHOD SetPositionAndSize(PRInt32 x, PRInt32 y, PRInt32 cx, PRInt32 cy, PRBool fRepaint) = 0;

  /* void getPositionAndSize (out long x, out long y, out long cx, out long cy); */
  NS_IMETHOD GetPositionAndSize(PRInt32 *x, PRInt32 *y, PRInt32 *cx, PRInt32 *cy) = 0;

  /** 
	 * Tell the window to repaint itself
	 * @param aForce - if true, repaint immediately
	 *                 if false, the window may defer repainting as it sees fit.
	 */
  /* void repaint (in boolean force); */
  NS_IMETHOD Repaint(PRBool force) = 0;

  /* [noscript] attribute nsIWidget parentWidget; */
  NS_IMETHOD GetParentWidget(nsIWidget * *aParentWidget) = 0;
  NS_IMETHOD SetParentWidget(nsIWidget * aParentWidget) = 0;

  /* attribute nativeWindow parentNativeWindow; */
  NS_IMETHOD GetParentNativeWindow(nativeWindow *aParentNativeWindow) = 0;
  NS_IMETHOD SetParentNativeWindow(nativeWindow aParentNativeWindow) = 0;

  /* attribute boolean visibility; */
  NS_IMETHOD GetVisibility(PRBool *aVisibility) = 0;
  NS_IMETHOD SetVisibility(PRBool aVisibility) = 0;

  /* [noscript] readonly attribute nsIWidget mainWidget; */
  NS_IMETHOD GetMainWidget(nsIWidget * *aMainWidget) = 0;

  /**
	* Give the window focus.
	*/
  /* void setFocus (); */
  NS_IMETHOD SetFocus(void) = 0;

  /* void focusAvailable (in nsIBaseWindow aCurrentFocus, out boolean aTookFocus); */
  NS_IMETHOD FocusAvailable(nsIBaseWindow *aCurrentFocus, PRBool *aTookFocus) = 0;

  /* attribute wstring title; */
  NS_IMETHOD GetTitle(PRUnichar * *aTitle) = 0;
  NS_IMETHOD SetTitle(const PRUnichar * aTitle) = 0;

nsIScrollable

  enum { ScrollOrientation_Y = 1 };

  enum { ScrollOrientation_X = 2 };

  /* void getCurScrollPos (in long scrollOrientation, out long curPos); */
  NS_IMETHOD GetCurScrollPos(PRInt32 scrollOrientation, PRInt32 *curPos) = 0;

  /* void setCurScrollPos (in long scrollOrientation, in long curPos); */
  NS_IMETHOD SetCurScrollPos(PRInt32 scrollOrientation, PRInt32 curPos) = 0;

  /* void setCurScrollPosEx (in long curHorizontalPos, in long curVerticalPos); */
  NS_IMETHOD SetCurScrollPosEx(PRInt32 curHorizontalPos, PRInt32 curVerticalPos) = 0;

  /* void getScrollRange (in long scrollOrientation, out long minPos, out long maxPos); */
  NS_IMETHOD GetScrollRange(PRInt32 scrollOrientation, PRInt32 *minPos, PRInt32 *maxPos) = 0;

  /* void setScrollRange (in long scrollOrientation, in long minPos, in long maxPos); */
  NS_IMETHOD SetScrollRange(PRInt32 scrollOrientation, PRInt32 minPos, PRInt32 maxPos) = 0;

  /* void setScrollRangeEx (in long minHorizontalPos, in long maxHorizontalPos
, in long minVerticalPos, in long maxVerticalPos); */
  NS_IMETHOD SetScrollRangeEx(PRInt32 minHorizontalPos, PRInt32
      maxHorizontalPos, PRInt32 minVerticalPos, PRInt32 maxVerticalPos) = 0;

  enum { Scrollbar_Auto = 1 };

  enum { Scrollbar_Never = 2 };

  enum { Scrollbar_Always = 3 };

  /* void getCurrentScrollbarPreferences (in long scrollOrientation, out long scrollbarPref); */
  NS_IMETHOD GetCurrentScrollbarPreferences(PRInt32 scrollOrientation, PRInt32 *scrollbarPref) = 0;

  /* void setCurrentScrollbarPreferences (in long scrollOrientation, in long scrollbarPref); */
  NS_IMETHOD SetCurrentScrollbarPreferences(PRInt32 scrollOrientation, PRInt32 scrollbarPref) = 0;

  /* void getDefaultScrollbarPreferences (in long scrollOrientation, out long scrollbarPref); */
  NS_IMETHOD GetDefaultScrollbarPreferences(PRInt32 scrollOrientation, PRInt32 *scrollbarPref) = 0;

  /* void setDefaultScrollbarPreferences (in long scrollOrientation, in long scrollbarPref); */
  NS_IMETHOD SetDefaultScrollbarPreferences(PRInt32 scrollOrientation, PRInt32 scrollbarPref) = 0;

  /* void resetScrollbarPreferences (); */
  NS_IMETHOD ResetScrollbarPreferences(void) = 0;

  /* void getScrollbarVisibility (out boolean verticalVisible, out boolean horizontalVisible); */
  NS_IMETHOD GetScrollbarVisibility(PRBool *verticalVisible, PRBool *horizontalVisible) = 0;

nsITextScroll

  /**
   * Scroll the view up or down by aNumLines lines. positive
   * values move down in the view. Prevents scrolling off the
   * end of the view.
   * @param numLines number of lines to scroll the view by
   */
  /* void scrollByLines (in long numLines); */
  NS_IMETHOD ScrollByLines(PRInt32 numLines) = 0;

  /**
   * Scroll the view up or down by numPages pages. a page
   * is considered to be the amount displayed by the clip view.
   * positive values move down in the view. Prevents scrolling
   * off the end of the view.
   * @param numPages number of pages to scroll the view by
   */
  /* void scrollByPages (in long numPages); */
  NS_IMETHOD ScrollByPages(PRInt32 numPages) = 0;

nsIInterfaceRequestor

  /* void getInterface (in nsIIDRef uuid, [iid_is (uuid), retval] out nsQIResult result); */
  NS_IMETHOD GetInterface(const nsIID & uuid, void * *result) = 0;

nsIWebBrowserPersist

  /**
   * Callback listener for progress notifications.
   */
  /* attribute nsIWebBrowserPersistProgress progressListener; */
  NS_IMETHOD GetProgressListener(nsIWebBrowserPersistProgress * *aProgressListener) = 0;
  NS_IMETHOD SetProgressListener(nsIWebBrowserPersistProgress * aProgressListener) = 0;

  /**
   * Save the specified URI to file.
   *
   * aURI - The URI to save to file.
   * aPostData - Data to pass with in an HTTP request or nsnull.
   * aFileName - Target local filename.
   */
  /* void saveURI (in nsIURI aURI, in nsIInputStream aPostData, in string aFileName); */
  NS_IMETHOD SaveURI(nsIURI *aURI, nsIInputStream *aPostData, const char *aFileName) = 0;

  /* void saveCurrentURI (in string aFileName); */
  NS_IMETHOD SaveCurrentURI(const char *aFileName) = 0;

  /**
   * Save the specified DOM document to file and optionally all linked files
   * including images, CSS, JS & frames.
   *
   * aDocument - Document to save.
   * aFileName - Target local filename.
   * aDataPath - Path to folder (which must exist) to save linked files to,
   *             or nsnull.
   */
  /* void saveDocument (in nsIDOMDocument aDocument, in string aFileName, in string aDataPath); */
  NS_IMETHOD SaveDocument(nsIDOMDocument *aDocument, const char *aFileName, const char *aDataPath) = 0;


DocShell

DocShell (nsDocShell) is an object in that the core part of the browser is implemented. Web browser object (nsWebBrowser) holds this DocShell indirectly and requests inner complicated process to DocShell.

In the case of controlling the browser from the outside, basically all you have to use is this web browser (nsWebBrowser), which has the most upper level interfaces embedding application should use. But, in the case of a delicate process, you may want to call DocShell directly.

DocShell is held indirectly by web browser in nsIInterfaceRequester's GetInterface() mechanism way. On nsIWebBrowser, nsIDocShell interface of DocShell can be gotton to by GetInterface().

    nsCOMPtr<nsIDocShell> ourDocShell(do_GetInterface(mWebBrowser));
    NS_ENSURE_TRUE(ourDocShell, NS_ERROR_FAILURE);

Also DocShell is an independent XPCOM object. So, it has various interfaces besides nsIDocShell.

The interfaces implemented by DocShell are such as

  • nsIDocShell
  • nsIDocShellTreeItem
  • nsIDocShellTreeNode
  • nsIDocShellHistory
  • nsIWebNavigation
  • nsIBaseWindow
  • nsIScrollable
  • nsITextScroll
  • nsIContentViewerContainer
  • nsIInterfaceRequestor
  • nsIScriptGlobalObjectOwner
  • nsIRefreshURI
  • nsIWebProgressListener
  • nsSupportsWeakReference

For reference, I show only methods implemented by nsIDocShell interface below.

nsIDocShell

  /* [noscript] void loadURI (in nsIURI uri, in nsIDocShellLoadInfo loadInfo,
      in unsigned long aLoadFlags); */
  NS_IMETHOD LoadURI(nsIURI *uri, nsIDocShellLoadInfo *loadInfo,
      PRUint32 aLoadFlags) = 0;

  /* [noscript] void loadStream (in nsIInputStream aStream, in nsIURI aURI, in
 string aContentType, in long aContentLen, in nsIDocShellLoadInfo aLoadInfo); */
  NS_IMETHOD LoadStream(nsIInputStream *aStream, nsIURI *aURI, const char 
    *aContentType, PRInt32 aContentLen, nsIDocShellLoadInfo *aLoadInfo) = 0;

  /* void createLoadInfo (out nsIDocShellLoadInfo loadInfo); */
  NS_IMETHOD CreateLoadInfo(nsIDocShellLoadInfo **loadInfo) = 0;

  /* void stopLoad (); */
  NS_IMETHOD StopLoad(void) = 0;

  /* attribute nsIDocumentLoaderObserver docLoaderObserver; */
  NS_IMETHOD GetDocLoaderObserver(nsIDocumentLoaderObserver * *aDocLoaderObserver) = 0;
  NS_IMETHOD SetDocLoaderObserver(nsIDocumentLoaderObserver * aDocLoaderObserver) = 0;

  /* [noscript] readonly attribute nsIPresContext presContext; */
  NS_IMETHOD GetPresContext(nsIPresContext * *aPresContext) = 0;

  /* [noscript] readonly attribute nsIPresShell presShell; */
  NS_IMETHOD GetPresShell(nsIPresShell * *aPresShell) = 0;

  /* readonly attribute nsIContentViewer contentViewer; */
  NS_IMETHOD GetContentViewer(nsIContentViewer * *aContentViewer) = 0;

  /* attribute nsIChromeEventHandler chromeEventHandler; */
  NS_IMETHOD GetChromeEventHandler(nsIChromeEventHandler * *aChromeEventHandler) = 0;
  NS_IMETHOD SetChromeEventHandler(nsIChromeEventHandler * aChromeEventHandler) = 0;

  /* attribute nsIURIContentListener parentURIContentListener; */
  NS_IMETHOD GetParentURIContentListener(nsIURIContentListener * *aParentURIContentListener) = 0;
  NS_IMETHOD SetParentURIContentListener(nsIURIContentListener * aParentURIContentListener) = 0;

  /* attribute nsIDocumentCharsetInfo documentCharsetInfo; */
  NS_IMETHOD GetDocumentCharsetInfo(nsIDocumentCharsetInfo * *aDocumentCharsetInfo) = 0;
  NS_IMETHOD SetDocumentCharsetInfo(nsIDocumentCharsetInfo * aDocumentCharsetInfo) = 0;

  /* attribute boolean allowPlugins; */
  NS_IMETHOD GetAllowPlugins(PRBool *aAllowPlugins) = 0;
  NS_IMETHOD SetAllowPlugins(PRBool aAllowPlugins) = 0;

  enum { viewNormal = 0 };

  enum { viewSource = 1 };

  /* attribute long viewMode; */
  NS_IMETHOD GetViewMode(PRInt32 *aViewMode) = 0;
  NS_IMETHOD SetViewMode(PRInt32 aViewMode) = 0;

  /**
	* Set/Get the document scale factor.  When setting this attribute, a
	* NS_ERROR_NOT_IMPLEMENTED error may be returned by implementations
	* not supporting zoom.  Implementations not supporting zoom should return
	* 1.0 all the time for the Get operation.  1.0 by the way is the default
	* of zoom.  This means 100% of normal scaling or in other words normal size
	* no zoom. 
	*/
  /* attribute float zoom; */
  NS_IMETHOD GetZoom(float *aZoom) = 0;
  NS_IMETHOD SetZoom(float aZoom) = 0;

  /* attribute long marginWidth; */
  NS_IMETHOD GetMarginWidth(PRInt32 *aMarginWidth) = 0;
  NS_IMETHOD SetMarginWidth(PRInt32 aMarginWidth) = 0;

  /* attribute long marginHeight; */
  NS_IMETHOD GetMarginHeight(PRInt32 *aMarginHeight) = 0;
  NS_IMETHOD SetMarginHeight(PRInt32 aMarginHeight) = 0;

Chrome

Chrome class (CWebBrowserChrome) is like a shadow of the browser shell class (CBrowserShell) and the window class (CBrowserWindow). This is in close cooperation with the browser shell class & the window class and act as go-between to mozilla side.

Among the classes used in embedding, the browser shell class and the chrome class use XPCOM frequently. But, from the standpoint of XPCOM usage, both are much different from each other.

The browser shell class only uses XPCOM already implemented, but the chrome class does implement various XPCOM interfaces by itself.

Candidates for the interfaces implemented by the chrome class are such as

  • nsIBaseWindow
  • nsIWebBrowserChrome
  • nsIWebProgressListener
  • nsIStreamObserver
  • nsIURIContentListener
  • nsIDocumentLoaderObserver - abolished
  • nsIDocShellTreeOwner
  • nsIInterfaceRequestor
  • nsIPrompt

Among these interfaces, there are ones not implemented by PPBrowser. But, accoding to the functions you need to achieve in your embedding application, there may be the case that other interfaces should be implemented.

And, embedding itself is still under development. Therefore, these interfaces may also change.


c_o_n_t_a_c_t
Copyright (C) 2000-2002 Symphony, Inc. All Rights Reserved.
Japanese