{excerpt:hidden=true} API details for {{dmc.newButtonGroup}}. {excerpt}

h2. Table of Contents {toc:style=disc|indent=20px|minLevel=2|exclude=Table of Contents|printable=false}

h2. Widget.newButtonGroup()

Creates a button group object.

h3. Syntax

{code} local Widget = require 'dmc_widgets'

local group = Widget.newButtonGroup( params ) {code}

This function takes a single argument, {{params}}, which is a table that accepts the following basic parameters:

h4. params.set_first_active (optional)

{{Boolean}}. Determines whether or not to set the first added button to {{active}}.

Radio Group - When using a Radio Group this parameter is always {{true}} an cannot be changed.

Toggle Group - When using a Toggle Group the default is {{false}}, do not set first button active.

h3. Properties

h4. group.selected (read-only)

Returns a reference to the button which is currently active. This could be {{nil}} when using a {{toggle}} group.

{code:language=none} button = button_group.selected if button then print( button.id, button.value ) -- prints the button id and value end {code}

h3. Methods

h4. group:add( button, params )

Adds an existing button to the button group. By default, the first button added to a group is set as active.

  • button (required) The button object to add. This should be one of {{toggle}} or {{radio}} buttons, according to the type of group used.
  • params (optional) Params is a table that accepts the following basic parameters: ** {{set_active}} (optional) {{boolean}}. Determines if the button will be set to {{active}} after being added. Defaults to {{false}}

{code:language=none} group:add( button1 ) group:add( button2, { set_active=true } ) {code}

h4. group:remove( button )

Method to remove an existing button from the button group.

  • button (required) The button object to remove. This should be one of the objects given to the {{add()}} method.

{code:language=none} group:remove( button ) {code}

h4. group:getButton( id )

Method to retrieve button object from the button group given the id string. Returns {{nil}} if not found.

  • id (required) The button id to retrieve.

{code:language=none} local button = group:getButton( 'arrow-up' ) {code}