widget.newButton()

Type Function
Library widget.*
Return value ButtonWidget
Revision Current Public Release (2014.2189)
Keywords widget, button
See also ButtonWidget

Overview

Creates a Button object.

Syntax

widget.newButton( options )

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

id (optional)

String. An optional identification string to assign for the button. Default is widget_button.

x / y (optional)

Numbers. Coordinates for the widget's x and y center point. These values will be overridden by left and top if those values are defined.

left / top (optional)

Numbers. The left and top position where the widget will be created. If specified, these values override the x and y parameters.

isEnabled (optional)

Boolean. If false, the button will not respond to touch events. Use button:setEnabled() to enable or disable touch events on a button after creation. Default is true (button is enabled).

onPress (optional)

Listener. An optional function to be called when the button is pressed. The callback function does not require testing for event.phase since it only honors "began".

onRelease (optional)

Listener. An optional function to be called when the user releases the button (assuming the touch is still over the button). The callback function does not require testing for event.phase since it only honors "ended".

onEvent (optional)

Listener. An optional function that should only be specified if onPress and onRelease are not set. This callback function allows you to test for the event.phase of "began", "moved", or "ended".

Methods

Basic Visual Options

All buttons accept the following visual parameters in the options table, plus specific parameters for 2-Image, 2-Frame, or 9-Slice button type construction.

label (optional)

String. Text label that will appear on top of the button.

labelAlign (optional)

String. Alignment of the button label. Valid values are left, right, or center. Default is center.

labelColor (optional)

Table. Table of two RGB+A color settings, one each for the default and over states.

labelColor = { default={ 1, 1, 1 }, over={ 0, 0, 0, 0.5 } }
labelXOffset / labelYOffset (optional)

Numbers. Optional x and y offsets for the button label. For example, labelYOffset = -8 will shift the label 8 pixels up from default.

font (optional)

String. Font used for the button label. Default is native.systemFont.

fontSize (optional)

Number. Font size (in pixels) for the button label. Default is 14.

emboss (optional)

Boolean. If set to true, the button label will appear embossed (inset effect).

textOnly (optional)

Boolean. If set to true, the button will be constructed via a text object only (no background element). Default is false.

2-Image Construction

This is the easiest button to construct — just create two image files, one for the default state and another for the over state.

width / height (required)

Numbers. The width and height of the image files.

baseDir (optional)

Constant. The base directory where your custom images are located. Default is your project folder (system.ResourceDirectory).

defaultFile (required)

String. The file name of the button default image (the "un-pressed" state).

overFile (optional)

String. The file name of the button over image (the "pressed" state).

2-Frame Construction

This method uses two frames from an image sheet — one frame each for the default and over states. For this method, include a reference to the image sheet as the sheet parameter. Then specify the frame numbers from the image sheet as defaultFrame and overFrame respectively.

sheet (required)

ImageSheet. The image sheet object for the button.

defaultFrame (required)

Number. The index number for the default frame of the button (the "un-pressed" state).

overFrame (required)

Number. The index number for the over frame of the button (the "pressed" state).

9-Slice Construction

This method uses 9 slices from an image sheet which are assembled internally to create flexible-sized buttons. As indicated in the following image, the 9 slices consist of the 4 corners (red), the 2 horizontal sides (green), the 2 vertical sides (yellow), and the middle fill. Depending on the size of the button, the corners will remain at the size stated in the image sheet, but the sides and middle will stretch to fill the entire width and height. Remember that 18 slices are necessary to construct the entire button: 9 slices each for the default and over states.

width / height (required)

Numbers. The flexible width and height of the 9-slice button.

sheet (required)

ImageSheet. The image sheet object for the button.

