CustomizeMode

This module is responsible for the mode of the browser window that lets users drag items around in customizable toolbars and panels, as well as the customization palette grid.

class CustomizeMode()

This class manages the lifetime of the CustomizeMode UI in a single browser window. There is one instance of CustomizeMode per browser window.

CustomizeMode.CustomizeMode

CustomizeMode.areas

type: null|Set.<DOMNode>

An array of customize target DOM nodes that this instance of CustomizeMode can be used to manipulate. It is assumed that when targets are in this Set, that they have drag / drop listeners attached and that their customizable children have been wrapped as toolbarpaletteitems.

CustomizeMode.browser

type: Tabbrowser

A reference to the Tabbrowser instance that belongs to the top-level browser window that CustomizeMode is configured to use.

CustomizeMode.customizing

type: boolean

True if we’re in the state of customizing this browser window.

CustomizeMode.document

type: Document

A reference to the top-level browser window document that this instance of CustomizeMode is configured to use.

CustomizeMode.dragOverItem

type: null|DOMNode

If a drag and drop operation is underway for a customizable toolbar item, this member is set to the current item being dragged over.

CustomizeMode.dragSizeMap

type: WeakMap.<DOMNode, WeakMap.<DOMNode, DragSizeForArea>>|null

A WeakMap mapping dragged customizable items to a WeakMap of areas that the item could be dragged into. That mapping maps to ItemSizeForArea objects that describe the width and height of the item were it to be dropped and placed within that area (since certain areas will encourage items to expand or contract).

CustomizeMode.enabledCommands

type: Set.<string>

These are the commands we continue to leave enabled while in customize mode. All other commands are disabled, and we remove the disabled attribute when leaving customize mode.

CustomizeMode.moveDownloadsButtonToNavBar: If this is set to true, this means that the user enabled the downloads button auto-hide feature while the button was in the palette. If so, then on exiting mode, the button is moved to its default position in the navigation toolbar.

CustomizeMode.skipSourceNodeCheck

type: boolean

True if we’re synthesizing drag and drop in customize mode for automated tests and want to skip the checks that ensure that the source of the drag events was this top-level browser window. This is controllable via browser.uiCustomization.skipSourceNodeCheck.

CustomizeMode.stowedPalette

type: null|DOMNode

When in customizing mode, we swap out the reference to the invisible palette in gNavToolbox.palette for our visiblePalette. This way, for the customizing browser window, when widgets are removed from customizable areas and added to the palette, they’re added to the visible palette. #stowedPalette is a reference to the old invisible palette so we can restore gNavToolbox.palette to its original state after exiting customization mode.

CustomizeMode.transitioning

type: boolean

True if CustomizeMode is in the process of being transitioned into or out of.

CustomizeMode.translationObserver

type: MutationObserver|null

A MutationObserver used to hear about Fluent localization occurring for customizable items.

CustomizeMode.window

type: DOMWindow

A reference to the top-level browser window that this instance of CustomizeMode is configured to use.

CustomizeMode.$(id)

This is a shortcut for this.#document.getElementById.

Arguments:

id (string) – The DOM ID to return a result for.

Returns:

DOMNode|null –

CustomizeMode.addToPanel(aNode, aReason)

Pins a customizable widget to the overflow panel. This is used by the toolbar item context menus regardless of whether or not we’re in customize mode. It is also on the widget context menu within the overflow panel when the widget is placed there temporarily during a toolbar overflow. If this item is within a toolbar, this may kick off an* animation that shrinks the item icon and causes it to become transparent before the move occurs. The returned Promise resolves once the animation and the move has completed.

Arguments:

aNode (DOMNode) – The node to be moved to the overflow panel.
aReason (string) – A string to describe why the item is being moved to the overflow panel. This is passed along to BrowserUsageTelemetry.recordWidgetChange, and is dash-delimited. Examples: “toolbar-context-menu”: the reason is that the user chose to do this via the toolbar context menu. “panelitem-context”: the reason is that the user chose to do this via the overflow panel item context menu when the item was moved there temporarily during a toolbar overflow.

