Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Revision 992951 of tabs/utils

  • Revision slug: Mozilla/Add-ons/SDK/Low-Level_APIs/tabs_utils
  • Revision title: tabs/utils
  • Revision id: 992951
  • Created:
  • Creator: wbamberg
  • Is current revision? Yes
  • Comment

Revision Content
{{AddonSidebar}}

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.

 

Revision Source

 
{{AddonSidebar}}

<div class="note">
<p>Unstable</p>
</div>

<div class="note">
<p>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 <a href="/en-US/Add-ons/SDK/Guides/Multiprocess_Firefox_and_the_SDK">Multiprocess Firefox and the SDK</a> for more details.</p>
</div>

<p><span class="seoSummary">Functions for working with XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tabs</code></a> and the XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser"><code>tabbrowser</code></a> object.</span></p>

<h2 id="Globals">Globals</h2>

<h3 id="Functions">Functions</h3>

<h4 class="addon-sdk-api-name" id="activateTab(tab_window)"><code>activateTab(tab, window)</code></h4>

<p>Set the specified tab as the active, or <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser#p-selectedTab">selected</a>, tab.</p>

<h5 id="Parameters">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A <a href="https://developer.mozilla.org/en-US/docs/XUL/tab">XUL <code>tab</code> element</a> to activate.</p>

<p><strong>window : window</strong><br />
 A browser window.</p>

<h4 class="addon-sdk-api-name" id="getTabBrowser(window)"><code>getTabBrowser(window)</code></h4>

<p>Get the <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser"><code>tabbrowser</code></a> element for the given browser window.</p>

<h5 id="Parameters_2">Parameters</h5>

<p><strong>window : window</strong><br />
 A browser window.</p>

<h5 id="Returns">Returns</h5>

<p><strong>tabbrowser</strong> :</p>

<h4 class="addon-sdk-api-name" id="getTabContainer(window)"><code>getTabContainer(window)</code></h4>

<p>Get the <code>tabbrowser</code>'s <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser#p-tabContainer"><code>tabContainer</code></a> property.</p>

<h5 id="Parameters_3">Parameters</h5>

<p><strong>window : window</strong><br />
 A browser window.</p>

<h5 id="Returns_2">Returns</h5>

<p><strong>tabContainer</strong> :</p>

<h4 class="addon-sdk-api-name" id="getTabs(window)"><code>getTabs(window)</code></h4>

<p>Returns the tabs for the specified <code>window</code>.</p>

<p>If you omit <code>window</code>, 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.</p>

<p>To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the <a href="/en-US/Add-ons/SDK/High-Level_APIs/private-browsing">documentation for the <code>private-browsing</code> module</a>.</p>

<h5 id="Parameters_4">Parameters</h5>

<p><strong>window : nsIWindow</strong><br />
 Optional.</p>

<h5 id="Returns_3">Returns</h5>

<p><strong>Array</strong> : An array of <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> elements.</p>

<h4 class="addon-sdk-api-name" id="getActiveTab(window)"><code>getActiveTab(window)</code></h4>

<p>Given a browser window, get the active, or <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser#p-selectedTab">selected</a>, tab.</p>

<h5 id="Parameters_5">Parameters</h5>

<p><strong>window : window</strong><br />
 A browser window.</p>

<h5 id="Returns_4">Returns</h5>

<p><strong>tab</strong> : The currently selected <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a>.</p>

<h4 class="addon-sdk-api-name" id="getOwnerWindow(tab)"><code>getOwnerWindow(tab)</code></h4>

<p>Get the browser window that owns the specified <code>tab</code>.</p>

<h5 id="Parameters_6">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A browser <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a>.</p>

<h5 id="Returns_5">Returns</h5>

<p><strong>window</strong> : A browser window.</p>

<h4 class="addon-sdk-api-name" id="openTab(window_url_options)"><code>openTab(window, url, options)</code></h4>

<p>Open a new tab in the specified browser window.</p>

