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

TOC PREV NEXT INDEX

Embedding Gecko Basics

Common Embedding Tasks

The following is a series of code snippets (taken from MFCEmbed, the Windows based embedding Gecko sample) which demonstrate very briefly implementation associated with common embedding tasks.To see all the files associated with this sample, go to lxr.mozilla.org/seamonkey/source/embedding/tests/mfcembed/. There are also Linux- and Mac OS-based examples.

Gecko setup

The Gecko embedding layer must be initialized before you can use Gecko. This ensures XPCOM is started, creates the component registry if necessary, and starts global services. There is an equivalent shutdown procedure.

Note that the embedding layer is started up by passing it two parameters. The first indicates where the executable is stored on the file system (nsnull indicates the working directory). The second indicates the file location object "provider" that specifies to Gecko where to find profiles, the component registry preferences, and so on. 

nsresult rv;
rv = NS_InitEmbedding(nsnull, provider);
if(NS_FAILED(rv))
{
ASSERT(FALSE);
return FALSE;
}
Creating a browser instance

The embedder-provided BrowserView object calls its method CreateBrowser. Each browser object (a webbrowser) represents a single browser window. Notice the utility directive do_CreateInstance and the use of macros. 

//Create an instance of the Mozilla embeddable browser
 
HRESULT CBrowserView::CreateBrowser() 
{
// Create a web shell  
nsresult rv;
mWebBrowser = do_CreateInstance(NS_WEBBROWSER_CONTRACTID, &rv);
if(NS_FAILED(rv))
return rv;

Once the nsWebBrowser object is created the application uses do_QueryInterface to load a pointer to the nsIWebNavigation interface into the mWebNav member variable. This will be used later for web page navigation. 

rv = NS_OK;
mWebNav = do_QueryInterface(mWebBrowser, &rv);
if(NS_FAILED(rv))
return rv;

Next the embedder-provided CBrowserImpl object is created. Gecko requires that some interfaces be implemented by the embedder so that Gecko can communicate with the embedding application. See the What You Provide section. In the sample, CBrowserImpl is the object that implements those required interfaces. It will be passed into the SetContainerWindow() call below. 

mpBrowserImpl = new CBrowserImpl();
if(mpBrowserImpl == nsnull)
return NS_ERROR_OUT_OF_MEMORY;

The mWebBrowser interface pointer is then passed to the CBrowserImpl object via its Init method. A second pointer to the platform specific BrowserFrameGlue interface is also passed in and saved. The BrowserFrameGlue pointer allows CBrowserImpl to call methods to update status/progress bars, etc. 

mpBrowserImpl->Init(mpBrowserFrameGlue, mWebBrowser);
mpBrowserImpl->AddRef();

Next the embedder-supplied chrome object is associated with the webbrowser. Note the use of an nsCOMPtr. 

mWebBrowser->SetContainerWindow
	(NS_STATIC_CAST(nsIWebBrowserChrome*, mpBrowserImpl)); 
nsCOMPtr<nsIWebBrowserSetup>setup(do_QueryInterface(mWebBrowser));  
if (setup) 
	setup->SetProperty(nsIWebBrowserSetup::SETUP_IS_CHROME_WRAPPER,PR_TRUE);

The real webbrowser window is created. 

rv = NS_OK;
mBaseWindow = do_QueryInterface(mWebBrowser, &rv);
if(NS_FAILED(rv))
return rv;

Binding a window

Basic location information is passed in. 

RECT rcLocation;
GetClientRect(&rcLocation);
if(IsRectEmpty(&rcLocation)) 
{
	rcLocation.bottom++;
	rcLocation.top++;
}
rv = mBaseWindow->InitWindow(nsNativeWidget(m_hWnd), 
		nsnull,0, 0, rcLocation.right - rcLocation.left, 
		rcLocation.bottom - rcLocation.top);
rv = mBaseWindow->Create();

Note the m_hWnd passed into the call above to InitWindow(). (CBrowserView inherits the m_hWnd from CWnd). This m_hWnd will be used as the parent window by the embeddable browser.

Adding a listener

The BrowserImpl object is added as an nsIWebProgressListener. It will now receive progress messages. These callbacks will be used to update the status/progress bars. 

nsWeakPtr weakling
	(dont_AddRef(NS_GetWeakReference(NS_STATIC_CAST(nsIWebProgressListener*, 
			mpBrowserImpl))));
void mWebBrowser->AddWebBrowserListener(weakling, NS_GET_IID(nsIWebProgressListener));

Finally the webbrowser window is shown. 

mBaseWindow->SetVisibility(PR_TRUE);
 
nsCOMPtr<nsIWebBrowserPrint> print(do_GetInterface(mWebBrowser));
if (print) 
	{
	print->GetNewPrintSettings(getter_AddRefs(m_PrintSettings));
	}
return S_OK;

Using session history to navigate

The pointer to nsIWebNavigation saved above is used to move back through session history. 

void CBrowserView::OnNavBack() 
{
if(mWebNav)
	mWebNav->GoBack();
}

Written by: Ellen Evans | Comments, questions, complaints? Bug 141350
TOC PREV NEXT INDEX