tabs/utils

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Unstable

Note that this module includes functions that give you direct access to web content. These functions are not safe to call in multiprocess Firefox. See Multiprocess Firefox and the SDK for more details.

Functions for working with XUL tabs and the XUL tabbrowser object.

Globals

Functions

activateTab(tab, window)

Set the specified tab as the active, or selected, tab.

Parameters

tab : tab
A XUL tab element to activate.

window : window
A browser window.

getTabBrowser(window)

Get the tabbrowser element for the given browser window.

Parameters

window : window
A browser window.

Returns

tabbrowser :

getTabContainer(window)

Get the tabbrowser's tabContainer property.

Parameters

window : window
A browser window.

Returns

tabContainer :

getTabs(window)

Returns the tabs for the specified window.

If you omit window, this function will return tabs across all the browser's windows. However, if your add-on has not opted into private browsing, then the function will exclude all tabs that are hosted by private browser windows.

To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the documentation for the private-browsing module.

Parameters

window : nsIWindow
Optional.

Returns

Array : An array of tab elements.

getActiveTab(window)

Given a browser window, get the active, or selected, tab.

Parameters

window : window
A browser window.

Returns

tab : The currently selected tab.

getOwnerWindow(tab)

Get the browser window that owns the specified tab.

Parameters

tab : tab
A browser tab.

Returns

window : A browser window.

openTab(window, url, options)

Open a new tab in the specified browser window.

Parameters

window : window
The browser window in which to open the tab.

url : String
URL for the document to load.

options : object
Optional options:

Name Type  
inBackground boolean

If true, open the new tab, but keep the currently selected tab selected. If false, make the new tab the selected tab. Optional, defaults to false.

pinned boolean

Pin this tab. Optional, defaults to false.

Returns

tab : The new tab.

isTabOpen(tab)

Test whether the specified tab is open.

Parameters

tab : tab
A XUL tab element.

Returns

boolean : true if the tab is open, otherwise false.

closeTab(tab)

Close the specified tab.

Parameters

tab : tab
A XUL tab element.

getURI(tab)

Get the specified tab's URI.

Parameters

tab : tab
A XUL tab element.

Returns

String : The current URI.

getTabBrowserForTab(tab)

Get the specified tab's tabbrowser.

Parameters

tab : tab
A XUL tab element.

Returns

tabbrowser :

getBrowserForTab(tab)

Get the specified tab's browser.

Parameters

tab : tab
A XUL tab element.

Returns

browser :

getTabId(tab)

Get the specified tab's ID. On Firefox for Android this is the tab's id property, and on Firefox Desktop it's derived from its linkedPanel property.

Parameters

tab : tab
A XUL tab element or a Firefox for Android Tab object.

Returns

id : the ID for this tab.

getTabForId(id)

Get the tab identified by id.

Parameters

id :
On Firefox for Android this is the tab's id property, and on Firefox Desktop it's derived from its linkedPanel property.

Returns

tab : tab
A XUL tab element or a Firefox for Android Tab object.

getTabTitle(tab)

Get the title of the document hosted by the specified tab, or the tab's label if the tab doesn't host a document.

Parameters

tab : tab
A XUL tab element.

Returns

String :

setTabTitle(tab, title)

Set the title of the document hosted by the specified tab, or the tab's label if the tab doesn't host a document.

Parameters

tab : tab
A XUL tab element.

title : String
The new title.

getTabContentWindow(tab)

Get the specified tab's content window.

Parameters

tab : tab
A XUL tab element.

Returns

window :

getAllTabContentWindows()

Get all tabs' content windows across all the browsers' windows.

Returns

Array : Array of windows.

getTabForContentWindow(window)

Get the tab element that hosts the specified content window.

Parameters

window : window

Returns

tab :

getTabURL(tab)

Get the specified tab's URL.

Parameters

tab : tab
A XUL tab element.

Returns

String : The current URI.

setTabURL(tab, url)

Set the specified tab's URL.

Parameters

tab : tab
A XUL tab element.

url : String

getTabContentType(tab)

Get the contentType of the document hosted by the specified tab.

Parameters

tab : tab
A XUL tab element.

Returns

String :

getSelectedTab(window)

Get the selected tab for the specified browser window.

Parameters

window : window

Returns

tab : A XUL tab element.

getTabForBrowser(browser)

Get the tab linked to the specified browser.

Parameters

browser : browser
the browser whose tab element we want to find.

Returns

tab :

the XUL tab element linked to the specified browser, if any.

 

Document Tags and Contributors

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