Mozilla plugins refresh and stuff

To verify that Mozilla is aware of new .xpt files, you can look in the generated file, xpti.dat, where type libraries are listed. If you need to, you can call navigator.plugins.refresh() to find new XPT files and plug-in software.

Plug-in developers might find it useful for debugging purposes to turn off the exception catching mechanism currently implemented in Mozilla on Windows. To turn off Windows exception handling, add the following line into your prefs.js file: user_pref("plugin.dont_try_safe_calls", true);

Mozilla Source Code Directory Structure

Dirctory structure: Mozilla Source Code Directory Structure
Another: Source code directories overview

Interesting:

browser - Firefox

xulrunner - xulrunner

widget - a cross-platform API, with implementations on each platform, for dealing with operating system/environment widgets, i.e., code related to creation and handling of windows, popups, and other native widgets and to converting the system's messages related to painting and events into the messages used by other parts of Mozilla (e.g. view/ and content/, the latter of which converts many of the messages to yet another API, the DOM event API).

gfx - contains interfaces that abstract the capabilities of platform specific graphics toolkits, along with implementations on various platforms. These interfaces provide methods for things like drawing images, text, and basic shapes. It also contains basic data structures such as points and rectangles used here and in other parts of Mozilla.
It is also the home of the new graphics architecture based on cairo (via a C++ wrapper called thebes). See NewGFXAPIs and GFXEvolution.


Not so interesting:

view - view manager. Contains cross-platform code used for painting, scrolling, event handling, z-ordering, and opacity. Soon to become obsolete, gradually.

docshell - Implementation of the docshell, the main object managing things related to a document window. Each frame has its own docshell. Contains methods for loading URIs, managing URI content listeners, etc. It is the outermost layer of the embedding API used to embed a Gecko browser into an application.

webshell - Mostly obsolete, and being merged into docshell/.

IRC: irc.mozilla.org, channel #developers

Gecko window creation and destruction

My current assumptions on this matter:

1. Instantiate your own implementation of nsIWebBrowserChrome.2. Create nsIWebBrowser:3. Tell nsIWebBrowser what chrome it's in:4. Query nsIBaseWindow from nsIWebBrowser:5. Create native window: hWnd.
6. Tell nsIBaseWindow to create browser window - a child of hWnd:7. Add listeners of your choice (if you want):8. Update size of browser window based on native window (see Resizing browser window):9. Show native window:

Some interesting Gecko interfaces

Interfaces reference: Mozilla Embedding API Reference
Interfaces reference: XPCOM API Reference

Mandatory: you have to implement those on one object - the Chrome.

nsIWebBrowserChrome - this interface must be implemented by the embedder in a class that also implements nsIEmbeddingSiteWindow. It corresponds to the top-level, outermost window containing an embedded Gecko WebBrowser (aka. Chrome).

nsIEmbeddingSiteWindow - this interface is implemented by the embedder to provide Gecko with the means to call up to the host to resize the window, hide or show it and set/get its title.

nsIInterfaceRequestor - implements GetInterface(). Don't know why this is mandatory, but I know that without it the browser shows, but on first interaction crashes.

Those are provided:

nsIWebBrowser - embedders use this interface during initialization to associate the new WebBrowser instance with the embedder's chrome and to register any listeners. The interface may also be used at runtime to obtain the content DOM window and from that the rest of the DOM.

nsIBaseWindow - window manipulations (size/visibility) for the browser.

Optional: window creation. Dunno when they are used:

nsIWindowCreator - this is a embedder-provided callback interface used by Gecko to create new browser windows in certain specific circumstances, like in utilizing PSM. A WindowWatcher component must also be available, and must be notified of the nsIWindowCreator during application initialization.

nsIWindowWatcher - this interface keeps track of Gecko/DOM Windows. It is a service that maintains a list of open top-level windows, and allows some operations on them.
This component must be initialized at application startup by calling setWindowCreator.

Optional:

nsIWebBrowserChromeFocus - this interface represents focus up-calls from Gecko to the embedding chrome. It is is implemented by the same embedder-provided object that implements nsIEmbeddingSiteWindow.

Listeners: those are optional too.

nsIWebProgressListener
nsISHistoryListener
nsIContextMenuListener
nsITooltipListener

To play with listeners you have to (I think...) implement nsISupportsWeakReference. Easiest way to do it is to use class nsSupportsWeakReference.

Interesting:

nsIDOMWindow

nsIDOMDocument
nsIEmbeddingSiteWindow2 - ???
nsIObserver - use this to observe i.e. profile directory changes or something... (WinEmbed example shows how).

Obsolete:

nsIWebBrowserSiteWindow - it was replaced by nsIEmbeddingSiteWindow.
"A new interface has been checked in called nsIWebBrowserSiteWindow. This
is a cut-down version of the nsIBaseWindow containing only the methods
that an embedding client needs to implement."

Question:
There are those two methods:Why both? What is the difference?

nsCOMPtr: AddRef, Release and QueryInterface

Here's the ultimate tutorial for nsCOMPtr: Using nsCOMPtr - Getting Started Guide

