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.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.