Source: ui/button/ButtonGroup.js

//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------

/**
 * Creates a container that manages button focus and navigation.
 *
 * @constructor
 * @extends rune.display.DisplayObjectContainer
 *
 * @param {number} [x=0] Horizontal position.
 * @param {number} [y=0] Vertical position.
 *
 * @class
 * @classdesc
 * Accepts Button children and navigates in insertion order, independently of
 * display depth or sorting. Navigation skips hidden or disabled buttons and wraps by
 * default; set wrap to false to stop at the ends. The
 * first enabled button receives focus. Game code positions the children and
 * supplies input through next(), previous(), select(), press() and release().
 * Focus is reconciled during update(), selection queries and input calls, so
 * hiding or disabling the selected button moves focus to the next available button.
 * Button focus is owned by the group while the button is a child.
 * The pixel buffer automatically fits the buttons, including negative positions,
 * scaling and rotation. Child coordinates remain relative to the group origin.
 * Inherited autoSize is enabled by default and can be disabled for manual sizing.
 */
rune.ui.ButtonGroup = function(x, y) {

    //--------------------------------------------------------------------------
    // Private properties
    //--------------------------------------------------------------------------

    /**
     * Buttons in insertion order, independent of the display list order.
     *
     * @type {Array.<rune.ui.Button>}
     * @private
     */
    this.m_buttons = [];

    /**
     * Currently selected button, or null when none is enabled.
     *
     * @type {rune.ui.Button}
     * @private
     */
    this.m_selected = null;

    /**
     * Button whose press originated in this group.
     *
     * @type {rune.ui.Button}
     * @private
     */
    this.m_pressed = null;

    /**
     * Whether group navigation and activation are enabled.
     *
     * @type {boolean}
     * @private
     */
    this.m_enabled = true;

    /**
     * Whether explicit navigation wraps at the ends.
     *
     * @type {boolean}
     * @private
     */
    this.m_wrap = true;

    /**
     * Handler executed after the selected button changes.
     *
     * @type {rune.util.Executable}
     * @private
     */
    this.m_onChange = null;

    //--------------------------------------------------------------------------
    // Super call
    //--------------------------------------------------------------------------

    /**
     * Extend rune.display.DisplayObjectContainer.
     */
    rune.display.DisplayObjectContainer.call(this, x, y, 0, 0);
    
    //--------------------------------------------------------------------------
    // Override public properties
    //--------------------------------------------------------------------------
    
    /**
     * @inheritDoc
     */
    this.immovable = true;
    
    /**
     * @inheritDoc
     */
    this['autoSize'] = true;
};

//------------------------------------------------------------------------------
// Inheritance
//------------------------------------------------------------------------------

rune.ui.ButtonGroup.prototype = Object.create(rune.display.DisplayObjectContainer.prototype);
rune.ui.ButtonGroup.prototype.constructor = rune.ui.ButtonGroup;

//------------------------------------------------------------------------------
// Public getter and setter methods
//------------------------------------------------------------------------------

/**
 * Selected button, or null when no button is enabled.
 *
 * @member {rune.ui.Button} selected
 * @memberof rune.ui.ButtonGroup
 * @instance
 * @readonly
 */
Object.defineProperty(rune.ui.ButtonGroup.prototype, "selected", {
    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    get : function() {
        this.m_updateSelection();
        return this.m_selected;
    }
});

/**
 * Selected insertion-order index, or -1 when no button is enabled.
 * This index is independent of the child's display depth.
 *
 * @member {number} selectedIndex
 * @memberof rune.ui.ButtonGroup
 * @instance
 * @readonly
 */
Object.defineProperty(rune.ui.ButtonGroup.prototype, "selectedIndex", {
    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    get : function() {
        this.m_updateSelection();
        return this.m_buttons.indexOf(this.m_selected);
    }
});

/**
 * Whether navigation and activation are enabled. Disabling cancels a press
 * and clears visual focus while retaining the selected button.
 *
 * @member {boolean} enabled
 * @memberof rune.ui.ButtonGroup
 * @instance
 */
Object.defineProperty(rune.ui.ButtonGroup.prototype, "enabled", {
    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    get : function() {
        return this.m_enabled;
    },

    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    set : function(value) {
        value = Boolean(value);
        if (this.m_enabled !== value) {
            this.m_enabled = value;
            if (value === false) this.cancel();
            this.m_updateSelection();
        }
    }
});

/**
 * Whether next() and previous() wrap at the ends. Defaults to true.
 *
 * @member {boolean} wrap
 * @memberof rune.ui.ButtonGroup
 * @instance
 */
Object.defineProperty(rune.ui.ButtonGroup.prototype, "wrap", {
    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    get : function() {
        return this.m_wrap;
    },

    /**
     * @this rune.ui.ButtonGroup
     * @ignore
     */
    set : function(value) {
        value = Boolean(value);
        if (this.m_wrap !== value) {
            this.m_wrap = value;
        }
    }
});

