ui/toolbar

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.

Experimental

Add a toolbar to the Firefox user interface. A toolbar is a horizontal strip of user interface real estate. Like a panel, a toolbar's content is specified using HTML. Unlike a panel, a toolbar:

  • does not overlap with any web content
  • is persistent, remaining visible until the user chooses to close it
  • is a fixed size, and appears in a fixed location

Usage

Creating and destroying toolbars

You don't specify toolbar content directly: instead, you create other UI components and supply them to the Toolbar constructor. You can supply three sorts of UI components:

This add-on builds part of the user interface for a music player using action buttons for the controls and a frame to display art and the currently playing song:

var { ActionButton } = require('sdk/ui/button/action');
var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var previous = ActionButton({
  id: "previous",
  label: "previous",
  icon: "./icons/previous.png"
});
var next = ActionButton({
  id: "next",
  label: "next",
  icon: "./icons/next.png"
});
var play = ActionButton({
  id: "play",
  label: "play",
  icon: "./icons/play.png"
});
var frame = new Frame({
  url: "./frame-player.html"
});
var toolbar = Toolbar({
  title: "Player",
  items: [previous, next, play, frame]
});

The toolbar appears just above the content window:

To destroy a Toolbar call its destroy() method.

Showing and hiding toolbars

By default, a toolbar is shown when it is created, although you can specify that a toolbar should be hidden initially by passing hidden:true as an option in its constructor.

After that, though, you can't show or hide the toolbar programmatically. Toolbars get a close button at the right-hand side, and users can show or hide the toolbar using the Firefox "View/Toolbars" menu, alongside built-in toolbars like the Bookmarks Toolbar.

Hidden state persists even over create/destroy cycles: if a toolbar is created, then hidden, then destroyed, and another toolbar with the same title is then created, the new toolbar will be in the hidden state.

Toolbar events

Toolbars get attach and detach events when their content is loaded and unloaded, and show and hide events when the uses shows or hides them.

Working with multiple browser windows

There's only a single toolbar for all browser windows, so operations like show and hide work across all browser windows. If you need to customize content for a particular browser window, you can do that by messaging the window-specific Frame hosted by that toolbar.

Globals

Constructors

Toolbar(options)

Creates a toolbar. The only mandatory option is title, but for the toolbar to contain any actual content, the items parameter must also be supplied, and must contain at least object. This add-on creates a toolbar containing one button and a frame:

var { ActionButton } = require('sdk/ui/button/action');
var { Frame } = require("sdk/ui/frame");
var { Toolbar } = require("sdk/ui/toolbar");
var button = ActionButton({
  id: "my-button",
  label: "my-button",
  icon: "./my-button.png"
});
var frame = new Frame({
  url: "./my-frame.html"
});
var toolbar = Toolbar({
  title: "Player",
  items: [button, frame]
});

This add-on creates a toolbar with one frame, that's hidden initially, and that logs show and hide events:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame],
  hidden: true,
  onShow: showing,
  onHide: hiding
});
function showing(e) {
  console.log("showing");
  console.log(e);
}
function hiding(e) {
  console.log("hiding");
  console.log(e);
}
Parameters

options : object
Required options:

Name Type  
title string

The toolbar's title. This appears as the name of the toolbar in the Firefox "Toolbars" menu. It must be unique.

Optional options:

Name Type  
items array

Adding buttons to toolbars is only supported from Firefox 30 onwards. In Firefox 29, you can only add frames.

An array of items to appear in the toolbar. Each item in items must be an action button, a toggle button, or a frame instance. Buttons each take up a fixed width. If more than one frame is supplied here, the frames each occupy an equal vertical strip of the toolbar.

hidden boolean

Boolean indicating whether the frame should be hidden initially or not. Defaults to false.

onAttach function

Assign a listener to the attach event.

onDetach function

Assign a listener to the detach event.

onShow function

Assign a listener to the show event.

onHide function

Assign a listener to the hide event.