<h5 id="Parameters_7">Parameters</h5>

<p><strong>window : window</strong><br />
 The browser window in which to open the tab.</p>

<p><strong>url : String</strong><br />
 URL for the document to load.</p>

<p><strong>options : object</strong><br />
 Optional options:</p>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col">&nbsp;</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>inBackground</td>
   <td>boolean</td>
   <td>
    <p>If <code>true</code>, open the new tab, but keep the currently selected tab selected. If <code>false</code>, make the new tab the selected tab. Optional, defaults to <code>false</code>.</p>
   </td>
  </tr>
  <tr>
   <td>pinned</td>
   <td>boolean</td>
   <td>
    <p>Pin this tab. Optional, defaults to <code>false</code>.</p>
   </td>
  </tr>
 </tbody>
</table>

<h5 id="Returns_6">Returns</h5>

<p><strong>tab</strong> : The new <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a>.</p>

<h4 class="addon-sdk-api-name" id="isTabOpen(tab)"><code>isTabOpen(tab)</code></h4>

<p>Test whether the specified tab is open.</p>

<h5 id="Parameters_8">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_7">Returns</h5>

<p><strong>boolean</strong> : <code>true</code> if the tab is open, otherwise <code>false</code>.</p>

<h4 class="addon-sdk-api-name" id="closeTab(tab)"><code>closeTab(tab)</code></h4>

<p>Close the specified tab.</p>

<h5 id="Parameters_9">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h4 class="addon-sdk-api-name" id="getURI(tab)"><code>getURI(tab)</code></h4>

<p>Get the specified tab's URI.</p>

<h5 id="Parameters_10">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_8">Returns</h5>

<p><strong>String</strong> : The current URI.</p>

<h4 class="addon-sdk-api-name" id="getTabBrowserForTab(tab)"><code>getTabBrowserForTab(tab)</code></h4>

<p>Get the specified tab's <a href="https://developer.mozilla.org/en-US/docs/XUL/tabbrowser"><code>tabbrowser</code></a>.</p>

<h5 id="Parameters_11">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_9">Returns</h5>

<p><strong>tabbrowser</strong> :</p>

<h4 class="addon-sdk-api-name" id="getBrowserForTab(tab)"><code>getBrowserForTab(tab)</code></h4>

<p>Get the specified tab's <a href="https://developer.mozilla.org/en-US/docs/XUL/browser"><code>browser</code></a>.</p>

<h5 id="Parameters_12">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_10">Returns</h5>

<p><strong>browser</strong> :</p>

<h4 class="addon-sdk-api-name" id="getTabId(tab)"><code>getTabId(tab)</code></h4>

<p>Get the specified tab's ID. On Firefox for Android this is the <a href="/en-US/Add-ons/Firefox_for_Android/API/Tab">tab's <code>id</code> property</a>, and on Firefox Desktop it's derived from its <a href="/en-US/docs/Mozilla/Tech/XUL/Attribute/linkedpanel"><code>linkedPanel</code></a> property.</p>

<h5 id="Parameters_13">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element or a Firefox for Android <a href="/en-US/Add-ons/Firefox_for_Android/API/Tab"><code>Tab</code></a> object.</p>

<h5 id="Returns_11">Returns</h5>

<p><strong>id</strong> : the ID for this tab.</p>

<h4 class="addon-sdk-api-name" id="getTabForId(id)"><code>getTabForId(id)</code></h4>

<p>Get the tab identified by <code>id</code>.</p>

<h5 id="Parameters_14">Parameters</h5>

<p><strong>id : </strong><br />
 On Firefox for Android this is the <a href="/en-US/Add-ons/Firefox_for_Android/API/Tab">tab's <code>id</code> property</a>, and on Firefox Desktop it's derived from its <a href="/en-US/docs/Mozilla/Tech/XUL/Attribute/linkedpanel"><code>linkedPanel</code></a> property.</p>