middleFrame / middleFrameOver (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the middle fill region.

topLeftFrame / topLeftOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the top-left corner.

topMiddleFrame / topMiddleOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the top-middle side.

topRightFrame / topRightOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the top-right corner.

middleRightFrame / middleRightOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the middle-right side.

bottomRightFrame / bottomRightOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the bottom-right corner.

bottomMiddleFrame / bottomMiddleOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the bottom-middle side.

bottomLeftFrame / bottomLeftOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the bottom-left corner.

middleLeftFrame / middleLeftOverFrame (required)

Numbers. The default ("un-pressed") and over ("pressed") frames of the middle-left side.

Examples

Default
local widget = require( "widget" )

-- Function to handle button events
local function handleButtonEvent( event )

    if ( "ended" == event.phase ) then
        print( "Button was pressed and released" )
    end
end

-- Create the widget
local button1 = widget.newButton
{
    left = 100,
    top = 200,
    id = "button1",
    label = "Default",
    onEvent = handleButtonEvent
}
2-Image Construction
local widget = require( "widget" )

-- Function to handle button events
local function handleButtonEvent( event )

    if ( "ended" == event.phase ) then
        print( "Button was pressed and released" )
    end
end

local button1 = widget.newButton
{
    width = 240,
    height = 120,
    defaultFile = "buttonDefault.png",
    overFile = "buttonOver.png",
    label = "button",
    onEvent = handleButtonEvent
}

-- Change the button's label text
button1:setLabel( "2-Image" )
2-Frame Construction
local widget = require( "widget" )

-- Function to handle button events
local function handleButtonEvent( event )

    if ( "ended" == event.phase ) then
        print( "Button was pressed and released" )
    end
end

-- Image sheet options and declaration
local options = {
    width = 240,
    height = 120,
    numFrames = 2,
    sheetContentWidth = 480,
    sheetContentHeight = 120
}
local buttonSheet = graphics.newImageSheet( "buttonSheet.png", options )

-- Create the widget
local button1 = widget.newButton
{
    sheet = buttonSheet,
    defaultFrame = 1,
    overFrame = 2,
    label = "button",
    onEvent = handleButtonEvent
}

-- Change the button's label text
button1:setLabel( "2-Frame" )
9-Slice Construction
local widget = require( "widget" )

-- Function to handle button events
local function handleButtonEvent( event )

    if ( "ended" == event.phase ) then
        print( "Button was pressed and released" )
    end
end

-- Image sheet options and declaration
local options = {
    frames =
    {
        { x=0, y=0, width=21, height=21 },
        { x=21, y=0, width=198, height=21 },
        { x=219, y=0, width=21, height=21 },
        { x=0, y=21, width=21, height=78 },
        { x=21, y=21, width=198, height=78 },
        { x=219, y=21, width=21, height=78 },
        { x=0, y=99, width=21, height=21 },
        { x=21, y=99, width=198, height=21 },
        { x=219, y=99, width=21, height=21 },
        { x=240, y=0, width=21, height=21 },
        { x=261, y=0, width=198, height=21 },
        { x=459, y=0, width=21, height=21 },
        { x=240, y=21, width=21, height=78 },
        { x=261, y=21, width=198, height=78 },
        { x=459, y=21, width=21, height=78 },
        { x=240, y=99, width=21, height=21 },
        { x=261, y=99, width=198, height=21 },
        { x=459, y=99, width=21, height=21 }
    },
    sheetContentWidth = 480,
    sheetContentHeight = 120
}
local buttonSheet = graphics.newImageSheet( "buttonSheet.png", options )

-- Create the widget
local button1 = widget.newButton
{
    width = 340,
    height = 100,
    sheet = buttonSheet,
    topLeftFrame = 1,
    topMiddleFrame = 2,
    topRightFrame = 3,
    middleLeftFrame = 4,
    middleFrame = 5,
    middleRightFrame = 6,
    bottomLeftFrame = 7,
    bottomMiddleFrame = 8,
    bottomRightFrame = 9,
    topLeftOverFrame = 10,
    topMiddleOverFrame = 11,
    topRightOverFrame = 12,
    middleLeftOverFrame = 13,
    middleOverFrame = 14,
    middleRightOverFrame = 15,
    bottomLeftOverFrame = 16,
    bottomMiddleOverFrame = 17,
    bottomRightOverFrame = 18,
    label = "button"
}

-- Change the button's label text
button1:setLabel( "9-Slice" )