h2. Overview

[!gitHub-download-button.png|align=right!|https://github.com/dmccuskey/dmc-corona-widgets/]

{excerpt} This Quick Guide gives a brief overview of how to use {{dmc_widgets.newButton}} to create different buttons. {excerpt}

{tip} The API for the button construction is modeled closely to the Corona API so it is familar and easy to use. But it also allows a lot of customization for advanced needs. {tip}

{tip:title=Examples} There are several examples which come with the library. They are located in the folder named {{examples}}. {tip}

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

h2. Benefits of dmc.newButton

Here are some reasons to use {{dmc_widgets}}:

  • Three types of buttons - {{push}}, {{toggle}} and {{radio}}

  • Button visuals and labels can be customized/changed on the fly There is no need to re-create a button to have a different look.

  • There are three different views for each button -- {{active}}, {{inactive}}, and {{disabled}} Each view can be customized. The disabled view doesn't accept clicks.

  • You can easily create control groups for radio and toggle buttons Yes, button groups ! For more information, see [newButtonGroup].

  • The hit-area of a button can be modified The hit-area for any button can be increased or decreased with simple properties. This is especially useful for smaller buttons.

  • handlers can be either of callback or event variety They can also be added or changed at any time. The ultimate flexibility !

  • More adventurous developers can create their own button-view types Create the view-type that you've always wanted -- 3-slice, sliding-door, etc !

  • The library is fully object-oriented You can easily modify functionality to your needs

h2. Button Objects Overview

The two characteristics to understand about buttons created from {{dmc.newButton}} are:

Each button has a particular type, be it a push button, toggle button or radio button.

Each button has separate, configurable views for each state. These states are the same for all buttons types -- {{active}}, {{inactive}} and {{disabled}}. Each view is named after the corresponding state name.

With that in mind, next we'll cover the button types and the button constructor.

{info} For a more complete explanation of button configuration, including examples of the full button configuration, see the [newButton Documentation|docs:newButton Documentation]. {info}

h3. Button-Types

The following is a description of the button types which can be created from {{dmc.newButtons}}:

|| Buttons || Type Param || Description || | Push Button | {{type='push'}} | The push button is a momentary-type button which will move into the {{active}} position when it is touched and stay there as long as the touch is held. It will immediately return to its {{inactive}} position when the touch is released. | | Toggle Button | {{type='toggle'}} | When tapped, this button it will alternate between the two main states states -- {{active}} and {{inactive}} -- and remain in its current state until pressed again. This button can be used by itself or in a Toggle Group. | | Radio Button | {{type='radio'}} | Like the Toggle Button, the Radio Button also has two main states associated with it -- {{active}} and {{inactive}}. Though, unlike the Toggle Button, once this button is {{active}} it will stay that way. So radio buttons are meant to be used with a Radio Group, not by itself. |

{note} The {{type}} property is required for all buttons {note}

h3. Construction Properties

All buttons are created via the {{dmc_widget}} object and the button type is given in the properties of the constructor.

Here is a partial example:

{code:language=none|title=Button Creation via the dmc.newButton Constructor} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Button Text",

...

} {code}

Now that we have our button type chosen and our label configured, we'll go over some of the global properties available to a button.

{tip} For more ways to modify the button label, including font, size, color, etc see the main documentation [newButton Documentation]. {tip}

h2. Global Button Properties

A partial list of button properties is shown here. These are defined at the top level of the properties list (ie, not nested) and they apply to the button and all of its views.

Note that it isn't required to use the entire configuration, only the parts needed.

{code:language=none|title=Partial Button Property List} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Button Text",

-- view info
-- (discussed later)

-- button handlers
-- (discussed later)

} {code}

h2. View-Specific Global Properties

The global properties specific to a button-type are also included at the top-level of the properties list, thus these properties will apply to all views for each states of the button (eg, {{active}}/{{inactive}}/{{disabled}}).

