The Tor Browser: comparison browser/devtools/shared/widgets/ViewHelpers.jsm

--1:000000000000
+:c6ff08cec81a
+/* -*- Mode: javascript; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
+/* vim: set ft=javascript ts=2 et sw=2 tw=80: */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+* License, v. 2.0. If a copy of the MPL was not distributed with this
+* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+"use strict";
+const Cc = Components.classes;
+const Ci = Components.interfaces;
+const Cu = Components.utils;
+const PANE_APPEARANCE_DELAY = 50;
+const PAGE_SIZE_ITEM_COUNT_RATIO = 5;
+const WIDGET_FOCUSABLE_NODES = new Set(["vbox", "hbox"]);
+Cu.import("resource://gre/modules/Services.jsm");
+Cu.import("resource://gre/modules/XPCOMUtils.jsm");
+Cu.import("resource://gre/modules/Timer.jsm");
+Cu.import("resource://gre/modules/devtools/DevToolsUtils.jsm");
+this.EXPORTED_SYMBOLS = [
+"Heritage", "ViewHelpers", "WidgetMethods",
+"setNamedTimeout", "clearNamedTimeout",
+"setConditionalTimeout", "clearConditionalTimeout",
+];
+/**
+* Inheritance helpers from the addon SDK's core/heritage.
+* Remove these when all devtools are loadered.
+*/
+this.Heritage = {
+/**
+* @see extend in sdk/core/heritage.
+*/
+extend: function(aPrototype, aProperties = {}) {
+return Object.create(aPrototype, this.getOwnPropertyDescriptors(aProperties));
+},
+/**
+* @see getOwnPropertyDescriptors in sdk/core/heritage.
+*/
+getOwnPropertyDescriptors: function(aObject) {
+return Object.getOwnPropertyNames(aObject).reduce((aDescriptor, aName) => {
+aDescriptor[aName] = Object.getOwnPropertyDescriptor(aObject, aName);
+return aDescriptor;
+}, {});
+}
+};
+/**
+* Helper for draining a rapid succession of events and invoking a callback
+* once everything settles down.
+*
+* @param string aId
+*        A string identifier for the named timeout.
+* @param number aWait
+*        The amount of milliseconds to wait after no more events are fired.
+* @param function aCallback
+*        Invoked when no more events are fired after the specified time.
+*/
+this.setNamedTimeout = function setNamedTimeout(aId, aWait, aCallback) {
+clearNamedTimeout(aId);
+namedTimeoutsStore.set(aId, setTimeout(() =>
+namedTimeoutsStore.delete(aId) && aCallback(), aWait));
+};
+/**
+* Clears a named timeout.
+* @see setNamedTimeout
+*
+* @param string aId
+*        A string identifier for the named timeout.
+*/
+this.clearNamedTimeout = function clearNamedTimeout(aId) {
+if (!namedTimeoutsStore) {
+return;
+}
+clearTimeout(namedTimeoutsStore.get(aId));
+namedTimeoutsStore.delete(aId);
+};
+/**
+* Same as `setNamedTimeout`, but invokes the callback only if the provided
+* predicate function returns true. Otherwise, the timeout is re-triggered.
+*
+* @param string aId
+*        A string identifier for the conditional timeout.
+* @param number aWait
+*        The amount of milliseconds to wait after no more events are fired.
+* @param function aPredicate
+*        The predicate function used to determine whether the timeout restarts.
+* @param function aCallback
+*        Invoked when no more events are fired after the specified time, and
+*        the provided predicate function returns true.
+*/
+this.setConditionalTimeout = function setConditionalTimeout(aId, aWait, aPredicate, aCallback) {
+setNamedTimeout(aId, aWait, function maybeCallback() {
+if (aPredicate()) {
+aCallback();
+return;
+}
+setConditionalTimeout(aId, aWait, aPredicate, aCallback);
+});
+};
+/**
+* Clears a conditional timeout.
+* @see setConditionalTimeout
+*
+* @param string aId
+*        A string identifier for the conditional timeout.
+*/
+this.clearConditionalTimeout = function clearConditionalTimeout(aId) {
+clearNamedTimeout(aId);
+};
+XPCOMUtils.defineLazyGetter(this, "namedTimeoutsStore", () => new Map());
+/**
+* Helpers for creating and messaging between UI components.
+*/
+this.ViewHelpers = {
+/**
+* Convenience method, dispatching a custom event.
+*
+* @param nsIDOMNode aTarget
+*        A custom target element to dispatch the event from.
+* @param string aType
+*        The name of the event.
+* @param any aDetail
+*        The data passed when initializing the event.
+* @return boolean
+*         True if the event was cancelled or a registered handler
+*         called preventDefault.
+*/
+dispatchEvent: function(aTarget, aType, aDetail) {
+if (!(aTarget instanceof Ci.nsIDOMNode)) {
+return true; // Event cancelled.
+}
+let document = aTarget.ownerDocument || aTarget;
+let dispatcher = aTarget.ownerDocument ? aTarget : document.documentElement;
+let event = document.createEvent("CustomEvent");
+event.initCustomEvent(aType, true, true, aDetail);
+return dispatcher.dispatchEvent(event);
+},
+/**
+* Helper delegating some of the DOM attribute methods of a node to a widget.
+*
+* @param object aWidget
+*        The widget to assign the methods to.
+* @param nsIDOMNode aNode
+*        A node to delegate the methods to.
+*/
+delegateWidgetAttributeMethods: function(aWidget, aNode) {
+aWidget.getAttribute =
+aWidget.getAttribute || aNode.getAttribute.bind(aNode);
+aWidget.setAttribute =
+aWidget.setAttribute || aNode.setAttribute.bind(aNode);
+aWidget.removeAttribute =
+aWidget.removeAttribute || aNode.removeAttribute.bind(aNode);
+},
+/**
+* Helper delegating some of the DOM event methods of a node to a widget.
+*
+* @param object aWidget
+*        The widget to assign the methods to.
+* @param nsIDOMNode aNode
+*        A node to delegate the methods to.
+*/
+delegateWidgetEventMethods: function(aWidget, aNode) {
+aWidget.addEventListener =
+aWidget.addEventListener || aNode.addEventListener.bind(aNode);
+aWidget.removeEventListener =
+aWidget.removeEventListener || aNode.removeEventListener.bind(aNode);
+},
+/**
+* Checks if the specified object looks like it's been decorated by an
+* event emitter.
+*
+* @return boolean
+*         True if it looks, walks and quacks like an event emitter.
+*/
+isEventEmitter: function(aObject) {
+return aObject && aObject.on && aObject.off && aObject.once && aObject.emit;
+},
+/**
+* Checks if the specified object is an instance of a DOM node.
+*
+* @return boolean
+*         True if it's a node, false otherwise.
+*/
+isNode: function(aObject) {
+return aObject instanceof Ci.nsIDOMNode ||
+aObject instanceof Ci.nsIDOMElement ||
+aObject instanceof Ci.nsIDOMDocumentFragment;
+},
+/**
+* Prevents event propagation when navigation keys are pressed.
+*
+* @param Event e
+*        The event to be prevented.
+*/
+preventScrolling: function(e) {
+switch (e.keyCode) {
+case e.DOM_VK_UP:
+case e.DOM_VK_DOWN:
+case e.DOM_VK_LEFT:
+case e.DOM_VK_RIGHT:
+case e.DOM_VK_PAGE_UP:
+case e.DOM_VK_PAGE_DOWN:
+case e.DOM_VK_HOME:
+case e.DOM_VK_END:
+e.preventDefault();
+e.stopPropagation();
+}
+},
+/**
+* Sets a side pane hidden or visible.
+*
+* @param object aFlags
+*        An object containing some of the following properties:
+*        - visible: true if the pane should be shown, false to hide
+*        - animated: true to display an animation on toggle
+*        - delayed: true to wait a few cycles before toggle
+*        - callback: a function to invoke when the toggle finishes
+* @param nsIDOMNode aPane
+*        The element representing the pane to toggle.
+*/
+togglePane: function(aFlags, aPane) {
+// Make sure a pane is actually available first.
+if (!aPane) {
+return;
+}
+// Hiding is always handled via margins, not the hidden attribute.
+aPane.removeAttribute("hidden");
+// Add a class to the pane to handle min-widths, margins and animations.
+if (!aPane.classList.contains("generic-toggled-side-pane")) {
+aPane.classList.add("generic-toggled-side-pane");
+}
+// Avoid useless toggles.
+if (aFlags.visible == !aPane.hasAttribute("pane-collapsed")) {
+if (aFlags.callback) aFlags.callback();
+return;
+}
+// The "animated" attributes enables animated toggles (slide in-out).
+if (aFlags.animated) {
+aPane.setAttribute("animated", "");
+} else {
+aPane.removeAttribute("animated");
+}
+// Computes and sets the pane margins in order to hide or show it.
+let doToggle = () => {
+if (aFlags.visible) {
+aPane.style.marginLeft = "0";
+aPane.style.marginRight = "0";
+aPane.removeAttribute("pane-collapsed");
+} else {
+let margin = ~~(aPane.getAttribute("width")) + 1;
+aPane.style.marginLeft = -margin + "px";
+aPane.style.marginRight = -margin + "px";
+aPane.setAttribute("pane-collapsed", "");
+}
+// Invoke the callback when the transition ended.
+if (aFlags.animated) {
+aPane.addEventListener("transitionend", function onEvent() {
+aPane.removeEventListener("transitionend", onEvent, false);
+if (aFlags.callback) aFlags.callback();
+}, false);
+}
+// Invoke the callback immediately since there's no transition.
+else {
+if (aFlags.callback) aFlags.callback();
+}
+}
+// Sometimes it's useful delaying the toggle a few ticks to ensure
+// a smoother slide in-out animation.
+if (aFlags.delayed) {
+aPane.ownerDocument.defaultView.setTimeout(doToggle, PANE_APPEARANCE_DELAY);
+} else {
+doToggle();
+}
+}
+};
+/**
+* Localization convenience methods.
+*
+* @param string aStringBundleName
+*        The desired string bundle's name.
+*/
+ViewHelpers.L10N = function(aStringBundleName) {
+XPCOMUtils.defineLazyGetter(this, "stringBundle", () =>
+Services.strings.createBundle(aStringBundleName));
+XPCOMUtils.defineLazyGetter(this, "ellipsis", () =>
+Services.prefs.getComplexValue("intl.ellipsis", Ci.nsIPrefLocalizedString).data);
+};
+ViewHelpers.L10N.prototype = {
+stringBundle: null,
+/**
+* L10N shortcut function.
+*
+* @param string aName
+* @return string
+*/
+getStr: function(aName) {
+return this.stringBundle.GetStringFromName(aName);
+},
+/**
+* L10N shortcut function.
+*
+* @param string aName
+* @param array aArgs
+* @return string
+*/
+getFormatStr: function(aName, ...aArgs) {
+return this.stringBundle.formatStringFromName(aName, aArgs, aArgs.length);
+},
+/**
+* L10N shortcut function for numeric arguments that need to be formatted.
+* All numeric arguments will be fixed to 2 decimals and given a localized
+* decimal separator. Other arguments will be left alone.
+*
+* @param string aName
+* @param array aArgs
+* @return string
+*/
+getFormatStrWithNumbers: function(aName, ...aArgs) {
+let newArgs = aArgs.map(x => typeof x == "number" ? this.numberWithDecimals(x, 2) : x);
+return this.stringBundle.formatStringFromName(aName, newArgs, newArgs.length);
+},
+/**
+* Converts a number to a locale-aware string format and keeps a certain
+* number of decimals.
+*
+* @param number aNumber
+*        The number to convert.
+* @param number aDecimals [optional]
+*        Total decimals to keep.
+* @return string
+*         The localized number as a string.
+*/
+numberWithDecimals: function(aNumber, aDecimals = 0) {
+// If this is an integer, don't do anything special.
+if (aNumber == (aNumber | 0)) {
+return aNumber;
+}
+// Remove {n} trailing decimals. Can't use toFixed(n) because
+// toLocaleString converts the number to a string. Also can't use
+// toLocaleString(, { maximumFractionDigits: n }) because it's not
+// implemented on OS X (bug 368838). Gross.
+let localized = aNumber.toLocaleString(); // localize
+let padded = localized + new Array(aDecimals).join("0"); // pad with zeros
+let match = padded.match("([^]*?\\d{" + aDecimals + "})\\d*$");
+return match.pop();
+}
+};
+/**
+* Shortcuts for lazily accessing and setting various preferences.
+* Usage:
+*   let prefs = new ViewHelpers.Prefs("root.path.to.branch", {
+*     myIntPref: ["Int", "leaf.path.to.my-int-pref"],
+*     myCharPref: ["Char", "leaf.path.to.my-char-pref"],
+*     ...
+*   });
+*
+*   prefs.myCharPref = "foo";
+*   let aux = prefs.myCharPref;
+*
+* @param string aPrefsRoot
+*        The root path to the required preferences branch.
+* @param object aPrefsObject
+*        An object containing { accessorName: [prefType, prefName] } keys.
+*/
+ViewHelpers.Prefs = function(aPrefsRoot = "", aPrefsObject = {}) {
+this.root = aPrefsRoot;
+for (let accessorName in aPrefsObject) {
+let [prefType, prefName] = aPrefsObject[accessorName];
+this.map(accessorName, prefType, prefName);
+}
+};
+ViewHelpers.Prefs.prototype = {
+/**
+* Helper method for getting a pref value.
+*
+* @param string aType
+* @param string aPrefName
+* @return any
+*/
+_get: function(aType, aPrefName) {
+if (this[aPrefName] === undefined) {
+this[aPrefName] = Services.prefs["get" + aType + "Pref"](aPrefName);
+}
+return this[aPrefName];
+},
+/**
+* Helper method for setting a pref value.
+*
+* @param string aType
+* @param string aPrefName
+* @param any aValue
+*/
+_set: function(aType, aPrefName, aValue) {
+Services.prefs["set" + aType + "Pref"](aPrefName, aValue);
+this[aPrefName] = aValue;
+},
+/**
+* Maps a property name to a pref, defining lazy getters and setters.
+* Supported types are "Bool", "Char", "Int" and "Json" (which is basically
+* just sugar for "Char" using the standard JSON serializer).
+*
+* @param string aAccessorName
+* @param string aType
+* @param string aPrefName
+* @param array aSerializer
+*/
+map: function(aAccessorName, aType, aPrefName, aSerializer = { in: e => e, out: e => e }) {
+if (aType == "Json") {
+this.map(aAccessorName, "Char", aPrefName, { in: JSON.parse, out: JSON.stringify });
+return;
+}
+Object.defineProperty(this, aAccessorName, {
+get: () => aSerializer.in(this._get(aType, [this.root, aPrefName].join("."))),
+set: (e) => this._set(aType, [this.root, aPrefName].join("."), aSerializer.out(e))
+});
+}
+};
+/**
+* A generic Item is used to describe children present in a Widget.
+*
+* This is basically a very thin wrapper around an nsIDOMNode, with a few
+* characteristics, like a `value` and an `attachment`.
+*
+* The characteristics are optional, and their meaning is entirely up to you.
+* - The `value` should be a string, passed as an argument.
+* - The `attachment` is any kind of primitive or object, passed as an argument.
+*
+* Iterable via "for (let childItem of parentItem) { }".
+*
+* @param object aOwnerView
+*        The owner view creating this item.
+* @param nsIDOMNode aElement
+*        A prebuilt node to be wrapped.
+* @param string aValue
+*        A string identifying the node.
+* @param any aAttachment
+*        Some attached primitive/object.
+*/
+function Item(aOwnerView, aElement, aValue, aAttachment) {
+this.ownerView = aOwnerView;
+this.attachment = aAttachment;
+this._value = aValue + "";
+this._prebuiltNode = aElement;
+};
+Item.prototype = {
+get value() { return this._value; },
+get target() { return this._target; },
+/**
+* Immediately appends a child item to this item.
+*
+* @param nsIDOMNode aElement
+*        An nsIDOMNode representing the child element to append.
+* @param object aOptions [optional]
+*        Additional options or flags supported by this operation:
+*          - attachment: some attached primitive/object for the item
+*          - attributes: a batch of attributes set to the displayed element
+*          - finalize: function invoked when the child item is removed
+* @return Item
+*         The item associated with the displayed element.
+*/
+append: function(aElement, aOptions = {}) {
+let item = new Item(this, aElement, "", aOptions.attachment);
+// Entangle the item with the newly inserted child node.
+// Make sure this is done with the value returned by appendChild(),
+// to avoid storing a potential DocumentFragment.
+this._entangleItem(item, this._target.appendChild(aElement));
+// Handle any additional options after entangling the item.
+if (aOptions.attributes) {
+aOptions.attributes.forEach(e => item._target.setAttribute(e[0], e[1]));
+}
+if (aOptions.finalize) {
+item.finalize = aOptions.finalize;
+}
+// Return the item associated with the displayed element.
+return item;
+},
+/**
+* Immediately removes the specified child item from this item.
+*
+* @param Item aItem
+*        The item associated with the element to remove.
+*/
+remove: function(aItem) {
+if (!aItem) {
+return;
+}
+this._target.removeChild(aItem._target);
+this._untangleItem(aItem);
+},
+/**
+* Entangles an item (model) with a displayed node element (view).
+*
+* @param Item aItem
+*        The item describing a target element.
+* @param nsIDOMNode aElement
+*        The element displaying the item.
+*/
+_entangleItem: function(aItem, aElement) {
+this._itemsByElement.set(aElement, aItem);
+aItem._target = aElement;
+},
+/**
+* Untangles an item (model) from a displayed node element (view).
+*
+* @param Item aItem
+*        The item describing a target element.
+*/
+_untangleItem: function(aItem) {
+if (aItem.finalize) {
+aItem.finalize(aItem);
+}
+for (let childItem of aItem) {
+aItem.remove(childItem);
+}
+this._unlinkItem(aItem);
+aItem._target = null;
+},
+/**
+* Deletes an item from the its parent's storage maps.
+*
+* @param Item aItem
+*        The item describing a target element.
+*/
+_unlinkItem: function(aItem) {
+this._itemsByElement.delete(aItem._target);
+},
+/**
+* Returns a string representing the object.
+* @return string
+*/
+toString: function() {
+return this._value + " :: " + this._target + " :: " + this.attachment;
+},
+_value: "",
+_target: null,
+_prebuiltNode: null,
+finalize: null,
+attachment: null
+};
+// Creating maps thousands of times for widgets with a large number of children
+// fills up a lot of memory. Make sure these are instantiated only if needed.
+DevToolsUtils.defineLazyPrototypeGetter(Item.prototype, "_itemsByElement", Map);
+/**
+* Some generic Widget methods handling Item instances.
+* Iterable via "for (let childItem of wrappedView) { }".
+*
+* Usage:
+*   function MyView() {
+*     this.widget = new MyWidget(document.querySelector(".my-node"));
+*   }
+*
+*   MyView.prototype = Heritage.extend(WidgetMethods, {
+*     myMethod: function() {},
+*     ...
+*   });
+*
+* See https://gist.github.com/victorporof/5749386 for more details.
+* The devtools/shared/widgets/SimpleListWidget.jsm is an implementation example.
+*
+* Language:
+*   - An "item" is an instance of an Item.
+*   - An "element" or "node" is a nsIDOMNode.
+*
+* The supplied widget can be any object implementing the following methods:
+*   - function:nsIDOMNode insertItemAt(aIndex:number, aNode:nsIDOMNode, aValue:string)
+*   - function:nsIDOMNode getItemAtIndex(aIndex:number)
+*   - function removeChild(aChild:nsIDOMNode)
+*   - function removeAllItems()
+*   - get:nsIDOMNode selectedItem()
+*   - set selectedItem(aChild:nsIDOMNode)
+*   - function getAttribute(aName:string)
+*   - function setAttribute(aName:string, aValue:string)
+*   - function removeAttribute(aName:string)
+*   - function addEventListener(aName:string, aCallback:function, aBubbleFlag:boolean)
+*   - function removeEventListener(aName:string, aCallback:function, aBubbleFlag:boolean)
+*
+* Optional methods that can be implemented by the widget:
+*   - function ensureElementIsVisible(aChild:nsIDOMNode)
+*
+* Optional attributes that may be handled (when calling get/set/removeAttribute):
+*   - "emptyText": label temporarily added when there are no items present
+*   - "headerText": label permanently added as a header
+*
+* For automagical keyboard and mouse accessibility, the widget should be an
+* event emitter with the following events:
+*   - "keyPress" -> (aName:string, aEvent:KeyboardEvent)
+*   - "mousePress" -> (aName:string, aEvent:MouseEvent)
+*/
+this.WidgetMethods = {
+/**
+* Sets the element node or widget associated with this container.
+* @param nsIDOMNode | object aWidget
+*/
+set widget(aWidget) {
+this._widget = aWidget;
+// Can't use a WeakMap for _itemsByValue because keys are strings, and
+// can't use one for _itemsByElement either, since it needs to be iterable.
+XPCOMUtils.defineLazyGetter(this, "_itemsByValue", () => new Map());
+XPCOMUtils.defineLazyGetter(this, "_itemsByElement", () => new Map());
+XPCOMUtils.defineLazyGetter(this, "_stagedItems", () => []);
+// Handle internal events emitted by the widget if necessary.
+if (ViewHelpers.isEventEmitter(aWidget)) {
+aWidget.on("keyPress", this._onWidgetKeyPress.bind(this));
+aWidget.on("mousePress", this._onWidgetMousePress.bind(this));
+}
+},
+/**
+* Gets the element node or widget associated with this container.
+* @return nsIDOMNode | object
+*/
+get widget() this._widget,
+/**
+* Prepares an item to be added to this container. This allows, for example,
+* for a large number of items to be batched up before being sorted & added.
+*
+* If the "staged" flag is *not* set to true, the item will be immediately
+* inserted at the correct position in this container, so that all the items
+* still remain sorted. This can (possibly) be much slower than batching up
+* multiple items.
+*
+* By default, this container assumes that all the items should be displayed
+* sorted by their value. This can be overridden with the "index" flag,
+* specifying on which position should an item be appended. The "staged" and
+* "index" flags are mutually exclusive, meaning that all staged items
+* will always be appended.
+*
+* @param nsIDOMNode aElement
+*        A prebuilt node to be wrapped.
+* @param string aValue
+*        A string identifying the node.
+* @param object aOptions [optional]
+*        Additional options or flags supported by this operation:
+*          - attachment: some attached primitive/object for the item
+*          - staged: true to stage the item to be appended later
+*          - index: specifies on which position should the item be appended
+*          - attributes: a batch of attributes set to the displayed element
+*          - finalize: function invoked when the item is removed
+* @return Item
+*         The item associated with the displayed element if an unstaged push,
+*         undefined if the item was staged for a later commit.
+*/
+push: function([aElement, aValue], aOptions = {}) {
+let item = new Item(this, aElement, aValue, aOptions.attachment);
+// Batch the item to be added later.
+if (aOptions.staged) {
+// An ulterior commit operation will ignore any specified index, so
+// no reason to keep it around.
+aOptions.index = undefined;
+return void this._stagedItems.push({ item: item, options: aOptions });
+}
+// Find the target position in this container and insert the item there.
+if (!("index" in aOptions)) {
+return this._insertItemAt(this._findExpectedIndexFor(item), item, aOptions);
+}
+// Insert the item at the specified index. If negative or out of bounds,
+// the item will be simply appended.
+return this._insertItemAt(aOptions.index, item, aOptions);
+},
+/**
+* Flushes all the prepared items into this container.
+* Any specified index on the items will be ignored. Everything is appended.
+*
+* @param object aOptions [optional]
+*        Additional options or flags supported by this operation:
+*          - sorted: true to sort all the items before adding them
+*/
+commit: function(aOptions = {}) {
+let stagedItems = this._stagedItems;
+// Sort the items before adding them to this container, if preferred.
+if (aOptions.sorted) {
+stagedItems.sort((a, b) => this._currentSortPredicate(a.item, b.item));
+}
+// Append the prepared items to this container.
+for (let { item, options } of stagedItems) {
+this._insertItemAt(-1, item, options);
+}
+// Recreate the temporary items list for ulterior pushes.
+this._stagedItems.length = 0;
+},
+/**
+* Immediately removes the specified item from this container.
+*
+* @param Item aItem
+*        The item associated with the element to remove.
+*/
+remove: function(aItem) {
+if (!aItem) {
+return;
+}
+this._widget.removeChild(aItem._target);
+this._untangleItem(aItem);
+if (!this._itemsByElement.size) {
+this._preferredValue = this.selectedValue;
+this._widget.selectedItem = null;
+this._widget.setAttribute("emptyText", this._emptyText);
+}
+},
+/**
+* Removes the item at the specified index from this container.
+*
+* @param number aIndex
+*        The index of the item to remove.
+*/
+removeAt: function(aIndex) {
+this.remove(this.getItemAtIndex(aIndex));
+},
+/**
+* Removes all items from this container.
+*/
+empty: function() {
+this._preferredValue = this.selectedValue;
+this._widget.selectedItem = null;
+this._widget.removeAllItems();
+this._widget.setAttribute("emptyText", this._emptyText);
+for (let [, item] of this._itemsByElement) {
+this._untangleItem(item);
+}
+this._itemsByValue.clear();
+this._itemsByElement.clear();
+this._stagedItems.length = 0;
+},
+/**
+* Ensures the specified item is visible in this container.
+*
+* @param Item aItem
+*        The item to bring into view.
+*/
+ensureItemIsVisible: function(aItem) {
+this._widget.ensureElementIsVisible(aItem._target);
+},
+/**
+* Ensures the item at the specified index is visible in this container.
+*
+* @param number aIndex
+*        The index of the item to bring into view.
+*/
+ensureIndexIsVisible: function(aIndex) {
+this.ensureItemIsVisible(this.getItemAtIndex(aIndex));
+},
+/**
+* Sugar for ensuring the selected item is visible in this container.
+*/
+ensureSelectedItemIsVisible: function() {
+this.ensureItemIsVisible(this.selectedItem);
+},
+/**
+* If supported by the widget, the label string temporarily added to this
+* container when there are no child items present.
+*/
+set emptyText(aValue) {
+this._emptyText = aValue;
+// Apply the emptyText attribute right now if there are no child items.
+if (!this._itemsByElement.size) {
+this._widget.setAttribute("emptyText", aValue);
+}
+},
+/**
+* If supported by the widget, the label string permanently added to this
+* container as a header.
+* @param string aValue
+*/
+set headerText(aValue) {
+this._headerText = aValue;
+this._widget.setAttribute("headerText", aValue);
+},
+/**
+* Toggles all the items in this container hidden or visible.
+*
+* This does not change the default filtering predicate, so newly inserted
+* items will always be visible. Use WidgetMethods.filterContents if you care.
+*
+* @param boolean aVisibleFlag
+*        Specifies the intended visibility.
+*/
+toggleContents: function(aVisibleFlag) {
+for (let [element, item] of this._itemsByElement) {
+element.hidden = !aVisibleFlag;
+}
+},
+/**
+* Toggles all items in this container hidden or visible based on a predicate.
+*
+* @param function aPredicate [optional]
+*        Items are toggled according to the return value of this function,
+*        which will become the new default filtering predicate in this container.
+*        If unspecified, all items will be toggled visible.
+*/
+filterContents: function(aPredicate = this._currentFilterPredicate) {
+this._currentFilterPredicate = aPredicate;
+for (let [element, item] of this._itemsByElement) {
+element.hidden = !aPredicate(item);
+}
+},
+/**
+* Sorts all the items in this container based on a predicate.
+*
+* @param function aPredicate [optional]
+*        Items are sorted according to the return value of the function,
+*        which will become the new default sorting predicate in this container.
+*        If unspecified, all items will be sorted by their value.
+*/
+sortContents: function(aPredicate = this._currentSortPredicate) {
+let sortedItems = this.items.sort(this._currentSortPredicate = aPredicate);
+for (let i = 0, len = sortedItems.length; i < len; i++) {
+this.swapItems(this.getItemAtIndex(i), sortedItems[i]);
+}
+},
+/**
+* Visually swaps two items in this container.
+*
+* @param Item aFirst
+*        The first item to be swapped.
+* @param Item aSecond
+*        The second item to be swapped.
+*/
+swapItems: function(aFirst, aSecond) {
+if (aFirst == aSecond) { // We're just dandy, thank you.
+return;
+}
+let { _prebuiltNode: firstPrebuiltTarget, _target: firstTarget } = aFirst;
+let { _prebuiltNode: secondPrebuiltTarget, _target: secondTarget } = aSecond;
+// If the two items were constructed with prebuilt nodes as DocumentFragments,
+// then those DocumentFragments are now empty and need to be reassembled.
+if (firstPrebuiltTarget instanceof Ci.nsIDOMDocumentFragment) {
+for (let node of firstTarget.childNodes) {
+firstPrebuiltTarget.appendChild(node.cloneNode(true));
+}
+}
+if (secondPrebuiltTarget instanceof Ci.nsIDOMDocumentFragment) {
+for (let node of secondTarget.childNodes) {
+secondPrebuiltTarget.appendChild(node.cloneNode(true));
+}
+}
+// 1. Get the indices of the two items to swap.
+let i = this._indexOfElement(firstTarget);
+let j = this._indexOfElement(secondTarget);
+// 2. Remeber the selection index, to reselect an item, if necessary.
+let selectedTarget = this._widget.selectedItem;
+let selectedIndex = -1;
+if (selectedTarget == firstTarget) {
+selectedIndex = i;
+} else if (selectedTarget == secondTarget) {
+selectedIndex = j;
+}
+// 3. Silently nuke both items, nobody needs to know about this.
+this._widget.removeChild(firstTarget);
+this._widget.removeChild(secondTarget);
+this._unlinkItem(aFirst);
+this._unlinkItem(aSecond);
+// 4. Add the items again, but reversing their indices.
+this._insertItemAt.apply(this, i < j ? [i, aSecond] : [j, aFirst]);
+this._insertItemAt.apply(this, i < j ? [j, aFirst] : [i, aSecond]);
+// 5. Restore the previous selection, if necessary.
+if (selectedIndex == i) {
+this._widget.selectedItem = aFirst._target;
+} else if (selectedIndex == j) {
+this._widget.selectedItem = aSecond._target;
+}
+// 6. Let the outside world know that these two items were swapped.
+ViewHelpers.dispatchEvent(aFirst.target, "swap", [aSecond, aFirst]);
+},
+/**
+* Visually swaps two items in this container at specific indices.
+*
+* @param number aFirst
+*        The index of the first item to be swapped.
+* @param number aSecond
+*        The index of the second item to be swapped.
+*/
+swapItemsAtIndices: function(aFirst, aSecond) {
+this.swapItems(this.getItemAtIndex(aFirst), this.getItemAtIndex(aSecond));
+},
+/**
+* Checks whether an item with the specified value is among the elements
+* shown in this container.
+*
+* @param string aValue
+*        The item's value.
+* @return boolean
+*         True if the value is known, false otherwise.
+*/
+containsValue: function(aValue) {
+return this._itemsByValue.has(aValue) ||
+this._stagedItems.some(({ item }) => item._value == aValue);
+},
+/**
+* Gets the "preferred value". This is the latest selected item's value,
+* remembered just before emptying this container.
+* @return string
+*/
+get preferredValue() {
+return this._preferredValue;
+},
+/**
+* Retrieves the item associated with the selected element.
+* @return Item | null
+*/
+get selectedItem() {
+let selectedElement = this._widget.selectedItem;
+if (selectedElement) {
+return this._itemsByElement.get(selectedElement);
+}
+return null;
+},
+/**
+* Retrieves the selected element's index in this container.
+* @return number
+*/
+get selectedIndex() {
+let selectedElement = this._widget.selectedItem;
+if (selectedElement) {
+return this._indexOfElement(selectedElement);
+}
+return -1;
+},
+/**
+* Retrieves the value of the selected element.
+* @return string
+*/
+get selectedValue() {
+let selectedElement = this._widget.selectedItem;
+if (selectedElement) {
+return this._itemsByElement.get(selectedElement)._value;
+}
+return "";
+},
+/**
+* Retrieves the attachment of the selected element.
+* @return object | null
+*/
+get selectedAttachment() {
+let selectedElement = this._widget.selectedItem;
+if (selectedElement) {
+return this._itemsByElement.get(selectedElement).attachment;
+}
+return null;
+},
+/**
+* Selects the element with the entangled item in this container.
+* @param Item | function aItem
+*/
+set selectedItem(aItem) {
+// A predicate is allowed to select a specific item.
+// If no item is matched, then the current selection is removed.
+if (typeof aItem == "function") {
+aItem = this.getItemForPredicate(aItem);
+}
+// A falsy item is allowed to invalidate the current selection.
+let targetElement = aItem ? aItem._target : null;
+let prevElement = this._widget.selectedItem;
+// Make sure the selected item's target element is focused and visible.
+if (this.autoFocusOnSelection && targetElement) {
+targetElement.focus();
+}
+if (this.maintainSelectionVisible && targetElement) {
+if ("ensureElementIsVisible" in this._widget) {
+this._widget.ensureElementIsVisible(targetElement);
+}
+}
+// Prevent selecting the same item again and avoid dispatching
+// a redundant selection event, so return early.
+if (targetElement != prevElement) {
+this._widget.selectedItem = targetElement;
+let dispTarget = targetElement || prevElement;
+let dispName = this.suppressSelectionEvents ? "suppressed-select" : "select";
+ViewHelpers.dispatchEvent(dispTarget, dispName, aItem);
+}
+},
+/**
+* Selects the element at the specified index in this container.
+* @param number aIndex
+*/
+set selectedIndex(aIndex) {
+let targetElement = this._widget.getItemAtIndex(aIndex);
+if (targetElement) {
+this.selectedItem = this._itemsByElement.get(targetElement);
+return;
+}
+this.selectedItem = null;
+},
+/**
+* Selects the element with the specified value in this container.
+* @param string aValue
+*/
+set selectedValue(aValue) {
+this.selectedItem = this._itemsByValue.get(aValue);
+},
+/**
+* Specifies if this container should try to keep the selected item visible.
+* (For example, when new items are added the selection is brought into view).
+*/
+maintainSelectionVisible: true,
+/**
+* Specifies if "select" events dispatched from the elements in this container
+* when their respective items are selected should be suppressed or not.
+*
+* If this flag is set to true, then consumers of this container won't
+* be normally notified when items are selected.
+*/
+suppressSelectionEvents: false,
+/**
+* Focus this container the first time an element is inserted?
+*
+* If this flag is set to true, then when the first item is inserted in
+* this container (and thus it's the only item available), its corresponding
+* target element is focused as well.
+*/
+autoFocusOnFirstItem: true,
+/**
+* Focus on selection?
+*
+* If this flag is set to true, then whenever an item is selected in
+* this container (e.g. via the selectedIndex or selectedItem setters),
+* its corresponding target element is focused as well.
+*
+* You can disable this flag, for example, to maintain a certain node
+* focused but visually indicate a different selection in this container.
+*/
+autoFocusOnSelection: true,
+/**
+* Focus on input (e.g. mouse click)?
+*
+* If this flag is set to true, then whenever an item receives user input in
+* this container, its corresponding target element is focused as well.
+*/
+autoFocusOnInput: true,
+/**
+* When focusing on input, allow right clicks?
+* @see WidgetMethods.autoFocusOnInput
+*/
+allowFocusOnRightClick: false,
+/**
+* The number of elements in this container to jump when Page Up or Page Down
+* keys are pressed. If falsy, then the page size will be based on the
+* number of visible items in the container.
+*/
+pageSize: 0,
+/**
+* Focuses the first visible item in this container.
+*/
+focusFirstVisibleItem: function() {
+this.focusItemAtDelta(-this.itemCount);
+},
+/**
+* Focuses the last visible item in this container.
+*/
+focusLastVisibleItem: function() {
+this.focusItemAtDelta(+this.itemCount);
+},
+/**
+* Focuses the next item in this container.
+*/
+focusNextItem: function() {
+this.focusItemAtDelta(+1);
+},
+/**
+* Focuses the previous item in this container.
+*/
+focusPrevItem: function() {
+this.focusItemAtDelta(-1);
+},
+/**
+* Focuses another item in this container based on the index distance
+* from the currently focused item.
+*
+* @param number aDelta
+*        A scalar specifying by how many items should the selection change.
+*/
+focusItemAtDelta: function(aDelta) {
+// Make sure the currently selected item is also focused, so that the
+// command dispatcher mechanism has a relative node to work with.
+// If there's no selection, just select an item at a corresponding index
+// (e.g. the first item in this container if aDelta <= 1).
+let selectedElement = this._widget.selectedItem;
+if (selectedElement) {
+selectedElement.focus();
+} else {
+this.selectedIndex = Math.max(0, aDelta - 1);
+return;
+}
+let direction = aDelta > 0 ? "advanceFocus" : "rewindFocus";
+let distance = Math.abs(Math[aDelta > 0 ? "ceil" : "floor"](aDelta));
+while (distance--) {
+if (!this._focusChange(direction)) {
+break; // Out of bounds.
+}
+}
+// Synchronize the selected item as being the currently focused element.
+this.selectedItem = this.getItemForElement(this._focusedElement);
+},
+/**
+* Focuses the next or previous item in this container.
+*
+* @param string aDirection
+*        Either "advanceFocus" or "rewindFocus".
+* @return boolean
+*         False if the focus went out of bounds and the first or last item
+*         in this container was focused instead.
+*/
+_focusChange: function(aDirection) {
+let commandDispatcher = this._commandDispatcher;
+let prevFocusedElement = commandDispatcher.focusedElement;
+let currFocusedElement;
+do {
+commandDispatcher.suppressFocusScroll = true;
+commandDispatcher[aDirection]();
+currFocusedElement = commandDispatcher.focusedElement;
+// Make sure the newly focused item is a part of this container. If the
+// focus goes out of bounds, revert the previously focused item.
+if (!this.getItemForElement(currFocusedElement)) {
+prevFocusedElement.focus();
+return false;
+}
+} while (!WIDGET_FOCUSABLE_NODES.has(currFocusedElement.tagName));
+// Focus remained within bounds.
+return true;
+},
+/**
+* Gets the command dispatcher instance associated with this container's DOM.
+* If there are no items displayed in this container, null is returned.
+* @return nsIDOMXULCommandDispatcher | null
+*/
+get _commandDispatcher() {
+if (this._cachedCommandDispatcher) {
+return this._cachedCommandDispatcher;
+}
+let someElement = this._widget.getItemAtIndex(0);
+if (someElement) {
+let commandDispatcher = someElement.ownerDocument.commandDispatcher;
+return this._cachedCommandDispatcher = commandDispatcher;
+}
+return null;
+},
+/**
+* Gets the currently focused element in this container.
+*
+* @return nsIDOMNode
+*         The focused element, or null if nothing is found.
+*/
+get _focusedElement() {
+let commandDispatcher = this._commandDispatcher;
+if (commandDispatcher) {
+return commandDispatcher.focusedElement;
+}
+return null;
+},
+/**
+* Gets the item in the container having the specified index.
+*
+* @param number aIndex
+*        The index used to identify the element.
+* @return Item
+*         The matched item, or null if nothing is found.
+*/
+getItemAtIndex: function(aIndex) {
+return this.getItemForElement(this._widget.getItemAtIndex(aIndex));
+},
+/**
+* Gets the item in the container having the specified value.
+*
+* @param string aValue
+*        The value used to identify the element.
+* @return Item
+*         The matched item, or null if nothing is found.
+*/
+getItemByValue: function(aValue) {
+return this._itemsByValue.get(aValue);
+},
+/**
+* Gets the item in the container associated with the specified element.
+*
+* @param nsIDOMNode aElement
+*        The element used to identify the item.
+* @param object aFlags [optional]
+*        Additional options for showing the source. Supported options:
+*          - noSiblings: if siblings shouldn't be taken into consideration
+*                        when searching for the associated item.
+* @return Item
+*         The matched item, or null if nothing is found.
+*/
+getItemForElement: function(aElement, aFlags = {}) {
+while (aElement) {
+let item = this._itemsByElement.get(aElement);
+// Also search the siblings if allowed.
+if (!aFlags.noSiblings) {
+item = item ||
+this._itemsByElement.get(aElement.nextElementSibling) ||
+this._itemsByElement.get(aElement.previousElementSibling);
+}
+if (item) {
+return item;
+}
+aElement = aElement.parentNode;
+}
+return null;
+},
+/**
+* Gets a visible item in this container validating a specified predicate.
+*
+* @param function aPredicate
+*        The first item which validates this predicate is returned
+* @return Item
+*         The matched item, or null if nothing is found.
+*/
+getItemForPredicate: function(aPredicate, aOwner = this) {
+// Recursively check the items in this widget for a predicate match.
+for (let [element, item] of aOwner._itemsByElement) {
+let match;
+if (aPredicate(item) && !element.hidden) {
+match = item;
+} else {
+match = this.getItemForPredicate(aPredicate, item);
+}
+if (match) {
+return match;
+}
+}
+// Also check the staged items. No need to do this recursively since
+// they're not even appended to the view yet.
+for (let { item } of this._stagedItems) {
+if (aPredicate(item)) {
+return item;
+}
+}
+return null;
+},
+/**
+* Shortcut function for getItemForPredicate which works on item attachments.
+* @see getItemForPredicate
+*/
+getItemForAttachment: function(aPredicate, aOwner = this) {
+return this.getItemForPredicate(e => aPredicate(e.attachment));
+},
+/**
+* Finds the index of an item in the container.
+*
+* @param Item aItem
+*        The item get the index for.
+* @return number
+*         The index of the matched item, or -1 if nothing is found.
+*/
+indexOfItem: function(aItem) {
+return this._indexOfElement(aItem._target);
+},
+/**
+* Finds the index of an element in the container.
+*
+* @param nsIDOMNode aElement
+*        The element get the index for.
+* @return number
+*         The index of the matched element, or -1 if nothing is found.
+*/
+_indexOfElement: function(aElement) {
+for (let i = 0; i < this._itemsByElement.size; i++) {
+if (this._widget.getItemAtIndex(i) == aElement) {
+return i;
+}
+}
+return -1;
+},
+/**
+* Gets the total number of items in this container.
+* @return number
+*/
+get itemCount() {
+return this._itemsByElement.size;
+},
+/**
+* Returns a list of items in this container, in the displayed order.
+* @return array
+*/
+get items() {
+let store = [];
+let itemCount = this.itemCount;
+for (let i = 0; i < itemCount; i++) {
+store.push(this.getItemAtIndex(i));
+}
+return store;
+},
+/**
+* Returns a list of values in this container, in the displayed order.
+* @return array
+*/
+get values() {
+return this.items.map(e => e._value);
+},
+/**
+* Returns a list of attachments in this container, in the displayed order.
+* @return array
+*/
+get attachments() {
+return this.items.map(e => e.attachment);
+},
+/**
+* Returns a list of all the visible (non-hidden) items in this container,
+* in the displayed order
+* @return array
+*/
+get visibleItems() {
+return this.items.filter(e => !e._target.hidden);
+},
+/**
+* Checks if an item is unique in this container. If an item's value is an
+* empty string, "undefined" or "null", it is considered unique.
+*
+* @param Item aItem
+*        The item for which to verify uniqueness.
+* @return boolean
+*         True if the item is unique, false otherwise.
+*/
+isUnique: function(aItem) {
+let value = aItem._value;
+if (value == "" || value == "undefined" || value == "null") {
+return true;
+}
+return !this._itemsByValue.has(value);
+},
+/**
+* Checks if an item is eligible for this container. By default, this checks
+* whether an item is unique and has a prebuilt target node.
+*
+* @param Item aItem
+*        The item for which to verify eligibility.
+* @return boolean
+*         True if the item is eligible, false otherwise.
+*/
+isEligible: function(aItem) {
+return this.isUnique(aItem) && aItem._prebuiltNode;
+},
+/**
+* Finds the expected item index in this container based on the default
+* sort predicate.
+*
+* @param Item aItem
+*        The item for which to get the expected index.
+* @return number
+*         The expected item index.
+*/
+_findExpectedIndexFor: function(aItem) {
+let itemCount = this.itemCount;
+for (let i = 0; i < itemCount; i++) {
+if (this._currentSortPredicate(this.getItemAtIndex(i), aItem) > 0) {
+return i;
+}
+}
+return itemCount;
+},
+/**
+* Immediately inserts an item in this container at the specified index.
+*
+* @param number aIndex
+*        The position in the container intended for this item.
+* @param Item aItem
+*        The item describing a target element.
+* @param object aOptions [optional]
+*        Additional options or flags supported by this operation:
+*          - attributes: a batch of attributes set to the displayed element
+*          - finalize: function when the item is untangled (removed)
+* @return Item
+*         The item associated with the displayed element, null if rejected.
+*/
+_insertItemAt: function(aIndex, aItem, aOptions = {}) {
+if (!this.isEligible(aItem)) {
+return null;
+}
+// Entangle the item with the newly inserted node.
+// Make sure this is done with the value returned by insertItemAt(),
+// to avoid storing a potential DocumentFragment.
+let node = aItem._prebuiltNode;
+let attachment = aItem.attachment;
+this._entangleItem(aItem, this._widget.insertItemAt(aIndex, node, attachment));
+// Handle any additional options after entangling the item.
+if (!this._currentFilterPredicate(aItem)) {
+aItem._target.hidden = true;
+}
+if (this.autoFocusOnFirstItem && this._itemsByElement.size == 1) {
+aItem._target.focus();
+}
+if (aOptions.attributes) {
+aOptions.attributes.forEach(e => aItem._target.setAttribute(e[0], e[1]));
+}
+if (aOptions.finalize) {
+aItem.finalize = aOptions.finalize;
+}
+// Hide the empty text if the selection wasn't lost.
+this._widget.removeAttribute("emptyText");
+// Return the item associated with the displayed element.
+return aItem;
+},
+/**
+* Entangles an item (model) with a displayed node element (view).
+*
+* @param Item aItem
+*        The item describing a target element.
+* @param nsIDOMNode aElement
+*        The element displaying the item.
+*/
+_entangleItem: function(aItem, aElement) {
+this._itemsByValue.set(aItem._value, aItem);
+this._itemsByElement.set(aElement, aItem);
+aItem._target = aElement;
+},
+/**
+* Untangles an item (model) from a displayed node element (view).
+*
+* @param Item aItem
+*        The item describing a target element.
+*/
+_untangleItem: function(aItem) {
+if (aItem.finalize) {
+aItem.finalize(aItem);
+}
+for (let childItem of aItem) {
+aItem.remove(childItem);
+}
+this._unlinkItem(aItem);
+aItem._target = null;
+},
+/**
+* Deletes an item from the its parent's storage maps.
+*
+* @param Item aItem
+*        The item describing a target element.
+*/
+_unlinkItem: function(aItem) {
+this._itemsByValue.delete(aItem._value);
+this._itemsByElement.delete(aItem._target);
+},
+/**
+* The keyPress event listener for this container.
+* @param string aName
+* @param KeyboardEvent aEvent
+*/
+_onWidgetKeyPress: function(aName, aEvent) {
+// Prevent scrolling when pressing navigation keys.
+ViewHelpers.preventScrolling(aEvent);
+switch (aEvent.keyCode) {
+case aEvent.DOM_VK_UP:
+case aEvent.DOM_VK_LEFT:
+this.focusPrevItem();
+return;
+case aEvent.DOM_VK_DOWN:
+case aEvent.DOM_VK_RIGHT:
+this.focusNextItem();
+return;
+case aEvent.DOM_VK_PAGE_UP:
+this.focusItemAtDelta(-(this.pageSize || (this.itemCount / PAGE_SIZE_ITEM_COUNT_RATIO)));
+return;
+case aEvent.DOM_VK_PAGE_DOWN:
+this.focusItemAtDelta(+(this.pageSize || (this.itemCount / PAGE_SIZE_ITEM_COUNT_RATIO)));
+return;
+case aEvent.DOM_VK_HOME:
+this.focusFirstVisibleItem();
+return;
+case aEvent.DOM_VK_END:
+this.focusLastVisibleItem();
+return;
+}
+},
+/**
+* The mousePress event listener for this container.
+* @param string aName
+* @param MouseEvent aEvent
+*/
+_onWidgetMousePress: function(aName, aEvent) {
+if (aEvent.button != 0 && !this.allowFocusOnRightClick) {
+// Only allow left-click to trigger this event.
+return;
+}
+let item = this.getItemForElement(aEvent.target);
+if (item) {
+// The container is not empty and we clicked on an actual item.
+this.selectedItem = item;
+// Make sure the current event's target element is also focused.
+this.autoFocusOnInput && item._target.focus();
+}
+},
+/**
+* The predicate used when filtering items. By default, all items in this
+* view are visible.
+*
+* @param Item aItem
+*        The item passing through the filter.
+* @return boolean
+*         True if the item should be visible, false otherwise.
+*/
+_currentFilterPredicate: function(aItem) {
+return true;
+},
+/**
+* The predicate used when sorting items. By default, items in this view
+* are sorted by their label.
+*
+* @param Item aFirst
+*        The first item used in the comparison.
+* @param Item aSecond
+*        The second item used in the comparison.
+* @return number
+*         -1 to sort aFirst to a lower index than aSecond
+*          0 to leave aFirst and aSecond unchanged with respect to each other
+*          1 to sort aSecond to a lower index than aFirst
+*/
+_currentSortPredicate: function(aFirst, aSecond) {
+return +(aFirst._value.toLowerCase() > aSecond._value.toLowerCase());
+},
+/**
+* Call a method on this widget named `aMethodName`. Any further arguments are
+* passed on to the method. Returns the result of the method call.
+*
+* @param String aMethodName
+*        The name of the method you want to call.
+* @param aArgs
+*        Optional. Any arguments you want to pass through to the method.
+*/
+callMethod: function(aMethodName, ...aArgs) {
+return this._widget[aMethodName].apply(this._widget, aArgs);
+},
+_widget: null,
+_emptyText: "",
+_headerText: "",
+_preferredValue: "",
+_cachedCommandDispatcher: null
+};
+/**
+* A generator-iterator over all the items in this container.
+*/
+Item.prototype["@@iterator"] =
+WidgetMethods["@@iterator"] = function*() {
+yield* this._itemsByElement.values();
+};

The Tor Browser / file comparison

comparison: browser/devtools/shared/widgets/ViewHelpers.jsm

browser/devtools/shared/widgets/ViewHelpers.jsm