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 thetop
of your implementation if you override this method.destroy
: Call the parent method at thebottom
of your implementation if you override this method.didAddChildComponent
: Call the parent method at thetop
of your implementation if you override this method.didRemoveChildComponent
: Call the parent method at thetop
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.