//------------------------------------------------------------------------------
// Override public prototype methods (API)
//------------------------------------------------------------------------------

/**
 * Adds a Button at a display depth. Newly added buttons are appended to the
 * navigation order. Moving an existing child only changes its display depth.
 * Inherited addChild() also uses this method.
 *
 * @param {rune.display.DisplayObject} child Button to add.
 * @param {number} index Display list index.
 *
 * @throws {TypeError} If child is not a Button.
 * @return {rune.display.DisplayObject} Added button.
 */
rune.ui.ButtonGroup.prototype.addChildAt = function(child, index) {
    if (!(child instanceof rune.ui.Button)) throw new TypeError("ButtonGroup accepts Button children.");
    var button = /** @type {rune.ui.Button} */ (child);
    rune.display.DisplayObjectContainer.prototype.addChildAt.call(this, child, index);
    if (button['parent'] === this && this.m_buttons.indexOf(button) === -1) {
        button.cancel();
        button.blur();
        this.m_buttons.push(button);
    }
    this.m_updateSelection();
    return child;
};

/**
 * Removes a button and moves selection to its next enabled successor.
 * Inherited removeChildAt() and removeChildren() also use this method.
 *
 * @param {rune.display.DisplayObject} child Button to remove.
 * @param {boolean} [dispose=false] Whether to dispose the removed button.
 *
 * @return {rune.display.DisplayObject} Removed button, or null when disposed.
 */
rune.ui.ButtonGroup.prototype.removeChild = function(child, dispose) {
    var index = this.m_buttons.indexOf(/** @type {rune.ui.Button} */ (child));
    var selected = child === this.m_selected;
    if (index !== -1) {
        this.m_buttons[index].cancel();
        this.m_buttons[index].blur();
        this.m_buttons.splice(index, 1);
        if (selected) this.m_selected = null;
        if (child === this.m_pressed) this.m_pressed = null;
    }
    var result = rune.display.DisplayObjectContainer.prototype.removeChild.call(this, child, dispose);
    if (selected) this.m_setSelection(this.m_findButton(index - 1, 1), /** @type {rune.ui.Button} */ (child));
    this.m_updateSelection();
    return result;
};

//------------------------------------------------------------------------------
// Override public prototype methods (ENGINE)
//------------------------------------------------------------------------------

/**
 * @inheritDoc
 */
rune.ui.ButtonGroup.prototype.update = function(step) {
    this.m_updateSelection();
    rune.display.DisplayObjectContainer.prototype.update.call(this, step);
    this.m_updateSelection();
};

/**
 * @inheritDoc
 */
rune.ui.ButtonGroup.prototype.dispose = function() {
    this.cancel();
    this.m_disposeOnChange();
    this.m_enabled = false;
    rune.display.DisplayObjectContainer.prototype.dispose.call(this);
    this.m_buttons.length = 0;
    this.m_selected = null;
    this.m_pressed = null;
};

//------------------------------------------------------------------------------
// Public prototype methods (API)
//------------------------------------------------------------------------------

/**
 * Selects the next enabled button in insertion order. Respects wrap.
 *
 * @return {boolean} Whether selection changed.
 */
rune.ui.ButtonGroup.prototype.next = function() {
    if (this.m_enabled === false) return false;
    this.m_updateSelection();
    var button = this.m_findButton(this.m_buttons.indexOf(this.m_selected), 1, this.m_wrap);
    return button != null ? this.m_setSelection(button) : false;
};

/**
 * Selects the previous enabled button in insertion order. Respects wrap.
 *
 * @return {boolean} Whether selection changed.
 */
rune.ui.ButtonGroup.prototype.previous = function() {
    if (this.m_enabled === false) return false;
    this.m_updateSelection();
    var button = this.m_findButton(this.m_buttons.indexOf(this.m_selected), -1, this.m_wrap);
    return button != null ? this.m_setSelection(button) : false;
};

/**
 * Activates the selected button directly. Any pending group press is cancelled
 * first so a later release cannot trigger a second activation.
 * Activation is cancelled if a focus-change callback disables the group.
 *
 * @return {boolean} Whether activation was accepted.
 */
rune.ui.ButtonGroup.prototype.select = function() {
    if (this.m_enabled === false) return false;
    this.m_updateSelection();
    this.cancel();
    return this.m_enabled === true && this.m_selected != null ? this.m_selected.activate() : false;
};

/**
 * Begins a press on the selected button.
 *
 * @return {boolean} Whether a new press began.
 */
rune.ui.ButtonGroup.prototype.press = function() {
    if (this.m_enabled === false) return false;
    this.m_updateSelection();
    if (this.m_selected != null && this.m_selected.press()) {
        this.m_pressed = this.m_selected;
        return true;
    }
    return false;
};

/**
 * Releases the button pressed through this group. Navigation, removal or
 * disabling cancels that press, so another button cannot receive its release.
 *
 * @return {boolean} Whether the button was activated.
 */