<h5 id="Returns_12">Returns</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element or a Firefox for Android <a href="/en-US/Add-ons/Firefox_for_Android/API/Tab"><code>Tab</code></a> object.</p>

<h4 class="addon-sdk-api-name" id="getTabTitle(tab)"><code>getTabTitle(tab)</code></h4>

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

<h5 id="Parameters_15">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_13">Returns</h5>

<p><strong>String</strong> :</p>

<h4 class="addon-sdk-api-name" id="setTabTitle(tab_title)"><code>setTabTitle(tab, title)</code></h4>

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

<h5 id="Parameters_16">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<p><strong>title : String</strong><br />
 The new title.</p>

<h4 class="addon-sdk-api-name" id="getTabContentWindow(tab)"><code>getTabContentWindow(tab)</code></h4>

<p>Get the specified tab's content window.</p>

<h5 id="Parameters_17">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_14">Returns</h5>

<p><strong>window</strong> :</p>

<h4 class="addon-sdk-api-name" id="getAllTabContentWindows()"><code>getAllTabContentWindows()</code></h4>

<p>Get all tabs' content windows across all the browsers' windows.</p>

<h5 id="Returns_15">Returns</h5>

<p><strong>Array</strong> : Array of windows.</p>

<h4 class="addon-sdk-api-name" id="getTabForContentWindow(window)"><code>getTabForContentWindow(window)</code></h4>

<p>Get the tab element that hosts the specified content window.</p>

<h5 id="Parameters_18">Parameters</h5>

<p><strong>window : window</strong></p>

<h5 id="Returns_16">Returns</h5>

<p><strong>tab</strong> :</p>

<h4 class="addon-sdk-api-name" id="getTabURL(tab)"><code>getTabURL(tab)</code></h4>

<p>Get the specified tab's URL.</p>

<h5 id="Parameters_19">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_17">Returns</h5>

<p><strong>String</strong> : The current URI.</p>

<h4 class="addon-sdk-api-name" id="setTabURL(tab_url)"><code>setTabURL(tab, url)</code></h4>

<p>Set the specified tab's URL.</p>

<h5 id="Parameters_20">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<p><strong>url : String</strong></p>

<h4 class="addon-sdk-api-name" id="getTabContentType(tab)"><code>getTabContentType(tab)</code></h4>

<p>Get the <a href="https://developer.mozilla.org/en-US/docs/DOM/document.contentType"><code>contentType</code></a> of the document hosted by the specified tab.</p>

<h5 id="Parameters_21">Parameters</h5>

<p><strong>tab : tab</strong><br />
 A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h5 id="Returns_18">Returns</h5>

<p><strong>String</strong> :</p>

<h4 class="addon-sdk-api-name" id="getSelectedTab(window)"><code>getSelectedTab(window)</code></h4>

<p>Get the selected tab for the specified browser window.</p>

<h5 id="Parameters_22">Parameters</h5>

<p><strong>window : window</strong></p>

<h5 id="Returns_19">Returns</h5>

<p><strong>tab</strong> : A XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element.</p>

<h4 class="addon-sdk-api-name" id="getTabForBrowser(browser)"><code>getTabForBrowser(browser)</code></h4>

<p>Get the <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> linked to the specified <a href="https://developer.mozilla.org/en-US/docs/XUL/browser"><code>browser</code></a>.</p>

<h5 id="Parameters_23">Parameters</h5>

<p><strong>browser : browser</strong><br />
 the <a href="https://developer.mozilla.org/en-US/docs/XUL/browser"><code>browser</code></a> whose <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element we want to find.</p>

<h5 id="Returns_20">Returns</h5>

<p><strong>tab</strong> :</p>

<p>the XUL <a href="https://developer.mozilla.org/en-US/docs/XUL/tab"><code>tab</code></a> element linked to the specified <a href="https://developer.mozilla.org/en-US/docs/XUL/browser"><code>browser</code></a>, if any.</p>

<p>&nbsp;</p>
Revert to this revision