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("https://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
- selectedTab
- The currently selected tab, represented as a
Tab
object. - deck
- A
deck
ofbrowser
objects. You can use this to listen forTabOpen
,TabClose
, andTabSelect
events. - selectedBrowser
- The
browser
for the currently selected tab. A shortcut forBrowserApp.selectedTab.browser
.