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

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

h2. Widget.newButton()

Creates a button object.

h3. Syntax

{code} local Widget = require 'dmc_widgets'

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

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

h4. General Button Params

These are parameters which affect the button as a whole.

h5. type (required)

h5. height (required)

h5. width (required)

h5. id (optional)

h5. hit_width (optional)

h5. hit_height (optional)

h5. onPress (optional)

h5. onRelease (optional)

h5. onEvent (optional)

h5. value (optional)

h4. Label Params

The parameter {{label}} can be either a string or a table or nil value. If nil, then the label defaults to the empty string {{''}}.

h5. label (optional)

When {{label}} is a string, it only specifies the text of the button label, not color, size, etc. If you want to adjust other properties, then set {{label}} to a table value.

{code:language=none|title=Label param as string} Widget.newButton{ label="Press Me" } {code}

When {{label}} is specified using a table, it is intended to be used to specify many more label options.

{code:language=none|title=Label param as table} Widget.newButton{ label={ text="Press Me", color={0.3,0.3,0.3} ... } } {code}

Here are the available options for {{lable}}:

h6. label.align (optional)

{{string}}. Sets alignment of text label.

Can be one of {{'left'}}, {{'center'}}, {{'right'}}. The default is {{'center'}}.

{code:language=none} Widget.newButton{ label={ text="Press Me", align='right' } } {code}

h6. label.color (optional)

{{table}}. Sets color and transparancy of text label.

Currently table must contain value HDR RGB values, eg, {{ {0.3, 0.5, 0.75} }}.

{code:language=none} Widget.newButton{ label={ text="Press Me", color={100/255, 150/255, 10/255, 127/255} } } {code}

h6. label.font (optional)

{{string}} or {{user data}}. Sets font of text label.

Can either be one of the default Corona values {{native.systemFontBold}} or a text value from the function {{native.getFontNames()}}.

{code:language=none} Widget.newButton{ label={ text="Press Me", font = 'ArialBold-MT' } } {code}

h6. label.font_size (optional)

{{number}}. Sets size of text label in content-pixels.

{code:language=none} Widget.newButton{ label={ text="Press Me", font_size = 34 } } {code}

h6. label.margin (optional)

{{number}}. Sets margin of text label in content-pixels.

This is most useful when the alignment of the text label is set to either {{'left'}} or {{'right'}}.

{code:language=none} Widget.newButton{ label={ text="Press Me", align='right', margin = 5, } } {code}

h6. label.text (optional)

{{string}}. Sets the actual text of the label.

{code:language=none} Widget.newButton{ label={ text="Press Me", } } {code}

h6. label.x_offset (optional)

{{string}}. Sets the offset of the text label in content-pixels on the x-axis.

{code:language=none} Widget.newButton{ label={ x_offset=-3, } } {code}

h6. label.y_offset (optional)

{{string}}. Sets the offset of the text label in content-pixels on the y-axis.

{code:language=none} Widget.newButton{ label={ y_offset=7, } } {code}

h4. General View Params

These are parameters which affect the individual views {{active}}, {{inactive}}, or {{disabled}}.

h5. params.view (required)

The type of view to create

h5. params.active (optional)

Specific parameters for the {{active}} view.

h5. params.inactive (optional)

Specific parameters for the {{inactive}} view.

h5. params.disabled (optional)

Specific parameters for the {{disabled}} view.

h5. Image View Params

h6. params.file (required)

h6. params.base_dir (optional)

h5. 9-slice View Params

h6. params.sheet (required)

h6. params.frames (required)

h5. Shape View Params

h6. params.shape (required)

h6. params.fill_color (optional)

h6. params.stroke_color (optional)

h6. params.stroke_width (optional)

h6. params.corner_radius (optional)

h3. Properties

h4. button.id (read/write)

The ID of the button. A button ID must be a string or {{nil}}. There is no default button id.

The ID is also made available in a button touch-event.

{code:language=none} button.id = 'button-buy' print( button.id ) -- prints 'button-buy' {code}

h4. button.is_active (read-only)

Boolean value to determine whether the button is in the active state.

The value is {{true}} if the button is active, {{false}} if the button is inactive.

{code:language=none} print( button.is_active ) {code}

h4. button.is_enabled (read/write)

Sets the button either enabled or disabled.

Set to {{true}} if you wish to receive touch events. Set to {{false}} to disable touch events on the button. The default is {{enabled=true}}.

{code:language=none} button.is_enabled = false print( button.is_enabled ) -- prints 'false' {code}

h4. button.onEvent (write-only)

Ability to set the {{onEvent}} handler outside of the button constructor. The value must be a function reference or {{nil}}.

{code:language=none} button.onEvent = function() end {code}

h4. button.onPress (write-only)

Ability to set the {{onPress}} handler outside of the button constructor. The value must be a function reference or {{nil}}.

{code:language=none} button.onPress = function() end {code}

h4. button.onRelease (write-only)

Ability to set the {{onRelease}} handler outside of the button constructor. The value must be a function reference or {{nil}}.

{code:language=none} button.onRelease = function() end {code}

h4. button.value (read/write)

A convenience property which allows a value to be attached to the button. The value can be anything -- number, function, etc.

A button's value will also be made available in a button touch-event.

{code:language=none} button.value = 4 print( button.value ) -- prints '4' {code}

h4. button.views (read-only)

A property to access the button's various views -- {{active}}, {{inactive}}, {{disabled}}.

This can be used to modify views outside of the constructor. Available changes depends on the view-type (eg, 9-slice, shape, etc).

{code:language=none} active_view = button.views.active active.view.strokeWidth = 5 {code}

h3. Methods

h4. button:press()

Method to programmatically press the button.

Button event handlers will fire for {{onPress}}, {{onRelease}} and {{onEvent}} just as if the button was pressed manually.

{code:language=none} button:press() {code}