mozilla

Revision 58508 of Tabbed browser

  • Revision slug: Code_snippets/Tabbed_browser
  • Revision title: Tabbed browser
  • Revision id: 58508
  • Created:
  • Creator: Jrm
  • Is current revision? No
  • Comment add gBrowser event listener on main window load

Revision Content

Here you should find a set of useful code snippets to help you work with Firefox's tabbed browser. The comments normally mark where you should be inserting your own code.

Each snippet normally includes some code to run at initialization, these are best run using a load listener. These snippets assume they are run in the context of a browser window. If you need to work with tabs from a non-browser window, you need to obtain a reference to one first, see Working with windows in chrome code for details.

Note that Firefox 2 has made detecting changes to the tabs far easier, if you are only developing for Firefox 2 and greater you should use the examples for that. The examples for Firefox 1.5 and lower will usually work OK on Firefox 2.

See also the XUL {{template.XULElem("tabbrowser")}} element reference. gBrowser object (same as getBrowser()) is a tabbrowser element.

Opening a new tab

// Add tab  
gBrowser.addTab("http://www.google.com/");

// Add tab, then make active
gBrowser.selectedTab = gBrowser.addTab("http://www.google.com/");

Detecting page load

function examplePageLoad(event)
{
  if (event.originalTarget instanceof HTMLDocument) {
    var doc = event.originalTarget;
    if (event.originalTarget.defaultView.frameElement) {
      // Frame within a tab was loaded. doc should be the root document of
      // the frameset. If you don't want do anything when frames/iframes
      // are loaded in this web page, uncomment the following line:
      // return;
      // Find the root document:
      while (doc.defaultView.frameElement) {
        doc=doc.defaultView.frameElement.ownerDocument;
      }
    }
  }
}

// do not try to add a callback until the browser window has
// been initialised. We add a callback to the tabbed browser
// when the browser's window gets loaded.
window.addEventListener(
  "load",
  function () {
    // Add a callback to be run every time a document loads.
    // note that this includes frames/iframes within the document
    gBrowser.addEventListener("load", examplePageLoad, true);
  },
  false
);

...
// When no longer needed
gBrowser.removeEventListener("load", examplePageLoad, true);
...

Notification when a tab is added or removed (<= Firefox 1.5)

function exampleTabAdded(event)
{ // listening for new tabs
  if (event.relatedNode != gBrowser.mPanelContainer)
    return; //Could be anywhere in the DOM (unless bubbling is caught at the interface?)

  var browser;
  if (event.target.localName == "browser") // SeaMonkey
    browser = event.target;
  else if (event.target.localName == "vbox") // Firefox
    browser = event.target.childNodes[1];
  // browser is the XUL element of the browser that's been added
}

function exampleTabRemoved(event)
{
  if (event.relatedNode != gBrowser.mPanelContainer)
    return;

  var browser;
  if (event.target.localName == "browser") // SeaMonkey
    browser = event.target;
  else if (event.target.localName == "vbox") // Firefox
    browser = event.target.childNodes[1];
  // browser is the XUL element of the browser that's been removed
}

// During initialisation
var container = gBrowser.mPanelContainer;
container.addEventListener("DOMNodeInserted", exampleTabAdded, false);
container.addEventListener("DOMNodeRemoved", exampleTabRemoved, false);

// When no longer needed
container.removeEventListener("DOMNodeInserted", exampleTabAdded, false);
container.removeEventListener("DOMNodeRemoved", exampleTabRemoved, false);

Notification when a tab is added or removed (Firefox 2+)

function exampleTabAdded(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been added
}

function exampleTabMoved(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been moved
}

function exampleTabRemoved(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been removed
}

// During initialisation
var container = gBrowser.tabContainer;
container.addEventListener("TabOpen", exampleTabAdded, false);
container.addEventListener("TabMove", exampleTabMoved, false);
container.addEventListener("TabClose", exampleTabRemoved, false);

