API-provided widgets

by 1 contributor:

To create a widget, you should pass a specification object with its desired properties. This document details the available properties.

Properties

Property Description
id the ID of the widget (required).
type a string indicating the type of widget. Possible types are
button
for simple button widgets (the default)
view
for buttons that open a panel or subview, depending on where they are placed.
custom
for fine-grained control over the creation of the widget.
viewId Only useful for views (and required there): the id of the <panelview></panelview> that should be shown when clicking the widget.
tooltiptext string to use for the tooltip of the widget
label string to use for the label of the widget
removable whether the widget is removable (optional, default: true).
NB: if you specify false here, you must provide a defaultArea, too.
overflows whether widget can overflow when in an overflowable toolbar (optional, default: true)
defaultArea default area to add the widget to (optional, default: none; required if non-removable)
shortcutId id of an element that has a shortcut for this widget (optional, default: null). This is only used to display the shortcut as part of the tooltip for builtin widgets (which have strings inside customizableWidgets.properties). If you're in an add-on, you should not set this property, and should instead include the shortcut as part of the tooltiptext you pass in yourself.
showInPrivateBrowsing whether to show the widget in private browsing mode (optional, default: true)

Event handlers

You can also define several event handlers which will be called at various stages in a widget's lifetime:

Event handler name Description
onBuild(aDoc) Only useful for custom widgets (and required there); a function that will be invoked with the document in which to build a widget. Should return the DOM node that has been constructed. NB: the DOM node you construct should have the same ID as the id property described above, so that CustomizableUI can find the node again later.
onBeforeCreated(aDoc) Attached to all non-custom widgets; a function that will be invoked before the widget gets a DOM node constructed, passing the document in which that will happen.
This is useful especially for 'view' type widgets that need to construct their views on the fly (e.g. from bootstrapped add-ons).
onCreated(aNode) Attached to all widgets; a function that will be invoked whenever the widget has a DOM node constructed, passing the constructed node as an argument.
onCommand(aEvt) Only useful for button widgets; a function that will be invoked when the user activates the button.
onClick(aEvt) Attached to all widgets; a function that will be invoked when the user clicks the widget.
onViewShowing(aEvt) Only useful for views; a function that will be invoked when a user shows your view.
onViewHiding(aEvt) Only useful for views; a function that will be invoked when a user hides your view.

 

Document Tags and Contributors

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