What is the difference between tabbrowser, browser, gBrowser?

Question

While developing Firefox extensions, I've been looking at those terms for quite some time and I find them really confusing.

Look at this link. They use the term browser in so many ways which in spite of the explanation leaves the real differences of contexts unattended.

I'm wondering if anyone can provide a top-down picture of the whole thing.

Like if there are n different Firefox windows (in the sense of an OS window) open, how do I access each window's XUL content (like address bar, scroll bar, etc.), HTML content and how do those terms come into the picture there?

EDIT: After reading Kashif's awesome answer and looking at DOM inspector, I'm left with these questions:

• tabbrowser has a property called contentDocument. It refers to the HTML document under it. But tabbrowser can have multiple documents (on in each tab). Does it even make sense to have a contentDocument property under tabbrowser? Shouldn't it exist under browser? (browser is under tabbrowser and contains just one HTML document object).
• Where does window object come? Not the XUL element, but the HTML element which all web developers use off the chrome context. The one that contains the HTML document object directly.
• To access the tab elements (the UI rectangles that represent the open tabs in Firefox) and their context menus, one must use document present in browser.xul right? They don't come under tabbrowser do they? That is what I could see from DOM inspector.

EDIT: Kashif answered all these in his answer.

Answer 1

Browser

Browser is a general term that means a software that can be used to browse internet e.g. Firefox, Chrome, Opera etc.

Coincidentally, <browser> is also an element in XUL. It is a component that can load web pages, make http requests and respond accordingly. In firefox, each tab has is associated with one <browser>.

<tabbrowser> and gBrowser

<tabbrowser> is also an element in XUL. It can contain multiple tabs each of which is associated with one <browser>. So in a firefox window, if you exclude toolbars, titlebar, sidebar and addonbar, whatever is remaining is roughly <tabbrowser>

If you have an overlay for browser.xul in your extensions' chrome.manifest and include a script, the overlay would be applied to every firefox window and script will run for every firefox window independently. The script will have access to variables defined and initialized by browser.xul. One such variable is gBrowser that points to <tabbrowser> in current Firefox (OS) window. So each Firefox window will have one <tabbrowser> that can be accessed using gBrowser variable in overlay script.

If you look at documentation of <tabbrowser>, it is very useful e.g. adding a new tab, finding selected browser etc.

Firefox Window

A firefox window is actually based upon browser.xul. This file contains all the elements that you see on the firefox window. (e.g. toolbars, urlbar, tabbed interface etc.). One of such elements is <tabbrowser> element with id=content. The <tabbrowser> element contains 1 or more panels, each of which contains a <browser>. So if there are 3 tabs open in firefox window, there will be 3 <browser> elements.

Accessing Window Elements:

When a javascript file is included from a xul overlay, it is said to execute in "chrome context". In chrome context, window refers to top-level firefox window and document refers to xul document (i.e. browser.xul)

Such a script has access to every element of XUL document. You can, for example, use document.getElementById("urlbar-container") to access urlbar of current window. You should get yourself familiar with DOM Inspector that can help you in finding ids of elements and understanding XUL document.

contentDocument in tabbbrowser

Look at the code of tabbrowser.xul:

<property name="contentDocument"
   onget="return this.mCurrentBrowser.contentDocument;"
   readonly="true"/>

I hope this is self explanatory :). This may not make sense but is really handy in the code. If this property would have been named as activeContentDocument, it would have been more understandable.

MXR is really handy to find the answers of such questions.

window Object:

See the <browser> code:

<property name="contentWindow"
  readonly="true"
  onget="return this._contentWindow || (this._contentWindow = this.docShell.QueryInterface(Components.interfaces.nsIInterfaceRequestor).getInterface(Components.interfaces.nsIDOMWindow));"/>

But I hope someone else may have a better explanation.

tabbrowser and tabs

<tabbrowser> and <tabs> work together. The <tabs> element is what you are referring to rectangle containing open tabs. Dom inspector reveals that :

<tabbrowser id="content" tabcontainer="tabbrowser-tabs" ...

and

<tabs id="tabbrowser-tabs" tabbrowser="content" ...

So both depend on each other although these are two different XUL elements.