h2. {color:#000000}{}Overview{}{color} {excerpt}This Quick Guide gives a brief overview of how to use dmc_buttons to create different buttons and button groups.{excerpt} {info}For more detailed information on the button classes, see the dmc_buttons Documentation.{info} {tip:title=More Examples}Besides the examples shown in this document, there are other, more complete examples which can be run on the Corona simulator or a mobile device. These are located in the folder examples/dmc_buttons/ which comes bundled with DMC Corona Library.{tip}

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

h2. Button Objects Overview

The following is a description of the button objects which can be created from dmc_buttons: || {color:#003366}{}Buttons{}{color} || {color:#003366}{}Constructor Param{}{color} || {color:#003366}{}Description{}{color} || | Push Button | "push" | The push button is a momentary-type button which will move into the "down" position when it is tapped and as long as the tap is held. It will immediately return to its "up" position when released. | | Toggle Button | "toggle" | This button has two states associated with it - "active" and "inactive". When tapped it will alternate between the two states and remain in the state until pressed again. This button can be used by itself or in a Toggle Group. | | Toggle Button Group | "toggleGroup" | The Toggle Group links together a set of Toggle Buttons so they act as a unit. Though all of the buttons will still toggle, the Toggle Group will make sure that only one button is active at any given time. | | Radio Button | "radio" | Like the Toggle Button, the Radio Button also has two states associated with it - "active" and "inactive". Unlike the Toggle Button, this button is intended to be used in a Radio Group, not by itself. | | Radio Button Group | "radioGroup" | The Radio Group links together a set of Radio Buttons so they act as a unit. The Radio Group will make sure that at least one and only one button is active at any given time. |

h3. Constructor Parameter

All buttons and button groups are created via the button factory object. The constructor is given the name of the desired object as a parameter. The different object names are listed in the table above.

Here is a simplified example using the button factory: {code:language=none|title=Object Creation via the Button Factory}-- import dmc_buttons into the namespace -- 'Buttons' is the name of our "factory", but it can be anything, eg 'ButtonFactory' local Buttons = require( "dmc_buttons" )

-- create a Toggle Group, pass in "toggleGroup" local toggleGroup = Buttons.create( "toggleGroup" )

-- create a Toggle Button, pass in "toggle" local toggle = Buttons.create( "toggle", ... )

...{code}

h2. Buttons

h3. Button Parameter List

A partial list of button parameters (the "global" part) is shown here, mainly for quick reference. The parts not shown are specific to a button's different views, however, they follow the same structure. They are discussed next.

Note that it isn't required to use the entire configuration, only the parts needed. {info}For a more complete explanation of button configuration, including examples of the full button configuration, see the [dmc_buttons Documentation|docs:dmc_buttons Documentation].{info} {code:language=none|title=Partial Button Parameter List}local anyButton = Buttons.create( "", {

id="buttonName",

-- Global Configs
defaultSrc="",
width=0,
height=0,
label="",
style={
    font = native.systemFontBold,
    size = 0,
    color = { 255, 255, 255, 255 },
    xOffset = 0,
    yOffset = 0,
}

-- view specific configurations follow
...

}{code}

h4. View Specific Parameters

Each button type has a parameter list for each view, similar to the general one shown above. It is these "view-specific" parameters which actually control the look of the view. Anything defined in the "global parameters" ultimately gets copied to the view-specific structure.

Table of Button Views || {color:#003366}{}Button Type{}{color} || {color:#003366}{}Views{}{color} || | Push Button | up, down | | Toggle Button | active, inactive | | Radio Button | active, inactive | \ {info}In the future, more views will be added. For example a "disabled" view for all buttons, and a "down" view for the Toggle Button and Radio Buttons.{info} A button view can be precisely configured by adding a parameter structure with the given name of the view to be configured. For example, here's an example adding configuration to a Push Button's down view.

{code:title=Specific View Configuration Structure|linenumbers=true}local anyButton = Buttons.create( "push", {

id="pushButton1",    -- a unique ID for this button

-- Global Configs as before
...

-- state specific configurations follow

-- structure for the "down" view ( all view structures are the same )

downSrc = "",    -- shorthand for the parameter at 'down = { source = "" }'
down = {
    -- these modify the image used for the state
    source="",            -- image file on filesystem for this state
    width=0,            -- width of image
    height=0,            -- height of image
    xOffset=0,            -- x offset
    yOffset=0,            -- y offset

    -- these are for the optional label
    label=nil,                -- string label for button
    style={                    -- style info for the label
        font = native.systemFontBold,
        size = 17,
        color = { 255, 255, 255, 255 },
        xOffset = 0,
        yOffset = 0,

}{code}   {color:#000000}{}put in multi excerpt{}{color}

h2. {color:#000000}{}Button Groups{}{color}

{color:#000000}{}There are two types of button groups, the Radio Group and the Toggle Group.{color}

{color:#000000}The radio group is used when you need a set of radio buttons - a group of buttons where only one {color}{color:#000000}{}can{}{color}{color:#000000} be active at any time and one {color}{color:#000000}{}must{}{color}{color:#000000} be active.{color}

{color:#000000}The second type of group is a Toggle Group - this is a group of buttons where none {color}{color:#000000}{}must{}{color}{color:#000000} be active, but only one {color}{color:#000000}{}can{}{color}{color:#000000} be active.{color}

h3. {color:#000000}Button Group Parameter List{color}

{color:#000000}For now, there aren't any parameters which can be passed into the Button Group constructor. However, there is a {color}setActive{color:#000000} parameter which can be passed into the Button Group's {color}add(){color:#000000} method. This will set the the button being added to state {color}active{color:#000000}, eg, it will be selected.:{color}

{code:language=none}anyButtonGroup:add( anyButtonObject, { setActive = true, }){code}

For more details about Button Group configuration, see [dmc_buttons Documentation|#QuickGuide-dmcbuttons-buttongroups].

h3. Radio Group

{code:language=none|linenumbers=true}function handleButtonGroupChange( event ) -- handle the button group event here... end

local radioBtn -- used for all of our buttons

local radioGroup = Buttons.create( "radioGroup" ) radioGroup:addEventListener( "change", handleButtonGroupChange )

local y_base = 100 -- our y position for all buttons in the group

-- setup button parameters object because most params are the same local button_params = { width=52, height=52, inactiveSrc = "assets/buttons/btn_off.png", activeSrc = "assets/buttons/btn_on.png", }

button_params.id = "one" radioBtn = Buttons.create( "radio", button_params ) radioGroup:add( radioBtn ) radioBtn.x, radioBtn.y = 80, y_base

button_params.id = "two" radioBtn = Buttons.create( "radio", button_params ) -- we want this one to be active at the start radioGroup:add( radioBtn, { setActive = true } ) radioBtn.x, radioBtn.y = 160, y_base

button_params.id = "three" radioBtn = Buttons.create( "radio", button_params ) radioGroup:add( radioBtn ) radioBtn.x, radioBtn.y = 240, y_base{code}

{note}Only Radio Buttons should be added to Radio Groups.{note}

h3. Toggle Group

{code:language=none|linenumbers=true}function handleButtonGroupChange( event ) -- handle the button group event here... end

local toggleBtn -- used for all of our buttons

local toggleGroup = Buttons.create( "toggleGroup" ) toggleGroup:addEventListener( "change", handleButtonGroupChange )

local y_base = 100 -- our y position for all buttons in the group

-- setup button parameters object because most params are the same local button_params = { width=52, height=52, inactiveSrc = "assets/buttons/btn_toggle_off.png", activeSrc = "assets/buttons/btn_toggle_on.png", }

button_params.id = "one" -- finish parameters toggleBtn = Buttons.create( "toggle", button_params ) toggleGroup:add( toggleBtn ) toggleBtn.x, toggleBtn.y = 80, y_base

button_params.id = "two" toggleBtn = Buttons.create( "toggle", button_params ) toggleGroup:add( toggleBtn ) toggleBtn.x, toggleBtn.y = 160, y_base

button_params.id = "three" toggleBtn = Buttons.create( "toggle", button_params ) toggleGroup:add( toggleBtn ) toggleBtn.x, toggleBtn.y = 240, y_base{code}

{note}Only Toggle Buttons should be added to Toggle Groups.{note}

h3. Button Group Events

h4. A Button Group Event {code:language=none|title=General Button Group Event}event.name = "change" -- the name of the event event.target = dmc button object event.label = id from constructor of dmc button event.state = string of button's state -- eg, STATE_ACTIVE or STATE_INACTIVE{code}

h4. Event Listeners

Just like standard Corona Display Objects, events are captured by adding an Event Listener on the button group object itself, either an object or a function.