// When no longer needed
container.removeEventListener("TabOpen", exampleTabAdded, false);
container.removeEventListener("TabMove", exampleTabMoved, false);
container.removeEventListener("TabClose", exampleTabRemoved, false);

Detecting tab selection (<= Firefox 1.5)

The following code allows you to detect when a new tab is selected in the browser:

function exampleTabSelected(event)
{
  var browser = gBrowser.getBrowserAtIndex(gBrowser.mTabContainer.selectedIndex);
  // browser is the newly selected tab
}

// During initialisation
var container = gBrowser.mPanelContainer;
container.addEventListener("select", exampleTabSelected, false);

// When no longer needed
var container = gBrowser.mPanelContainer;
container.removeEventListener("select", exampleTabSelected, false);

Detecting tab selection (Firefox 2+)

The following code allows you to detect when a new tab is selected in the browser:

function exampleTabSelected(event)
{
  var browser = gBrowser.selectedTab;
  // browser is the newly selected tab
}

// During initialisation
var container = gBrowser.tabContainer;
container.addEventListener("TabSelect", exampleTabSelected, false);

// When no longer needed
container.removeEventListener("TabSelect", exampleTabSelected, false);

Getting document of currently selected tab

The following code allows you to retrieve the document that is in the selected tab:

gBrowser.selectedBrowser.contentDocument;

or

content.document

See also Working with windows in chrome code.

{{ wiki.languages( { "fr": "fr/Extraits_de_code/Onglets_de_navigation" } ) }}

Revision Source

<p>
Here you should find a set of useful code snippets to help you work with Firefox's tabbed browser. The comments normally mark where you should be inserting your own code.
</p><p>Each snippet normally includes some code to run at initialization, these are best run using a <a href="en/Extension_Frequently_Asked_Questions#Why_doesn.27t_my_script_run_properly.3F">load listener</a>. These snippets assume they are run in the context of a browser window. If you need to work with tabs from a non-browser window, you need to obtain a reference to one first, see <a href="en/Working_with_windows_in_chrome_code">Working with windows in chrome code</a> for details.
</p><p>Note that <a href="en/Firefox_2">Firefox 2</a> has made detecting changes to the tabs far easier, if you are only developing for Firefox 2 and greater you should use the examples for that. The examples for Firefox 1.5 and lower will usually work OK on Firefox 2.
</p><p>See also the XUL {{template.XULElem("tabbrowser")}} element reference. <code>gBrowser</code> object (same as <code>getBrowser()</code>) is a <code>tabbrowser</code> element.
</p>
<h3 name="Opening_a_new_tab"> Opening a new tab </h3>
<pre>// Add tab  
gBrowser.addTab("http://www.google.com/");

// Add tab, then make active
gBrowser.selectedTab = gBrowser.addTab("http://www.google.com/");
</pre>
<h3 name="Detecting_page_load"> Detecting page load </h3>
<pre>function examplePageLoad(event)
{
  if (event.originalTarget instanceof HTMLDocument) {
    var doc = event.originalTarget;
    if (event.originalTarget.defaultView.frameElement) {
      // Frame within a tab was loaded. doc should be the root document of
      // the frameset. If you don't want do anything when frames/iframes
      // are loaded in this web page, uncomment the following line:
      // return;
      // Find the root document:
      while (doc.defaultView.frameElement) {
        doc=doc.defaultView.frameElement.ownerDocument;
      }
    }
  }
}

// do not try to add a callback until the browser window has
// been initialised. We add a callback to the tabbed browser
// when the browser's window gets loaded.
window.addEventListener(
  "load",
  function () {
    // Add a callback to be run every time a document loads.
    // note that this includes frames/iframes within the document
    gBrowser.addEventListener("load", examplePageLoad, true);
  },
  false
);