Most properties will be the same, however, it's possible that a particular view-type (eg, {{'9-slice'}} or {{'image'}}) will need properties not required by the other views.

Pick the way in which you want to construct your views, then jump to that example:

  • [Image View|#image-view] Use single images for the button's views, either separate images or those from an image sheet
  • [Shape View|#shape-view] Use a native Corona shape (rectangle, circle, etc) to create the button's views
  • [9-Slice View|#9-slice-view] Use 9 images to create the button's views
  • [Text-only View|#text-only-view] No visual background, just a text label.

{note} The {{view}} parameter is required for all buttons except for text buttons. {note}

{anchor:image-view}

h3. Image View ({{view='image'}})

For this button view, each background is created by a single image defined by the {{file}} property or an image sheet. As only a single image is listed this will be the default image for all views. Images for the other states should be defined in the params for that view (shown later).

|| View Param || Description || | {{view='image'}} \ {{file='image_name.png'}} \ {{width=180}} \ {{height=75}} | required | | {{base_dir =''}} | optional |

h4. Image Button Example

{code:language=none|title=Properties for Image View} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Image Button",

-- view info
view='image',
width = 152,
height = 56,
file = 'asset/btn_bg_green.png',
base_dir = <corona directory reference>,

} {code}

{anchor:shape-view}

h3. Shape View ({{view='shape'}})

For this button view, each background is created by a native Corona display object and so has all of their properties. The shape type can be one of {{rect}}, {{roundedRect}}, {{circle}} or {{polygon}}. This shape type is used for all of the button views.

The following tables show the required and optional properties for each shape:

|| Rounded Rectangle View || Description || | {{view='shape'}} \ {{width=180}} \ {{height=75}} \ {{shape='roundedRect'}} \ {{corner_radius=4}} | required | | {{fill_color={0.5,0.5,0.1}}} \ {{stroke_width=2}} \ {{stroke_color={0.5,0.5,0.1}}} | optional |

|| Rectangle View || Description || | {{view='shape'}} \ {{width=180}} \ {{height=75}} \ {{shape='rect'}} | required | | {{fill_color={0.5,0.5,0.1}}} \ {{stroke_width=2}} \ {{stroke_color={0.5,0.5,0.1}}} | optional |

h4. Shape Button Example

{code:language=none|title=Properties for Shape-View Buttons} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Rounded Rect Button",

-- view info
view='shape',
shape='roundedRect',
width = 100,
height = 60,
corner_radius = 4,
fill_color={1,1,0.5,0.5},
stroke_width=4,
stroke_color={0.75,0.75,0.75,0.5},

}

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Rectangle Button",

-- view info
view='shape',
shape='rect',
width = 100,
height = 60,
fill_color={1,1,0.5,0.5},
stroke_width=4,
stroke_color={0.75,0.75,0.75,0.5},

} {code}

{anchor:9-slice-view}

h3. 9-Slice View ({{view='9-slice'}})

For this button view, each background is created by a 9 images defined by an image sheet.

|| View Param || Description || | {{view='9-slice'}} \ {{width=180}} \ {{height=75}} \ {{sheet=''}} | required | | frames={ =, ... } | required, table associating a frame name with its index inside of the image sheet |

Name of each frame:

| {{top_left}} | {{top_middle}} | {{top_right}} | {{middle_left}} | {{middle}} | {{middle_right}} | {{bottom_left}} | {{bottom_middle}} | {{bottom_right}}

h4. 9-Slice Button Example

{code:language=none|title=Properties for 9-Slice View} local Widgets = require 'dmc_widgets'

-- load button sheet info local button_info = require 'btn-blue-sheet' local button_sheet = graphics.newImageSheet( 'btn-blue-sheet.png', button_info:getSheet() )

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="9-Slice Button",

-- view info
view='9-slice',
width = 200,
height = 80,
sheet = button_sheet,
frames = {
    top_left=1,
    top_middle=2,
    top_right=3,
    middle_left=4,
    middle=5,
    middle_right=6,
    bottom_left=7,
    bottom_middle=8,
    bottom_right=9,
},

} {code}