Returns:

Promise.<undefined> – Resolves once the move has completed.

CustomizeMode.addToToolbar(aNode)

Moves a customizable item to the end of the navbar. This is used primarily by the toolbar item context menus regardless of whether or not we’re in customize mode. If this item is within a toolbar, this may kick off an animation that shrinks the item icon and causes it to become transparent before the move occurs. The returned Promise resolves once the animation and the move has completed.

Arguments:

aNode (DOMNode) – The node to be moved to the end of the navbar area.

Returns:

Promise.<undefined> – Resolves once the move has completed.

CustomizeMode.createOrUpdateWrapper(aNode, aPlace, aIsUpdate)

Creates or updates a toolbarpaletteitem to wrap a customizable item. This wrapper makes it possible to click and drag these customizable items around in the DOM without the underlying item having its event handlers invoked.

Arguments:

aNode (DOMNode) – The node to create or update the toolbarpaletteitem wrapper for.
aPlace (string) – The string to set as the “place” attribute on the node when it is wrapped. This is expected to be one of the strings returned by CustomizableUI.getPlaceForItem.
aIsUpdate (boolean) – True if it is expected that aNode is already wrapped and that we’re updating the wrapper rather than creating it.

Returns:

DOMNode – Returns the created or updated toolbarpaletteitem wrapper.

CustomizeMode.enter()

Kicks off the process of entering customize mode for the window that this CustomizeMode instance was constructed with. If this window happens to be a popup window, the opener window will enter customize mode.

Entering customize mode is a multistep asynchronous operation, but this method returns immediately while this operation is underway. A customizationready custom event is dispatched on the gNavToolbox when this asynchronous process has completed.

This method will return early if customize mode is already active in this window.

CustomizeMode.exit()

Exits customize mode, if we happen to be in it. This is a no-op if we are not in customize mode.

This is a multi-step asynchronous operation, but this method returns synchronously after the operation begins. An aftercustomization custom event is dispatched on the gNavToolbox once the operation has completed.

CustomizeMode.handleEvent(aEvent)

Generic event handler used throughout most of the Customize Mode UI. This is mainly used to dispatch events to more specific handlers based on the event type.

Arguments:

aEvent (Event) – The event being handled.

CustomizeMode.isWrappedToolbarItem(aNode)

Checks if the passed in DOM node is a toolbarpaletteitem wrapper.

Arguments:

aNode (DOMNode) – The node to check for being wrapped.

Returns:

boolean – true if the passed in DOM node is a toolbarpaletteitem, meaning that it was wrapped via createOrUpdateWrapper.

CustomizeMode.observe(aSubject, aTopic)

Implements nsIObserver. This is mainly to observe for preference changes.

Arguments:

aSubject (nsISupports) – The nsISupports subject for the notification topic that is being observed.
aTopic (string) – The notification topic that is being observed.

CustomizeMode.onAreaNodeRegistered(aArea, aContainer)

Called by CustomizableUI after an area node is first built when it is registered.

Arguments:

aArea (string) – The ID for the area that was just registered.
aContainer (DOMNode) – The DOM node for the customizable area.

CustomizeMode.onAreaNodeUnregistered(aArea, aContainer, aReason)

Called by CustomizableUI after an area node is unregistered and no longer available in this window.

Arguments:

aArea (string) – The ID for the area that was just registered.
aContainer (DOMNode) – The DOM node for the customizable area.
aReason (string) – One of the CustomizableUI.REASON_* constants to describe the reason that the area was unregistered for.

CustomizeMode.onPanelContextMenuShowing(event)

The popupshowing event handler for the context menu for items in the overflow panel while in customize mode. This is currently public due to bug 1378427 (also see bug 1747945).

Arguments:

event (WidgetMouseEvent) – The popupshowing event being fired for the context menu.

CustomizeMode.onWidgetAdded(): The callback called by CustomizableUI when a widget is added to an area.

