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 |
hidden | boolean |
Boolean indicating whether the frame should be hidden initially or not. Defaults to |
onAttach | function |
Assign a listener to the |
onDetach | function |
Assign a listener to the |
onShow | function |
Assign a listener to the |
onHide | function |
Assign a listener to the |
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.