CustomizableUI Module
The CustomizableUI module is responsible for managing the default and customized state of various surfaces within the browser. At this time, this includes surfaces like:
The navigation toolbar
The tabs toolbar (in horizontal tabs mode)
The bookmarks toolbar
The overflow panel
The menubar (on Linux and Windows)
- class CustomizableUI()
This is the publicly exposed interface CustomizableUI. It uses old-school encapsulation by forwarding most method calls to CustomizableUIInternal, which is not exported.
- CustomizableUI.AREA_ADDONS
Constant reference to the ID of the addons area.
- CustomizableUI.AREA_BOOKMARKS
Constant reference to the ID of the bookmarks toolbar.
- CustomizableUI.AREA_FIXED_OVERFLOW_PANEL
Constant reference to the ID of the non-dymanic (fixed) list in the overflow panel.
- CustomizableUI.AREA_MENUBAR
Constant reference to the ID of the menubar’s toolbar.
- CustomizableUI.AREA_NAVBAR
Constant reference to the ID of the navigation toolbar.
- CustomizableUI.AREA_NO_AREA
Constant reference to the ID of the customization palette, which is where widgets go when they’re not assigned to an area. Note that this area is “virtual” in that it’s never set as a value for a widgets currentArea or defaultArea. It’s only used for the canWidgetMoveToArea function to check if widgets can be moved to the palette. Callers who wish to move items to the palette should use removeWidgetFromArea.
- CustomizableUI.AREA_TABSTRIP
Constant reference to the ID of the tabstrip toolbar.
- CustomizableUI.AREA_VERTICAL_TABSTRIP
Constant reference to the ID of the vertical tabstrip toolbar.
- CustomizableUI.PROVIDER_API
Constant indicating an API-type provider.
- CustomizableUI.PROVIDER_SPECIAL
Constant indicating dynamic (special) widgets: spring, spacer, and separator.
- CustomizableUI.PROVIDER_XUL
Constant indicating a XUL-type provider.
- CustomizableUI.REASON_AREA_UNREGISTERED
Constant indicating the reason the event was fired was an area being unregistered separately from window closing mechanics.
- CustomizableUI.REASON_WINDOW_CLOSED
Constant indicating the reason the event was fired was a window closing
- CustomizableUI.SOURCE_BUILTIN
Constant indicating the widget is built-in
- CustomizableUI.SOURCE_EXTERNAL
Constant indicating the widget is externally provided (e.g. by add-ons or other items not part of the builtin widget set).
- CustomizableUI.TYPE_PANEL
Constant indicating the area is a panel.
- CustomizableUI.TYPE_TOOLBAR
Constant indicating the area is a toolbar.
- CustomizableUI.areas
Obtain an array of all the area IDs known to CustomizableUI. This array is created for you, so is modifiable without CustomizableUI being affected.
- CustomizableUI.canUndoReset
Can the last Restore Defaults operation be undone.
- CustomizableUI.inDefaultState
Whether we’re in a default state. Note that non-removable non-default widgets and non-existing widgets are not taken into account in determining whether we’re in the default state.
NB: this is a property with a getter. The getter is NOT cheap, because it does smart things with non-removable non-default items, non-existent items, and so forth. Please don’t call unless necessary.
- CustomizableUI.windows
An iteratable property of windows managed by CustomizableUI. Note that this can only be used as an iterator. ie:
for (let window of CustomizableUI.windows) { … }
- static CustomizableUI.addListener(aListener)
Add a listener object that will get fired for various events regarding window, area, and window lifetimes / events, as well as customization events.
- Arguments:
aListener (CustomizableUIListener) – The listener object to add. Not all event handler methods need to be defined. CustomizableUI will catch exceptions. Events are dispatched synchronously on the UI thread, so if you can delay any/some of your processing, that is advisable.
- static CustomizableUI.addPanelCloseListeners(aPanel)
Add listeners to a panel that will close it. For use from the menu panel and overflowable toolbar implementations, unlikely to be useful for consumers.
- Arguments:
aPanel (Element) – The panel to which listeners should be attached.
- static CustomizableUI.addShortcut(aShortcutNode, aTargetNode)
Utility function to detect, find and set a keyboard shortcut for a menuitem or (toolbar)button.
- Arguments:
aShortcutNode (Element) – The XUL node where the shortcut will be derived from;
aTargetNode (Element|null) – The XUL node on which the shortcut attribute will be set. If NULL, the shortcut will be set on aShortcutNode.
- static CustomizableUI.addWidgetToArea(aWidgetId, aArea, aPosition)
Add a widget to an area. If the area to which you try to add is not known to CustomizableUI, this will throw. If the area to which you try to add is the same as the area in which the widget is currently placed, this will do the same as moveWidgetWithinArea. If the widget cannot be removed from its original location, this will no-op.
This will fire an onWidgetAdded notification, and an onWidgetBeforeDOMChange and onWidgetAfterDOMChange notification for each window CustomizableUI knows about.
- Arguments:
aWidgetId (string) – The ID of the widget to add to the area.
aArea (string) – The name of the area to add the widget to.
aPosition (number) – The position at which to add the widget. If you do not pass a position, the widget will be added to the end of the area.
- static CustomizableUI.beginBatchUpdate()
Start a batch update of items. During a batch update, the customization state is not saved to the user’s preferences file, in order to reduce (possibly sync) IO. Calls to begin/endBatchUpdate may be nested.
Callers should ensure that NO MATTER WHAT they call endBatchUpdate once for each call to beginBatchUpdate, even if there are exceptions in the code in the batch update. Otherwise, for the duration of the Firefox session, customization state is never saved. Typically, you would do this using a try…finally block.
- static CustomizableUI.canWidgetMoveToArea(aWidgetId, aArea)
Check if a widget can be moved to a particular area. Like isWidgetRemovable but better, because it’ll return true if the widget is already in the right area.
- Arguments:
aWidgetId (string) – The ID of the widget that you want to move somewhere.
aArea (string) – The area ID you want to move the widget to. This can also be CustomizableUI.AREA_NO_AREA to see if the widget can move to the customization palette, whether it’s removable or not.
- Returns:
boolean – True if this is possible. The same caveats as for isWidgetRemovable apply, however, if no windows are open.
- static CustomizableUI.clearSubview(aSubview)
A helper function for clearing subviews.
- Arguments:
aSubview (Element) – The subview to clear.
- static CustomizableUI.createSpecialWidget(aId, aDocument)
Create an instance of a spring, spacer or separator.
- Arguments:
aId (string) – The type of special widget (spring, spacer or separator).
aDocument (Document) – The document in which to create it.
- static CustomizableUI.createWidget(aProperties)
Create a widget.
To create a widget, you should pass an object with its desired properties.
- Arguments:
aProperties (CustomizableUICreateWidgetProperties) – The properties for the widget to be created.
- Returns:
WidgetGroupWrapper|XULWidgetGroupWrapper –
- static CustomizableUI.destroyWidget(aWidgetId)
Destroy a widget
If the widget is part of the default placements in an area, this will remove it from there. It will also remove any DOM instances. However, it will keep the widget in the placements for whatever area it was in at the time. You can remove it from there yourself by calling CustomizableUI.removeWidgetFromArea(aWidgetId).
- Arguments:
aWidgetId (string) – The ID of the widget to destroy.
- static CustomizableUI.dispatchToolboxEvent(aEvent, aDetails={}, aWindow=null)
Notify toolbox(es) of a particular event. If you don’t pass aWindow, all toolboxes will be notified. For use from Customize Mode only, do not use otherwise.
- Arguments:
aEvent (string) – The name of the event to send.
aDetails (object) – The details of the event.
aWindow (DOMWindow|null) – The window in which to send the event.
- static CustomizableUI.endBatchUpdate(aForceDirty=false)
End a batch update. See the documentation for beginBatchUpdate above.
State is not saved if we believe it is identical to the last known saved state. State is only ever saved when all batch updates have finished (ie there has been 1 endBatchUpdate call for each beginBatchUpdate call). If any of the endBatchUpdate calls pass aForceDirty=true, we will flush to the prefs file.
- Arguments:
aForceDirty (boolean) – Force CustomizableUI to flush to the prefs file when all batch updates have finished. Defaults to false.
- static CustomizableUI.ensureSubviewListeners(aViewNode)
Ensure the customizable widget that matches up with this view node will get the right subview showing/shown/hiding/hidden events when they fire.
- Arguments:
aViewNode (Element) – The view node to add listeners to if they haven’t been added already.
- static CustomizableUI.ensureWidgetPlacedInWindow(aWidgetId, aWindow)
Ensure a XUL-based widget created in a window after areas were initialized moves to its correct position. Always prefer this over moving items in the DOM yourself.
NB: why is this API per-window, you wonder? Because if you need this, presumably you yourself need to create the widget in all the windows and need to loop through them anyway.
- Arguments:
aWidgetId (string) – The ID of the widget that was just created.
aWindow (DOMWindow) – The window in which you want to ensure it was added.
- static CustomizableUI.fillSubviewFromMenuItems(aMenuItems, aSubview)
Fills a submenu with menu items.
- Arguments:
aMenuItems (Array.<Element>) – The array of menu items to display.
aSubview (Element) – The subview to fill with the menu items.
- static CustomizableUI.getAreaType(aArea)
Check what kind of area (toolbar or menu panel) an area is. This is useful if you have a widget that needs to behave differently depending on its location. Note that widget wrappers have a convenience getter property (areaType) for this purpose.
- Arguments:
aArea (string) – The ID of the area whose type you want to know
- Returns:
string – Returns CustomizableUI.TYPE_TOOLBAR or CustomizableUI.TYPE_PANEL depending on the area, null if the area is unknown.
- static CustomizableUI.getCollapsedToolbarIds(window)
Returns a Set with the IDs of any registered toolbar areas that are currently collapsed in a particular window. Menubars that are set to autohide and are in the temporary “open” state are still considered collapsed by default.
- Arguments:
window (Window) – The browser window to check for collapsed toolbars.
- Returns:
Set.<string> –
- static CustomizableUI.getCustomizeTargetForArea(aArea, aWindow)
Obtain the DOM node that is the customize target for an area in a specific window.
Areas can have a customization target that does not correspond to the node itself. In particular, toolbars that have a customizationtarget attribute set will have their customization target set to that node. This means widgets will end up in the customization target, not in the DOM node with the ID that corresponds to the area ID. This is useful because it lets you have fixed content in a toolbar (e.g. the panel menu item in the navbar) and have all the customizable widgets use the customization target.
Using this API yourself is discouraged; you should generally not need to be asking for the DOM container node used for a particular area. In particular, if you’re wanting to check it in relation to a widget’s node, your DOM node might not be a direct child of the customize target in a window if, for instance, the window is in customization mode, or if this is an overflowable toolbar and the widget has been overflowed.
- Arguments:
aArea (string) – The ID of the area whose customize target you want to have
aWindow (DOMWindow) – The window where you want to fetch the DOM node.
- Returns:
Element – The customize target DOM node for aArea in aWindow
- static CustomizableUI.getDefaultPlacementsForArea(aArea)
Get an array of all the widget IDs in the default placements for an area. Modifying the array will not affect CustomizableUI.
- Arguments:
aArea (string) – The ID of the area whose default placements you want to obtain.
- Returns:
Array.<string> – An array containing the widget IDs that are in the default placements for that area.
- static CustomizableUI.getLocalizedProperty(aWidget, aProp, aFormatArgs, aDef)
DEPRECATED! Use fluent instead.
Get a localized property off a (widget?) object.
- NB: this is unlikely to be useful unless you’re in Firefox code, because
this code uses the builtin widget stringbundle, and can’t be told to use add-on-provided strings. It’s mainly here as convenience for custom builtin widgets that build their own DOM but use the same stringbundle as the other builtin widgets.
- Arguments:
aWidget (string|object) – The ID of a widget, or a widget object whose properties we should use to fetch a localizable string.
aProp (string) – The property on the object to use for the fetching from customizableWidgets.properties.
aFormatArgs (Array.<string>) – Any extra arguments to use for a formatted string.
aDef (string) – The default to return if we don’t find the string in the stringbundle.
- Returns:
string – The localized string, or aDef if the string isn’t in the bundle. If no default is provided, if aProp exists on aWidget, we’ll return that, otherwise we’ll return the empty string.
- static CustomizableUI.getPlaceForItem(aElement)
Obtain a string indicating the place of an element. This is intended for use from customize mode; You should generally use getPlacementOfWidget instead, which is cheaper because it does not use the DOM.
- Arguments:
aElement (DOMElement) – The DOM node whose place we need to check.
- Returns:
string|undefined – “toolbar” if the node is in a toolbar, “panel” if it is in the menu panel, “palette” if it is in the (visible!) customization palette, undefined otherwise.
- static CustomizableUI.getPlacementOfWidget(aWidgetId)
Get the placement of a widget. This is by far the best way to obtain information about what the state of your widget is. The internals of this call are cheap (no DOM necessary) and you will know where the user has put your widget.
- Arguments:
aWidgetId (string) – The ID of the widget whose placement you want to know.
- Returns:
CustomizableUIPlacementInfo|null – Returns null if the widget is not placed anywhere (ie in the palette).
- static CustomizableUI.getUnusedWidgets(aWindowPalette)
Get an array of widget wrappers (see getWidget) for all the widgets which are currently not in any area (so which are in the palette).
- Arguments:
aWindowPalette (DOMElement) – The palette element (and by extension, the window) in which CustomizableUI should look. This matters because of course XUL-provided widgets could be available in some windows but not others, and likewise API-provided widgets might not exist in a private window (because of the showInPrivateBrowsing property).
- Returns:
Array.<WidgetGroupWrapper>|Array.<XULWidgetGroupWrapper> – An array of widget wrappers (see getWidget)
- static CustomizableUI.getWidget(aWidgetId)
Get a wrapper object with information about the widget. The object provides the following properties (all read-only unless otherwise indicated):
id: the widget’s ID;
- type: the type of widget (button, view, custom). For
XUL-provided widgets, this is always ‘custom’;
- provider: the provider type of the widget, id est one of
PROVIDER_API or PROVIDER_XUL;
- forWindow(w): a method to obtain a single window wrapper for a widget,
in the window w passed as the only argument;
- instances: an array of all instances (single window wrappers)
of the widget. This array is NOT live;
areaType: the type of the widget’s current area
isGroup: true; will be false for wrappers around single widget nodes;
- source: for API-provided widgets, whether they are built-in to
Firefox or add-on-provided;
- disabled: for API-provided widgets, whether the widget is currently
disabled. NB: this property is writable, and will toggle all the widgets’ nodes’ disabled states;
label: for API-provied widgets, the label of the widget;
tooltiptext: for API-provided widgets, the tooltip of the widget;
- showInPrivateBrowsing: for API-provided widgets, whether the widget is
visible in private browsing;
- hideInNonPrivateBrowsing: for API-provided widgets, whether the widget is
hidden in non-private browsing;
Single window wrappers obtained through forWindow(someWindow) or from the instances array have the following properties (all read-only unless otherwise indicated):
id: the widget’s ID;
- type: the type of widget (button, view, custom). For
XUL-provided widgets, this is always ‘custom’;
- provider: the provider type of the widget, id est one of
PROVIDER_API or PROVIDER_XUL;
node: reference to the corresponding DOM node;
- anchor: the anchor on which to anchor panels opened from this
node. This will point to the overflow chevron on overflowable toolbars if and only if your widget node is overflowed, to the anchor for the panel menu if your widget is inside the panel menu, and to the node itself in all other cases;
- overflowed: boolean indicating whether the node is currently in the
overflow panel of the toolbar;
isGroup: false; will be true for the group widget;
- label: for API-provided widgets, convenience getter for the
label attribute of the DOM node;
- tooltiptext: for API-provided widgets, convenience getter for the
tooltiptext attribute of the DOM node;
- disabled: for API-provided widgets, convenience getter and setter
for the disabled state of this single widget. Note that you may prefer to use the group wrapper’s getter/setter instead.
- Arguments:
aWidgetId (string) – The ID of the widget whose information you need.
- Returns:
WidgetGroupWrapper|XULWidgetGroupWrapper|null – A wrapper around the widget as described above, or null if the widget is known not to exist (anymore). NB: A non-null return is no guarantee the widget exists because we cannot know in advance if a XUL widget exists or not.
- static CustomizableUI.getWidgetIdsInArea(aArea)
Get an array of all the widget IDs placed in an area. Modifying the array will not affect CustomizableUI.
- NB: will throw if called too early (before placements have been fetched)
or if the area is not currently known to CustomizableUI.
- Arguments:
aArea (string) – The name of the area whose placements you want to obtain.
- Returns:
Array.<string> – An array containing the widget IDs that are in the area.
- static CustomizableUI.getWidgetsInArea(aArea)
Get an array of widget wrappers for all the widgets in an area. This is the same as calling getWidgetIdsInArea and .map() ing the result through CustomizableUI.getWidget. Careful: this means that if there are IDs in there which don’t have corresponding DOM nodes, there might be nulls in this array, or items for which wrapper.forWindow(win) will return null.
- Arguments:
aArea (string) – The ID of the area whose widgets you want to obtain.
- Returns:
Array.<(WidgetGroupWrapper|XULWidgetGroupWrapper|null)> – An array of widget wrappers and/or null values for the widget IDs placed in an area. NB: will throw if called too early (before placements have been fetched) or if the area is not currently known to CustomizableUI.
- static CustomizableUI.hidePanelForNode(aNode)
Given a node, walk up to the first panel in its ancestor chain, and close it.
- Arguments:
aNode (Element) – a node whose panel should be closed.
- static CustomizableUI.isAreaOverflowable(aAreaId)
Check whether an area is overflowable.
- Arguments:
aAreaId (string) – The ID of an area to check for overflowable-ness.
- Returns:
boolean – True if the area is overflowable, false otherwise.
- static CustomizableUI.isBuiltinToolbar(aToolbarId)
Check if a toolbar is builtin or not.
- Arguments:
aToolbarId (string) – The ID of the toolbar you want to check.
- static CustomizableUI.isSpecialWidget(aWidgetId)
Check if a widget is a “special” widget: a spring, spacer or separator.
- Arguments:
aWidgetId (string) – the widget ID to check.
- Returns:
boolean – true if the widget is ‘special’, false otherwise.
- static CustomizableUI.isToolbarDefaultCollapsed(aArea)
Check if a toolbar is collapsed by default.
- Arguments:
aArea (string) – The ID of the area whose default-collapsed state you want to know.
- Returns:
boolean – Returns true if the toolbar area is collapsed by default, false if not collapsed by default, and null if the area is unknown its collapsed state cannot normally be controlled by the user.
- static CustomizableUI.isWebExtensionWidget(aWidgetId)
Check if a widget is provided by an extension. This effectively checks whether webExtension: true passed when the widget was being created.
If the widget being referred to hasn’t yet been created, or has been destroyed, we fallback to checking the ID for the “-browser-action” suffix.
- Arguments:
aWidgetId (string) – the widget ID to check.
- Returns:
boolean – True if the widget was provided by an extension, false otherwise.
- static CustomizableUI.isWidgetRemovable(aWidgetId)
Check if a widget can be removed from the area it’s in.
Note that if you’re wanting to move the widget somewhere, you should generally be checking canWidgetMoveToArea, because that will return true if the widget is already in the area where you want to move it (!).
- NB: oh, also, this method might lie if the widget in question is a
XUL-provided widget and there are no windows open, because it can obviously not check anything in this case. It will return true. You will be able to move the widget elsewhere. However, once the user reopens a window, the widget will move back to its ‘proper’ area automagically.
- Arguments:
aWidgetId (string) – A widget ID or DOM node to check.
- Returns:
boolean – True if the widget can be removed from its area.
- static CustomizableUI.moveWidgetWithinArea(aWidgetId, aPosition)
Move a widget within an area. If the widget is not in any area, this will no-op. If the widget is already at the indicated position, this will no-op.
Otherwise, this will move the widget and fire an onWidgetMoved notification, and an onWidgetBeforeDOMChange and onWidgetAfterDOMChange notification for each window CustomizableUI knows about.
- Arguments:
aWidgetId (string) – The ID of the widget to move.
aPosition (number) – The position to move the widget to. Negative values or values greater than the number of widgets will be interpreted to mean moving the widget to respectively the first or last position.
- static CustomizableUI.notifyEndCustomizing(aWindow)
Notify listeners that a window is exiting customize mode. For use from Customize Mode only, do not use otherwise.
- Arguments:
aWindow (DOMWindow) – The window exiting customize mode.
- static CustomizableUI.notifyStartCustomizing(aWindow)
Notify listeners that a window is entering customize mode. For use from Customize Mode only, do not use otherwise.
- Arguments:
aWindow (DOMWindow) – The window entering customize mode.
- static CustomizableUI.onWidgetDrag(aWidgetId, aArea)
Notify listeners a widget is about to be dragged to an area. For use from Customize Mode only, do not use otherwise.
- Arguments:
aWidgetId (string) – The ID of the widget that is being dragged to an area.
aArea (string) – The ID of the area to which the widget is being dragged.
- static CustomizableUI.registerArea(aName, aProperties)
Register a customizable area with CustomizableUI.
- Arguments:
aName (string) – The name of the area to register. Can only contain alphanumeric characters, dashes (-) and underscores (_).
aProperties (object) – The properties of the area to register.
aProperties.type (string) – The type of area being registered. Either CustomizableUI.TYPE_TOOLBAR (default) or CustomizableUI.TYPE_PANEL.
aProperties.anchor (Element|undefined) – For a menu panel or overflowable toolbar area, the anchoring node for the panel.
aProperties.overflowable (boolean) – Set to true if your toolbar is overflowable. This requires an anchor, and only has an effect for toolbars.
aProperties.defaultPlacements (Array.<string>) – An array of widget IDs making up the default contents of the area.
aProperties.defaultCollapsed (boolean|null) – (INTERNAL ONLY) applies if the type is CustomizableUI.TYPE_TOOLBAR, specifies if the toolbar is collapsed by default (defaults to true). Specify null to ensure that reset/inDefaultArea don’t care about a toolbar’s collapsed state
- static CustomizableUI.registerPanelNode(aNode, aArea)
Register a panel node. A panel treated slightly differently from a toolbar in terms of what items can be moved into it. For example, a panel cannot have a spacer or a spring put into it.
- Arguments:
aNode (Element) – The panel contents DOM node being registered.
aArea (string) – The name of the area for which to register this node.
- static CustomizableUI.registerToolbarNode()
Register a concrete node for a registered area. This method needs to be called with any toolbar in the main browser window that has its “customizable” attribute set to true.
Note that ideally, you should register your toolbar using registerArea before calling this. If you don’t, the node will be saved for processing when you call registerArea. Note that CustomizableUI won’t restore state in the area, allow the user to customize it in customize mode, or otherwise deal with it, until the area has been registered.
- static CustomizableUI.removeExtraToolbar(aToolbarId)
Remove a custom toolbar added in a previous version of Firefox or using an add-on. NB: only works on the customizable toolbars generated by the toolbox itself. Intended for use from CustomizeMode, not by other consumers.
- Arguments:
aToolbarId (string) – The ID of the toolbar to remove.
- static CustomizableUI.removeListener(aListener)
Remove a listener that was previously added with addListener.
- Arguments:
aListener (CustomizableUIListener) – The listener object to remove.
- static CustomizableUI.removePanelCloseListeners(aPanel)
Remove close listeners that have been added to a panel with addPanelCloseListeners. For use from the menu panel and overflowable toolbar implementations, unlikely to be useful for consumers.
- Arguments:
aPanel (Element) – The panel from which listeners should be removed.
- static CustomizableUI.removeWidgetFromArea(aWidgetId)
Remove a widget from its area. If the widget cannot be removed from its area, or is not in any area, this will no-op. Otherwise, this will fire an onWidgetRemoved notification, and an onWidgetBeforeDOMChange and onWidgetAfterDOMChange notification for each window CustomizableUI knows about.
- Arguments:
aWidgetId (string) – The ID of the widget to remove from its area.
- static CustomizableUI.reset()
Reset the customization state back to its default.
This is the nuclear option. You should never call this except if the user explicitly requests it. Firefox does this when the user clicks the “Restore Defaults” button in customize mode.
- static CustomizableUI.setToolbarVisibility(aToolbarId, aIsVisible)
Set a toolbar’s visibility state in all windows.
- Arguments:
aToolbarId (string) – The toolbar whose visibility should be adjusted.
aIsVisible (boolean) – Whether the toolbar should be made visible.
- static CustomizableUI.undoReset()
Undo the previous reset, can only be called immediately after a reset.
- Returns:
Promise.<undefined> – A promise that will be resolved when the operation is complete.
- static CustomizableUI.unregisterArea(aName, aDestroyPlacements)
Unregister a customizable area. The inverse of registerArea.
Unregistering an area will remove all the (removable) widgets in the area, which will return to the panel, and destroy all other traces of the area within CustomizableUI. Note that this means the contents of the area’s DOM nodes will be moved to the panel or removed, but the area’s DOM nodes themselves will stay.
Furthermore, by default the placements of the area will be kept in the saved state (!) and restored if you re-register the area at a later point. This is useful for e.g. add-ons that get disabled and then re-enabled (e.g. when they update).
You can override this last behaviour (and destroy the placements information in the saved state) by passing true for aDestroyPlacements.
- Arguments:
aName (string) – The name of the area to unregister.
aDestroyPlacements (boolean) – True if the placements information for the area should be destroyed too. Defaults to not destroying the placements information.
- static CustomizableUI.widgetIsLikelyVisible(aWidgetId, window)
Checks if a widget is likely visible in a given window.
- This method returns true when a widget is:
Not pinned to the overflow menu
Not in a collapsed toolbar (e.g. bookmarks toolbar, menu bar)
Not in the customization palette
- Note: A widget that is moved into the overflow menu due to
the window being small might be considered visible by this method, because a widget’s placement does not change when it overflows into the overflow menu.
- Arguments:
aWidgetId (string) – the widget ID to check.
window (Window) – The browser window to check for widget visibility.
- Returns:
boolean – whether the given widget is likely visible or not.