...
// When no longer needed
gBrowser.removeEventListener("load", examplePageLoad, true);
...
</pre>
<h3 name="Notification_when_a_tab_is_added_or_removed_.28.3C.3D_Firefox_1.5.29"> Notification when a tab is added or removed (&lt;= Firefox 1.5) </h3>
<pre>function exampleTabAdded(event)
{ // listening for new tabs
  if (event.relatedNode != gBrowser.mPanelContainer)
    return; //Could be anywhere in the DOM (unless bubbling is caught at the interface?)

  var browser;
  if (event.target.localName == "browser") // SeaMonkey
    browser = event.target;
  else if (event.target.localName == "vbox") // Firefox
    browser = event.target.childNodes[1];
  // browser is the XUL element of the browser that's been added
}

function exampleTabRemoved(event)
{
  if (event.relatedNode != gBrowser.mPanelContainer)
    return;

  var browser;
  if (event.target.localName == "browser") // SeaMonkey
    browser = event.target;
  else if (event.target.localName == "vbox") // Firefox
    browser = event.target.childNodes[1];
  // browser is the XUL element of the browser that's been removed
}

// During initialisation
var container = gBrowser.mPanelContainer;
container.addEventListener("DOMNodeInserted", exampleTabAdded, false);
container.addEventListener("DOMNodeRemoved", exampleTabRemoved, false);

// When no longer needed
container.removeEventListener("DOMNodeInserted", exampleTabAdded, false);
container.removeEventListener("DOMNodeRemoved", exampleTabRemoved, false);
</pre>
<h3 name="Notification_when_a_tab_is_added_or_removed_.28Firefox_2.2B.29"> Notification when a tab is added or removed (Firefox 2+) </h3>
<pre>function exampleTabAdded(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been added
}

function exampleTabMoved(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been moved
}

function exampleTabRemoved(event)
{
  var browser = event.target.linkedBrowser;
  // browser is the XUL element of the browser that's been removed
}

// During initialisation
var container = gBrowser.tabContainer;
container.addEventListener("TabOpen", exampleTabAdded, false);
container.addEventListener("TabMove", exampleTabMoved, false);
container.addEventListener("TabClose", exampleTabRemoved, false);

// When no longer needed
container.removeEventListener("TabOpen", exampleTabAdded, false);
container.removeEventListener("TabMove", exampleTabMoved, false);
container.removeEventListener("TabClose", exampleTabRemoved, false);
</pre>
<h3 name="Detecting_tab_selection_.28.3C.3D_Firefox_1.5.29"> Detecting tab selection (&lt;= Firefox 1.5) </h3>
<p>The following code allows you to detect when a new tab is selected in the browser:
</p>
<pre>function exampleTabSelected(event)
{
  var browser = gBrowser.getBrowserAtIndex(gBrowser.mTabContainer.selectedIndex);
  // browser is the newly selected tab
}

// During initialisation
var container = gBrowser.mPanelContainer;
container.addEventListener("select", exampleTabSelected, false);

// When no longer needed
var container = gBrowser.mPanelContainer;
container.removeEventListener("select", exampleTabSelected, false);
</pre>
<h3 name="Detecting_tab_selection_.28Firefox_2.2B.29"> Detecting tab selection (Firefox 2+) </h3>
<p>The following code allows you to detect when a new tab is selected in the browser:
</p>
<pre>function exampleTabSelected(event)
{
  var browser = gBrowser.selectedTab;
  // browser is the newly selected tab
}

// During initialisation
var container = gBrowser.tabContainer;
container.addEventListener("TabSelect", exampleTabSelected, false);

// When no longer needed
container.removeEventListener("TabSelect", exampleTabSelected, false);
</pre>
<h3 name="Getting_document_of_currently_selected_tab"> Getting document of currently selected tab </h3>
<p>The following code allows you to retrieve the document that is in the selected tab:
</p>
<pre class="eval">gBrowser.selectedBrowser.contentDocument;
</pre>
<p>or
</p>
<pre class="eval">content.document
</pre>
<p>See also <a href="en/Working_with_windows_in_chrome_code#Content_windows">Working with windows in chrome code</a>.
</p>{{ wiki.languages( { "fr": "fr/Extraits_de_code/Onglets_de_navigation" } ) }}
Revert to this revision