Toolbar

Methods

on(event, listener)

Assign a listener to an event:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("show", showing);
toolbar.on("hide", hiding);
function showing(e) {
  console.log("showing: " + e.title);
}
function hiding(e) {
  console.log("hiding: " + e.title);
}
Parameters

event : string
The name of the event to listen to. Toolbar supports the following events: attach, detach, show, and hide.

listener : function
The listener function. This may be passed arguments, depending on the particular event.

once(event, listener)

Assign a listener to the first occurrence only of an event emitted by the toolbar. Toolbar supports the following events: attach, detach, show, and hide. The listener is automatically removed after the first time the event is emitted.

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.once("show", showing);
toolbar.once("hide", hiding);
function showing(e) {
  console.log("showing: " + e.title);
}
function hiding(e) {
  console.log("hiding: " + e.title);
}
Parameters

event : string
The name of the event to listen to. Toolbar supports the following events: attach, detach, show, and hide.

listener : function
The listener function. This may be passed arguments, depending on the particular event.

removeListener(event, listener)

Removes an event listener. For example, this code is equivalent to once():

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("show", showing);
toolbar.on("hide", hiding);
function showing(e) {
  console.log("showing: " + e.title);
  toolbar.removeListener("show", showing);
}
function hiding(e) {
  console.log("hiding: " + e.title);
  toolbar.removeListener("hide", hiding);
}
Parameters

event : string
The event the listener is listening for. Toolbar supports the following events: attach, detach, show, and hide.

listener : function
The listener to remove.

off(event, listener)

This function is an alias for removeListener().

Parameters

event : string
The event the listener is listening for. Toolbar supports the following events: attach, detach, show, and hide.

listener : function
The listener to remove.

destroy()

Destroys the toolbar. After calling this function, the toolbar will no longer be visible and its menu item will no longer appear in the Firefox "Toolbars" menu. Calling this function also causes the detach event to be emitted.

Properties

title

The toolbar's title. This is read-only and must be unique. It's also not available until after the attach event is emitted.

items

The array of frames hosted by this toolbar. This property is read-only and is not available until after the attach event is emitted.

hidden

Boolean indicating whether the toolbar is hidden. This property is read-only and is not available until after the attach event is emitted.

Events

attach

This event is emitted when the toolbar is first loaded. Note that since there is only one toolbar for the whole browser, opening another browser window does not cause this event to be emitted again. After this event the toolbar's properties are available:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("attach", attached);
function attached() {
  console.log("attached");
  console.log(toolbar.title);
  console.log(toolbar.items[0]);
  console.log(toolbar.hidden);
}

detach

This event is emitted when the toolbar has been destroyed:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("attach", attached);
toolbar.on("detach", detached);
function attached() {
  console.log("attached");
  require("sdk/timers").setTimeout(destroyToolbar, 1000);
}
function destroyToolbar() {
  toolbar.destroy();
}
function detached() {
  console.log("detached");
}

show

This event is emitted when the user shows the toolbar. The listener is passed the Toolbar instance that was shown:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("show", showing);
function showing(e) {
  console.log("showing");
  console.log(e.title);
  console.log(e.items[0]);
  console.log(e.hidden);
}
Arguments

toolbar : The Toolbar that was shown.

hide

This event is emitted when the user hides the toolbar, either using the "close" button or using the "Toolbars" menu. The listener is passed the Toolbar instance that was hidden:

var { Toolbar } = require("sdk/ui/toolbar");
var { Frame } = require("sdk/ui/frame");
var frame = new Frame({
  url: "./frame.html"
});
var toolbar = Toolbar({
  title: "My toolbar",
  items: [frame]
});
toolbar.on("hide", hiding);
function hiding(e) {
  console.log("hiding");
  console.log(e.title);
  console.log(e.items[0]);
  console.log(e.hidden);
}
Arguments

toolbar : The Toolbar that was hidden.

Document Tags and Contributors

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