BrowserApp

Summary

Add-ons running on desktop Firefox can use the global gBrowser variable to interact with tabs and any HTML content they host. This object isn't available on Firefox for Android, and instead add-ons should use the BrowserApp object, which provides much of the same functionality.

BrowserApp is available as a property of the chrome window object. For example, if you use this template for initializing your add-on, you can access it from the window argument passed into loadIntoWindow():

function loadIntoWindow(window) {
  if (!window)
    return;
  window.BrowserApp.addTab("http://example.com/");
}

Obtain BrowserApp object with add-on SDK:

// Obtain component object : Chrome Authority
// https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Chrome_Authority
var { Cu } = require("chrome");
// Obtain commonly used services : Services.jsm
// https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/Services.jsm
Cu.import("resource://gre/modules/Services.jsm");
function getBrowserApp() {
	let window = Services.wm.getMostRecentWindow("navigator:browser");
	return window.BrowserApp;
}

BrowserApp provides four main areas of functionality:

• Enumerating and retrieving tabs.
• Retrieving XUL browser objects.
• Manipulating tabs: opening, closing, and selecting tabs.
• Listening for tab events.

Enumerating and retrieving tabs

Tabs are represented as Tab objects, which include an API to access the content window they host.

// Log the titles of all open tabs
function logTabTitles(window) {
  var tabs = window.BrowserApp.tabs;
  tabs.forEach(function(tab) {
    window.console.log(tab.browser.contentTitle);
  });
}
// Get the selected tab
let tab = BrowserApp.selectedTab;
// Look up tab using an ID
let tab = BrowserApp.getTabForId(aID);
// Look up tab using a browser
let tab = BrowserApp.getTabForBrowser(aBrowser);
// Look up tab using a DOM window
let tab = BrowserApp.getTabForWindow(aWindow);

Retrieving XUL browser objects

// Get the selected browser
let selectedBrowser = BrowserApp.selectedTab.browser;
// Get the selected browser ( a shortcut)
let selectedBrowser = BrowserApp.selectedBrowser;
// Look up browser using a tab
let browser = tab.browser;
// Look up browser using a DOM window
let browser = BrowserApp.getBrowserForWindow(aWindow);
// Look up browser using a DOM document
let browser = BrowserApp.getBrowserForDocument(aDocument);

Manipulating browser tabs

// Add a tab
let tab = BrowserApp.addTab();
// Close a tab
BrowserApp.closeTab(tab);
// Select a tab
BrowserApp.selectTab(tab);

Listening for tab events

// Listening for tab events
function watchTab(aEvent) {
  // the target is a XUL browser element
  let browser = aEvent.target;
}
BrowserApp.deck.addEventListener("TabOpen", watchTab, false);
BrowserApp.deck.addEventListener("TabClose", watchTab, false);
BrowserApp.deck.addEventListener("TabSelect", watchTab, false);

Methods

getTabForId

Retrieve a tab, given its ID.

getTabForBrowser

Retrieve a tab, given its browser.

getTabForWindow

Retrieve a tab, given its DOM window.

getBrowserForWindow

Retrieve a browser, given its DOM window.

getBrowserForDocument

Retrieve a browser, given its DOM document.

addTab

Open a new tab.

closeTab

Close a tab.

selectTab

Set a tab as the selected tab.

loadURI

Load a URI into the specified browser.

getPreferences

Retrieve a set of preferences.

setPreferences

Set a single preference.

quit

Quit Firefox for Android.

Properties 

tabs

An Array of all currently open tabs, represented as Tab objects.

selectedTab

The currently selected tab, represented as a Tab object.

deck

A deck of browser objects. You can use this to listen for TabOpen, TabClose, and TabSelect events.

selectedBrowser

The browser for the currently selected tab. A shortcut for BrowserApp.selectedTab.browser.