Vars:Assignment:Output parameters (GetFoo() adds reference itself, so tell nsFoo not to):Return values (CreateFoo() adds reference itself, so tell nsFoo not to):Four ways to QueryInterface:QueryInterface and GetInterface:
getInterface is very similar to QueryInterface. The main difference is that interfaces returned from getInterface are not required to provide a way back to the object implementing nsIInterfaceRequestor. The semantics of QueryInterface dictate that given an interface A that you QueryInterface on to get to interface B, you must be able to QueryInterface on B to get back to A. nsIInterfaceRequestor, however, allows you to obtain an interface C from A that may (or most likely) will not have the ability to get back to A.
Helper: do_GetInterface()

Caution: most frequent leaks are caused by assigning a raw pointer you have already AddRefed:

Gecko SDK strings

Gecko string reference: Mozilla internal string guide

When embedding Gecko one should use nsEmbedString and nsEmbedCString I think. But the're just typedef's for nsString and nsCString.
nsString is a UTF16 string (Gecko's "native").
nsCString is a single-byte string (ASCII).
(They extend nsAString and nsACString, which are abstract themselves.)
They both have a get() method to get their null-terminated contents.

How to convert them? UTF16 -> ASCII:The other way, ASCII -> UTF16:See code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function UpdateStatusBarText() and OpenWebPage()

Gecko window activation

How to inform Gecko about window activation?

On WM_ACTIVATE do this:

nsCOMPtr<nsIWebBrowserFocus> focus(do_GetInterface(webBrowser));

focus->Activate()/Deactivate();

What about create/destroy? Don't know, but there's this code for WM_CLOSE:
WebBrowserChromeUI::Destroy(chrome);

See code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function BrowserDlgProc()

Gecko SDK and clipboard

Clipboard operations using Gecko SDK:

nsCOMPtr<nsIWebBrowser> webBrowser;

...

nsCOMPtr<nsIClipboardCommands> clipCmds = do_GetInterface(webBrowser);
clipCmds->CanCutSelection(&canCutSelection);
clipCmds->CanCopySelection(&canCopySelection);
clipCmds->CanPaste(&canPaste);

...

See code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function UpdateUI()

How to navigate to URL in Gecko SDK?

It's simple:

nsIWebBrowserChrome->GetWebBrowser(nsIWebBrowser**)

nsIWebBrowser -QI-> nsIWebNavigation
nsIWebNavigation->LoadURI(...)

See code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function OpenWebPage()

How to set up a profile?

I don't know if setting up a profile is necessary for a Gecko app. Probably.
Anyway, to set up a profile you just need to provide the runtime with a directory for it.

Note: nsIFile is a cross-platform representation of a file system path (not a file itself). It can point to a file or a directory.

So first get the standard directory for application data on your operating system:
nsCOMPtr<nsIFile> appDataDir;
nsresult rv = NS_GetSpecialDirectory(NS_APP_APPLICATION_REGISTRY_DIR, getter_AddRefs(appDataDir));
(On Windows this will be "C:\Documents and Settings\\Application Data\Mozilla\".)

Append your application name to it:
appDataDir->AppendNative(nsCString("winembed"));

I don't know whether this is needed (probably not?):

nsCOMPtr<nsILocalFile>localAppDataDir(do_QueryInterface(appDataDir));

Create directory provider that will report where the profile dir is when asked:

nsCOMPtr<nsProfileDirServiceProvider> locProvider;
NS_NewProfileDirServiceProvider(PR_TRUE, getter_AddRefs(locProvider));

locProvider->Register();

And set the profile dir on this directory provider:
locProvider->SetProfileDir(localAppDataDir);

See code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function StartupProfile()

Resizing browser window

How to resize a Gecko SDK browser window:

Native window handle:

nsIWebBrowserChrome -QI-> nsIEmbeddingSiteWindow ->GetSiteWindow(HWND**);

GetClientRect(hWnd, &rect);

nsIWebBrowserChrome ->GetWebBrowser(nsIWebBrowser**)

nsIWebBrowser -QI-> nsIBaseWindow ->SetPositionAndSize()/SetVisibility()

When resizing you have to do both: resize the native window (HWND) and resize the "virtual" browser window (nsIBaseWindow).

Example code: xulrunner-1.9.1.3-source\mozilla-1.9.1\embedding\tests\winEmbed\winEmbed.cpp, function ResizeEmbedding()

XRE_InitEmbedding

Q. I'm new to embedding Gecko and I started to look at code in embedding/tests/*.
winEmbed uses XRE_InitEmbedding to initialize the gecko engine while other ports (mfcembed, os2Embed, wxEmbed) use NS_InitEmbedding.
What is the difference and which one should I use?

A. It depends. If you want to embed all of the mozilla code base into your code, then use NS_InitEmbedding. If you want to link only XUL Runner then use XRE_InitEmbedding. If you want to be able to link any mozilla tree, then use neither. Write them out yourself and use InitXPCOM2 or InitXPCOM3.

XRE_InitEmbedding just calls InitXPCOM3 with default XULRunner components.

Here's a post by Benjamin Smedberg about bootstrapping Gecko SDK: Re: XRE_InitEmbedding gecko 1.9 c++

And here's a minimal workable embedding example (gtk).

Here are the basics - a little outdated but mostly valid: Gecko Embedding Basics

See XRE_InitEmbedding() source: xulrunner-1.9.1.3-source\mozilla-1.9.1\toolkit\xre\nsEmbedFunctions.cpp, function XRE_InitEmbedding()