{anchor:text-only-view}

h3. Text-only View ({{default}})

For this button view, there is no background, only the text label is drawn. However, there is still an invisible hit area defined by the button's {{width}} and {{height}}.

|| View Param || Description || | {{width=180}} \ {{height=75}} | required | | {{view='text'}} | optional |

h4. Text Button Example

{code:language=none|title=Properties for Text-only View} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push',

-- label info
label="Text-only Button",

-- view info
-- view='text', -- << optional
width = 152,
height = 56,

} {code}

h2. Button Events and Handlers

Now we'll cover how to receive events so you know when a button is pressed or released.

h3. Button Events

The event dispatched by the button has the following properties:

|| Event Property || Description || | {{target}}| A reference to the button which has the action. | | {{phase}}| The phase of the touch event -- {{target.PRESSED}}, {{target.MOVED}}, {{target.RELEASED}}. | | {{state}}| The current state of the button. Note that the state of the button will only move to another state after the button is released, though the view might change. | | {{id}}| This is only valid if an ID has been given to the button. See below. |

h4. Button ID

If you want to use the same handler for all buttons, you can set a button ID so that you can differentiate buttons inside of the handler.

{code:language=none|title=Button ID} local Widgets = require 'dmc_widgets'

local button = Widgets.newButton{ -- button info type='push', id='button-choose', -- << a button id, will be in event

...

} {code}

h3. Button Handlers

One way to receive events is by specifying function handlers. Here are the possible property names and an example:

|| View Param || Description || | {{onPress=}}| An optional function to be called when the button is pressed. The callback does not require testing for {{event.phase}} since it only honors {{'pressed'}} ({{'began'}} in CSDK) | | {{onRelease=}}| An optional function to be called when the button is released. The callback does not require testing for {{event.phase}} since it only honors {{'released'}} ({{'ended'}} in CSDK) | | {{onEvent=}}| An optional function that should only be specified in {{onPress}} and {{onRelease}} are not set. This callback function allows you to test for the {{event.phase}} |

h4. Button Handler Example

{code:language=none|title=Function Handlers Example} local Widgets = require 'dmc_widgets'

--== Button Handlers

local function onPress_handler( event ) print( 'onPress_handler: id', event.id ) local button = event.target end

local function onRelease_handler( event ) print( 'onRelease_handler: id', event.id ) local button = event.target end

local function onEvent_handler( event ) print( 'onEvent_handler: id', event.id, event.phase ) local button = event.target

if event.phase == button.PRESSED then
    -- do something for press

elseif event.phase == button.MOVED then
    -- do something for move

elseif event.phase == button.RELEASED then
    -- do something for release

end

end

local button = Widgets.newButton{ -- button info type='push', id='button-left',

-- label info
label="Text-only Button",

-- view info
-- view='text', -- << optional
width = 152,
height = 56,

-- button handlers
onPress = onRelease_handler,
onRelease = onRelease_handler,
onEvent = onEvent_handler,

} {code}

{tip} See the main documentation for additional information regarding button handlers. {tip}

h3. Button Event Listeners

If preferred, it is also possible to attach event listeners on the button.

{code:language=none|title=Example of Button Listeners} local Widgets = require 'dmc_widgets'

local function buttonEvent_handler( event ) print( 'buttonEvent_handler: id', event.id, event.phase ) local button = event.target

if event.phase == button.PRESSED then
    -- do something for press

elseif event.phase == button.MOVED then
    -- do something for move

elseif event.phase == button.RELEASED then
    -- do something for release

end

end

local button = Widgets.newButton{ -- button info type='push', id='button-left',

-- label info
label="Text-only Button",

-- view info
-- view='text', -- << optional
width = 152,
height = 56,

}

button:addEventListener( button.EVENT, buttonEvent_handler ) {code}