Moobile.ButtonGroup

Moobile.ButtonGroup

397 737 ThomasEngels
Extends Moobile.Control

Provides a control that group buttons and handle the selection of these buttons.

Initialization

Syntax:

var buttonGroup = new Moobile.ButtonGroup([element], [options], [name]);

Parameters:

Name Type Description
element Optional Element The button group’s element, element id or html string.
options Optional Object The button group’s options, see below.
name Optional String The button group’s name.

Options:

Name Type Description
className String The button group’s extended CSS class name, defaults to null.
styleName String The button group’s default style, defaults to null.
tagName String The button group’s element tag name, defaults to div.
layout String The button group’s layout, either horizontal or vertical, defaults to horizontal.
selectable Boolean Whether a button can be selected, defaults to true.
selectedButtonIndex Number The button group’s default selected button index, defaults to -1.

Generates:

<div class="button-group"></div>

Note:

Buttons can be added to this button group by adding elements with the button data-role attribute:

<div data-role="button-group">
    <div data-role="button">Button 1</div>
    <div data-role="button">Button 2</div>
    <div data-role="button">Button 3</div>
    <div data-role="button">Button 4</div>
</div>

Subclassing Notes:

This class overrides the following method:

  • willBuild: Call the parent method at the top of your implementation if you override this method.
  • destroy : Call the parent method at the bottom of your implementation if you override this method.
  • didAddChildComponent: Call the parent method at the top of your implementation if you override this method.
  • didRemoveChildComponent: Call the parent method at the top of your implementation if you override this method.

Defined roles:

Name Description Applies to Note
button-group Defines an element acting as a Moobile.ButtonGroup control All components Use the data-button-group attribute to specify a subclass instead

Examples:

Specifying an element that acts a button group control using the data-role attribute:
<div data-role="button-group"></div>
Specifying an element that acts a button group control subclass using the data-role attribute:
<div data-role="button-group" data-button="MyButtonGroup"></div>

Events

select

Fired when a button is selected.

Arguments

Name Type Description
button Moobile.Button The selected button.

deselect

Fired when a button is deselected.

Arguments

Name Type Description
button Moobile.Button The button that was deselected.

Methods

setSelectedButton(selectedButton)

Selects the specified button and deselect the currently selected button if any. You can also clear the selected button by specifying null instead of a button.

This methods fires the deselect and select events.

Parameters:

Name Type Description
selectedButton Moobile.Button The selected button or null to clear the selection.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.setSelectedButton(buttonOne); // selects the first button

getSelectedButton()

Returns the selected button.

Returns:

  • Moobile.Button The selected button or null if no buttons are selected.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.setSelectedButton(buttonOne);
buttonGroup.getSelectedButton(); // returns buttonOne

setSelectedButtonIndex(index)

Selects a button using a specified index, 0 being the first button in the list. Specifying an index that matches no buttons will clear the selection.

Parameters:

Name Type Description
index Number The selected button index.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.setSelectedButtonIndex(0); // selects the first button

getSelectedButtonIndex()

Returns the index of the selected button or -1 if no buttons are selected.

Returns:

  • Number The selected button index or -1 if no buttons are selected.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.setSelectedButtonIndex(0);
buttonGroup.getSelectedButtonIndex(); // returns 0

clearSelectedButton()

Unselects the selected button.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.setSelectedButtonIndex(0);
buttonGroup.clearSelectedButton();

addButton(button, [where])

Adds the specified button at the top or bottom of this button group. If where is omitted, the button will be added at the bottom of this button group. The button may be a string. In this case, this method will create a Moobile.Button instance and set the specified string as its label.

Parameters:

Name Type Description
button Mixed The button as a string or a Moobile.Button instance.
where Optional String The button’s location, either top or bottom, defaults to bottom.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
buttonGroup.addButton(buttonOne);

addButtonAfter(button, after)

Adds the specified button after a button from this button group. The button may be a string. In this case, this method will create a Moobile.Button instance and set the specified string as its label.

Parameters:

Name Type Description
button Mixed The button as a string or a Moobile.Button instance.
after Moobile.Button The button will be placed after this button.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButtonAfter(buttonTwo, buttonOne); // buttonTwo is after buttonOne

addButtonBefore(button, before)

Adds the specified button before a button from this button group. The button may be a string. In this case, this method will create a Moobile.Button instance and set the specified string as its label.

Parameters:

Name Type Description
button Mixed The button as a string or a Moobile.Button instance.
after Moobile.Button The button will be placed before this button.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButtonBefore(buttonTwo, buttonOne); // buttonTwo is before buttonOne

getButtons()

Returns all buttons in this button group.

Returns:

  • Array An array of all buttons in this button group.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.getButtons(); // returns [buttonOne, buttonTwo]

getButton(name)

Returns a button that matches the specified name.

Parameters:

Name Type Description
name String The name of the button to search for.

Returns:

  • Moobile.Button The button or null if no buttons were found with the name.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button(null, null, 'me');
buttonGroup.addButton(buttonOne);
buttonGroup.getButton('me'); // returns buttonOne

getButtonAt(index)

Return a button at a specified index.

Parameters:

Name Type Description
index Number The index location of the button.

Returns:

  • Moobile.Button The button or null if no buttons were found at the index.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.getButtonAt(0); // returns buttonOne

removeButton(button, [destroy])

Removes a button.

Parameters:

Name Type Description
button Moobile.Button The button to remove.
destroy Optional Boolean Whether to destroy the button upon removal.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.removeButton(buttonOne); // the button group contains only buttonTwo

removeAllButtons()

Removes all buttons.

Parameters:

Name Type Description
destroy Optional Boolean Whether to destroy the buttons upon removal.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

Example:

var buttonGroup = new Moobile.ButtonGroup();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
buttonGroup.addButton(buttonOne);
buttonGroup.addButton(buttonTwo);
buttonGroup.removeAllButtons(); // no buttons remains

setSelectable(selectable)

Sets whether buttons from this button group are selectable.

Parameters:

Name Type Description
selectable Boolean Whether buttons from this button group are selectable.

Returns:

  • Moobile.ButtonGroup This Moobile.ButtonGroup instance.

isSelectable(selectable)

Indicates whether buttons from this button group are selectable.

Returns:

  • Boolean Whether buttons from this button group are selectable.