rune.ui.ButtonGroup.prototype.release = function() {
    if (this.m_enabled === false) return false;
    this.m_updateSelection();
    var button = this.m_pressed;
    this.m_pressed = null;
    return button != null && button === this.m_selected ? button.release() : false;
};

/**
 * Cancels a press begun through this group without changing selection.
 *
 * @return {boolean} Whether a press was cancelled.
 */
rune.ui.ButtonGroup.prototype.cancel = function() {
    var button = this.m_pressed;
    this.m_pressed = null;
    return button != null ? button.cancel() : false;
};

/**
 * Focuses a button by its insertion-order index without activating it.
 * Invalid indices, hidden or disabled buttons and disabled groups are ignored.
 *
 * @param {number} index Insertion-order index.
 *
 * @return {boolean} Whether selection changed.
 */
rune.ui.ButtonGroup.prototype.focusAt = function(index) {
    if (typeof index !== "number" || index !== Math.floor(index) ||
        index < 0 || index >= this.m_buttons.length) return false;
    return this.focusButton(this.m_buttons[index]);
};

/**
 * Focuses a visible, enabled child button without activating it.
 *
 * @param {rune.ui.Button} button Button belonging to this group.
 *
 * @return {boolean} Whether selection changed.
 */
rune.ui.ButtonGroup.prototype.focusButton = function(button) {
    if (this.m_enabled === false || this.m_buttons.indexOf(button) === -1 ||
        button.enabled === false || button['visible'] === false) return false;
    return this.m_setSelection(button);
};

/**
 * Replaces the selection-change handler. Receives previous button, new button
 * and this group. Either button may be null. No event is emitted when the same
 * button remains selected or when registering the handler. Pass null to remove.
 *
 * @param {Function} func Handler, or null to remove it.
 * @param {Object} [scope] Handler execution scope.
 *
 * @throws {TypeError} If func is neither a function nor null.
 * @return {undefined}
 */
rune.ui.ButtonGroup.prototype.onChange = function(func, scope) {
    if (func != null && typeof func !== "function") throw new TypeError();
    this.m_disposeOnChange();
    if (func != null) this.m_onChange = new rune.util.Executable(func, scope);
};

//------------------------------------------------------------------------------
// Protected prototype methods
//------------------------------------------------------------------------------

/**
 * Restores a valid selection and ensures only its button has focus.
 *
 * @return {undefined}
 * @protected
 * @ignore
 */
rune.ui.ButtonGroup.prototype.m_updateSelection = function() {
    var index = this.m_buttons.indexOf(this.m_selected);
    if (index === -1 || this.m_selected.enabled === false || this.m_selected['visible'] === false) {
        this.m_setSelection(this.m_findButton(index, 1));
    }
    for (var i = 0; i < this.m_buttons.length; i++) {
        if (this.m_enabled === true && this.m_buttons[i] === this.m_selected) {
            this.m_buttons[i].focus();
        } else {
            this.m_buttons[i].blur();
        }
    }
};

/**
 * Finds an enabled button after an insertion-order index. Each button is
 * examined at most once; null is returned when none is enabled.
 *
 * @param {number} index Starting index, excluded until navigation wraps.
 * @param {number} direction Navigation direction, 1 or -1.
 * @param {boolean} [wrap=true] Whether to search past the ends. Automatic focus
 * repair always wraps so an available button is retained.
 *
 * @return {rune.ui.Button} Matching button, or null.
 * @protected
 * @ignore
 */
rune.ui.ButtonGroup.prototype.m_findButton = function(index, direction, wrap) {
    var count = this.m_buttons.length;
    for (var i = 0; i < count; i++) {
        index += direction;
        if (wrap === false && (index < 0 || index >= count)) return null;
        index = (index + count) % count;
        if (this.m_buttons[index].enabled === true && this.m_buttons[index]['visible'] === true) {
            return this.m_buttons[index];
        }
    }
    return null;
};

/**
 * Changes selection, cancelling a pending press and clearing previous focus.
 *
 * @param {rune.ui.Button} button Next selected button, or null.
 * @param {rune.ui.Button} [previous] Removed selection for notification only.
 *
 * @return {boolean} Whether selection changed.
 * @protected
 * @ignore
 */
rune.ui.ButtonGroup.prototype.m_setSelection = function(button, previous) {
    previous = previous === undefined ? this.m_selected : previous;
    if (previous === button) return false;
    this.cancel();
    if (this.m_selected != null) this.m_selected.blur();
    this.m_selected = button;
    if (this.m_enabled === true && this.m_selected != null) this.m_selected.focus();
    if (this.m_onChange != null) this.m_onChange.execute(previous, button, this);
    return true;
};

/**
 * Releases the selection-change handler and its execution scope.
 *
 * @return {undefined}
 * @protected
 * @ignore
 */
rune.ui.ButtonGroup.prototype.m_disposeOnChange = function() {
    if (this.m_onChange != null) {
        this.m_onChange.dispose();
        this.m_onChange = null;
    }
};