BrowserApp

The BrowserApp object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.

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/");
}

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.
 

Document Tags and Contributors

Contributors to this page: wbamberg, MarkFinkle
Last updated by: MarkFinkle,