ui/toolbar

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:

• action buttons
• toggle buttons
• frames

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:

Optional options:

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.