CustomizeMode.onWidgetAfterCreation(aWidgetId, aArea)

The callback called by CustomizableUI after a widget with id aWidgetId has been created, and has been added to either its default area or the area in which it was placed previously. If the widget has no default area and/or it has never been placed anywhere, aArea may be null. Only fired for API-based widgets.

Arguments:

aWidgetId (string) – The ID of the widget that was just created.
aArea (string|null) – The ID of the area that the widget was placed in, or null if it is now in the customization palette.

CustomizeMode.onWidgetAfterDOMChange(aNodeToChange, aSecondaryNode, aContainer)

The callback called by CustomizableUI after a widget’s DOM node is acted upon by CustomizableUI (to add, move or remove it).

Arguments:

aNodeToChange (Element) – The DOM node that was acted upon.
aSecondaryNode (Element|null) – The DOM node (if any) that the widget was inserted before.
aContainer (Element) – The actual DOM container for the widget (could be an overflow panel in case of an overflowable toolbar).

CustomizeMode.onWidgetBeforeDOMChange(aNodeToChange, aSecondaryNode, aContainer)

The callback called by CustomizableUI before a widget’s DOM node is acted upon by CustomizableUI (to add, move or remove it).

Arguments:

aNodeToChange (Element) – The DOM node being acted upon.
aSecondaryNode (Element|null) – The DOM node (if any) before which a widget will be inserted.
aContainer (Element) – The actual DOM container for the widget (could be an overflow panel in case of an overflowable toolbar).

CustomizeMode.onWidgetDestroyed(aWidgetId)

The callback called by CustomizableUI when a widget is destroyed. Only fired for API-based widgets.

Arguments:

aWidgetId (string) – The ID of the widget that was destroyed.

CustomizeMode.onWidgetMoved(): The callback called by CustomizableUI when a widget moves.

CustomizeMode.onWidgetRemoved(): The callback called by CustomizableUI when a widget is removed from an area.

CustomizeMode.removeFromArea(aNode, aReason)

Removes a customizable item from its area and puts it in the palette. This is used by the toolbar item context menus regardless of whether or not we’re in customize mode. It is also on the widget context menu within the overflow panel when the widget is placed there temporarily during a toolbar overflow. If this item is within a toolbar, this may kick off an animation that shrinks the item icon and causes it to become transparent before the removal occurs. The returned Promise resolves once the animation and the removal has completed.

Arguments:

aNode (DOMNode) – The node to be removed and placed into the palette.
aReason (string) – A string to describe why the item is being removed. This is passed along to BrowserUsageTelemetry.recordWidgetChange, and is dash-delimited. Examples: “toolbar-context-menu”: the reason is that the user chose to do this via the toolbar context menu. “panelitem-context”: the reason is that the user chose to do this via the overflow panel item context menu when the item was moved there temporarily during a toolbar overflow.

Returns:

Promise.<undefined> – Resolves once the removal has completed.

CustomizeMode.reset()

Resets the customization state of the browser across all windows to the default settings.

Returns:: Promise.<undefined> – Resolves once resetting the customization state has completed.

CustomizeMode.setTab(aTab)

Sets the fake tab element that will be associated with being in customize mode. Customize mode looks similar to a “special kind of tab”, and when that tab is closed, we exit customize mode. When that tab is switched to, we enter customize mode. If that tab is restored in the foreground, we enter customize mode.

This method assigns the special <xul:tab> that will represent customize mode for this window, and sets up the relevant listeners to it. The tab will have a “customizemode” attribute set to “true” on it, as well as a special favicon.

Arguments:

aTab (MozTabbrowserTab) – The tab to act as the tab representation of customize mode.

CustomizeMode.setUIDensity(mode)

Sets a UI density mode as the configured density.

Arguments:

mode (number|null) – One of the density mode constants from gUIDensity - for example, gUIDensity.MODE_TOUCH.

CustomizeMode.undoReset()

Reverts a reset operation back to the prior customization state.

Returns:: Promise.<undefined> –