OverflowableToolbar

The OverflowableToolbar class is used for toolbars that, upon shrinking in width, can overflow their contents into an “overflow panel”. In practice, this is really only the browser navigation toolbar - though in times past, it was possible to create multiple overflowable toolbars.

class OverflowableToolbar(aToolbarNode)

OverflowableToolbar is a class that gives a <xul:toolbar> the ability to send toolbar items that are “overflowable” to lists in separate panels if and when the toolbar shrinks enough so that those items overflow out of bounds. Secondly, this class manages moving things out from those panels and back into the toolbar once it underflows and has the space to accommodate the items that had originally overflowed out.

There are two panels that toolbar items can be overflowed to:

1. The default items overflow panel

This is where built-in default toolbar items will go to.

2. The Unified Extensions panel

This is where browser_action toolbar buttons created by extensions will go to if the Unified Extensions UI is enabled - otherwise, those items will go to the default items overflow panel.

Finally, OverflowableToolbar manages the showing of the default items overflow panel when the associated anchor is clicked or dragged over. The Unified Extensions panel is managed separately by the extension code.

In theory, we could have multiple overflowable toolbars, but in practice, only the nav-bar (CustomizableUI.AREA_NAVBAR) makes use of this class.

OverflowableToolbar constructor. This is run very early on in the lifecycle of a browser window, so it tries to defer most work to the init() method instead after first paint.

Upon construction, a “overflowable” attribute will be set on the toolbar, set to the value of “true”.

Part of the API for OverflowableToolbar is declarative, in that it expects certain attributes to be set on the <xul:toolbar> that is overflowable. Those attributes are:

default-overflowbutton:

The ID of the button that is used to open and anchor the overflow panel.

default-overflowtarget:

The ID of the element that overflowed items will be appended to as children. Note that the overflowed toolbar items are moved into and out of this overflow target, so it is definitely advisable to let OverflowableToolbar own managing the children of default-overflowtarget, and to not modify it outside of this class.

default-overflowpanel:

The ID of the <xul:panel> that contains the default-overflowtarget.

addon-webext-overflowbutton:

The ID of the button that is used to open and anchor the Unified Extensions panel.

addon-webext-overflowtarget:

The ID of the element that overflowed extension toolbar buttons will be appended to as children if the Unified Extensions UI is enabled. Note that the overflowed toolbar items are moved into and out of this overflow target, so it is definitely advisable to let OverflowableToolbar own managing the children of addon-webext-overflowtarget, and to not modify it outside of this class.

Arguments:

• aToolbarNode (Element) – The <xul:toolbar> that will be overflowable.

Throws:

Error – Throws if the customization target of the toolbar somehow isn’t a direct descendent of the toolbar.

OverflowableToolbar.checkOverflowHandle

type: object

An empty object that is created in #checkOverflow to identify individual calls to #checkOverflow and avoid re-entrancy (since #checkOverflow is asynchronous, and in theory, could be called multiple times before any of those times have a chance to fully exit).

OverflowableToolbar.defaultList

type: Element

A reference to the element that overflowed toolbar items will be appended to as children upon overflow.

OverflowableToolbar.defaultListButton

type: Element

A reference to the button that opens the overflow panel. This is also the element that the panel will anchor to.

OverflowableToolbar.defaultListPanel

type: Element

A reference to the <xul:panel> overflow panel that contains the #defaultList element.

OverflowableToolbar.enabled

type: boolean

True if the overflowable toolbar is actively handling overflows and underflows. This value is set internally by the private #enable() and #disable() methods.

OverflowableToolbar.hiddenOverflowedNodes

The set of overflowed DOM nodes that were hidden at the time of overflowing.

OverflowableToolbar.hideTimeoutId

type: number

A timeout ID returned by setTimeout that identifies a timeout function that runs to hide the #defaultListPanel if the user happened to open the panel by dragging over the #defaultListButton and then didn’t hover any part of the #defaultListPanel.

OverflowableToolbar.initialized

type: boolean

The OverflowableToolbar class is constructed during browser window creation, but to optimize for window painting, we defer most work until after the window has painted. This property is set to true once initialization has completed.

OverflowableToolbar.overflowedInfo

type: Map.<string, number>

A mapping from the ID of a toolbar item that has overflowed to the width that the toolbar item occupied in the toolbar at the time of overflow. Any item that is currently overflowed will have an entry in this map.

OverflowableToolbar.target

type: Element

A reference to the part of the <xul:toolbar> that accepts CustomizableUI widgets.

OverflowableToolbar.toolbar

type: Element

A reference to the <xul:toolbar> that is overflowable.

OverflowableToolbar.webExtListRef

type: Element|null

A reference to the the element that overflowed extension browser action toolbar items will be appended to as children upon overflow if the Unified Extension UI is enabled. This is created lazily and might be null, so you should use the #webExtList memoizing getter instead to get this.

OverflowableToolbar.findOverflowedInsertionPoints(aNode)

Finds the most appropriate place to insert toolbar item aNode if we’ve been asked to put it into the overflowable toolbar without being told exactly where.

Arguments:

• aNode (Element) – The toolbar item being inserted.

Returns:

Array – [parent, nextNode] parent: {Element} The parent element that should contain aNode. nextNode: {Element|null} The node that should follow aNode after insertion, if any. If this is null, aNode should be placed at the end of parent.

OverflowableToolbar.getContainerFor(aNode)

Allows callers to query for the current parent of a toolbar item that may or may not be overflowed. That parent will either be #defaultList, #webExtList (if it’s an extension button) or #target.

Note: It is assumed that the caller has verified that aNode is placed within the toolbar customizable area according to CustomizableUI.

Arguments:

• aNode (Element) – the node that can be overflowed by this OverflowableToolbar.

Returns:

Element – The current containing node for aNode.

OverflowableToolbar.handleEvent(aEvent)

nsIDOMEventListener implementation starts here.

OverflowableToolbar.init()

Does final initialization of the OverflowableToolbar after the window has first painted. This will also kick off the first check to see if overflow has already occurred at the time of initialization.

OverflowableToolbar.isHandlingOverflow()

Exposes whether #checkOverflow is currently running.

Returns:

boolean – True if #checkOverflow is currently running.

OverflowableToolbar.isInOverflowList(node)

Returns:

boolean – whether the given node is in the overflow list.

OverflowableToolbar.observe(aSubject, aTopic)

nsIObserver implementation starts here.

OverflowableToolbar.onWidgetBeforeDOMChange(aNode, aNextNode, aContainer)

CustomizableUI listener methods start here.

OverflowableToolbar.show(aEvent)

Opens the overflow #defaultListPanel if it’s not already open. If the panel is in the midst of hiding when this is called, the panel will be re-opened.

Returns:

Promise.<undefined> – Resolves once the panel is open.

OverflowableToolbar.uninit()

Almost the exact reverse of init(). This is called when the browser window is unloading.