Gecko: gBrowser and tabs

As anyone who hacks on Gecko knows, the project’s documentation is, um, lacking. This is sometimes Ok if all you do is work on Gecko; But for us that dive in and out of Gecko every few weeks … let’s just say, it can drive one a little insane. It also makes it really hard to learn what the f$%# is going on and wastes tremendous amounts of (my) time just getting something up an running (I’m talking days).

Anyway, I’m writing these posts mostly for myself, so I can avoid having to go through the pain of having to (re)learn Gecko’s JS APIs every few weeks.

If you want to follow along, make sure you clone Mozilla central and then:

./mach build
./mach run


After you build you also need go to “about:config” in the browser and set the preferences <code>devtools.debugger.remote-enabled</code>, <code>devtools.debugger.chrome-enabled</code>, and <code>devtools.chrome.enabled</code>. This will allow the -jsdebugger argument (the browser toolbox) to work. Thanks to Andreas Tolfsen who pointed this out in the comments!

Now, shut down the running instance of Nightly, because we need to launch a new one. Type into your terminal:


./mach run -P "coding" -jsdebugger -purgecaches


The -P is for profile (I’m using one called “coding”). The -jsdebugger option opens the “Browser toolbox” automatically. And -purgecaches dumps the JSM caches, avoiding a whole bunch of headaches.

window

At the top of the Gecko hierarchy, there is a window (similar to HTML), but this window represents the actual application window. This means that the interface is different to HTML’s Window object. You can test this by, for instance:

//Maximize the window, and the restore it to its previous location
window.maximize();
window.restore();


This window actually points to “chrome://browser/content/browser.xul”, which is basically what the browser is composed of (XUL elements – which implement the common DOM Interfaces).

gBrowser

Inside window there is gBrowser: this object represents the browser window. You can confirm this by, for instance, calling gBrowser.addTab("http://google.com"). This will add a tab. So:

const tab = gBrowser.addTab("http://google.com");


Tabs are opened in the background and are not “selected” (i.e., the focused one, independently of window focus).

//bring the new tab to the foreground
gBrowser.selectedTab = tab;


The main purpose for creating a tab will generally be to load content and possibly do something with that content. Inside each tab, there is a Browser, which is not directly accessible through the Tab‘s interface. Also, a Tab object does not provide direct access to the Window object of the tab. Instead you need to use a method from gBrowser to get at it:

//Get the "browser"
const browser = tab.linkedBrowser;
//Get the actual window object.
//NOTE: YOU CAN'T USE win yet! see below!
const win = browser.contentWindow


Note that this puts your in a race condition (the Document object won’t be ready), so you need to wait for the actual page to “show”. this is done through the undocumented pageshow event.

const pageShow = function() {
browser.removeEventListener('pageshow', pageShow);
//do something interesting
win.document.body.innerHTML = '<h1>Yay!</h1>';
}
browser.addEventListener('pageshow', pageShow);


Of course, once you have the Window object, then you are back in Web Development land and all is good. Once you are finished with a tab, you can remove it:

//clean up!
gBrowser.removeTab(tab);


Note: don’t be fooled by the .remove() method on the Tab object. That corresponds to the DOM interface’s .remove() method, which removes the node from the XBL tree, but doesn’t actually destroy the Tab. So, calling this can cause memory leaks. For example, when you run this against mochitests, you might see something like:


TEST-UNEXPECTED-FAIL | dom/manifest/test/browser_ManifestObtainer_obtain.jsleaked 1 docShell(s) until shutdown