×
A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2014.2450 | Released: 1 Oct 2014, 1:35am | What's New | Download Now

widget.newButton( )

Description:

This widget requires Corona build 2011.646 or higher.

This is a basic button that supports onPress, onRelease, onDrag events (or an onEvent to handle all phases using a single listener). If no custom graphics are passed via options, and no supporting theme has been set, button will default to using a Rounded Rect which also supports customization.

For a tutorial that walks you through button usage, please see: Adding Buttons to Your Games and Apps.

Syntax:

widget.newButton( [options] )

Example:

    local widget = require "widget"
 
    local onButtonEvent = function (event )
        if event.phase == "release" then
            print( "You pressed and released a button!" )
        end
    end
 
    local myButton = widget.newButton{
        id = "btn001",
        left = 100,
        top = 200,
        label = "Widget Button",
        width = 150, height = 28,
        cornerRadius = 8,
        onEvent = onButtonEvent
    }
 
    -- Insert button into a group:
    someGroup:insert( myButton )  -- if using older build, use: myButton.view instead
 
    -- Change the button's label text:
    myButton:setLabel( "My Button" )
 
    -- Remove the button
    display.remove( myButton )

Parameters:

widget.newButton() takes a single argument, options, which is a Lua table that accepts the following parameters:

 
id
string. This is an optional id you can use to identify the button. Default is nil.

 
left, top
numbers. The initial x/y coordinates of the button's top/left corner.

 
width, height
numbers. If using a custom image, set this to the width/height of your default/over images (or you can omit these parameters if you don't want to use content scaling). If not using images, set these to whatever you want. default values for no image are: 124(w) and 42(h).

 
label
string. The text you want to appear over the button.

 
labelColor
table. This table should hold the red, green, blue, and alpha channels for the color of your label in both its 'default' and 'over' states. Here's an example table:
{ default={ 128, 255, 96, 255 }, over={ 0 } }

 
xOffset, yOffset
numbers. Use these options to offset the label text on the x and y-axis.

 
font
string. The font you want to be used for your label. default is native.systemFont.

 
fontSize
number. The font size (in pixels) for your label text. default is 14.

 
emboss
boolean (true/false). If set to true, label text will appear to be embossed (inset effect).

 
default, over
strings. These two parameters are the image files that will represent the 'default' and 'over' (pressed) states of the button. If no images are specified, and no theme is set, the button will default to using a rounded rect.

 
baseDir
system directory. This is the base directory where your custom images are located. The default is your project folder (system.ResourceDirectory).

 
defaultColor, overColor
tables. These two tables will hold the red, green, blue, and alpha channels for the the color of your button in the 'default' and 'over' (pressed) states, IF you're not using a custom image (for Rounded Rect buttons). Here is an example table:
{ 128, 128, 128, 255 }

 
strokeColor
table. This table will hold the red, green, blue, and alpha channels for the the color of the button's border, IF you're not using a custom image (for Rounded Rect buttons). Here is an example table:
{ 128, 128, 128, 255 }

 
strokeWidth
number. This is the width of the border (stroke) of your button, IF you're not using graphics resources (for rounded rect buttons).

 
cornerRadius
number. For rounded rect buttons, this is the corner radius that controls how curved the corners are. default is 8 (pixels).

 
sheet
Requires build 2012.824 or higher. Specify the image sheet object for the widget button (instead of graphic files). Requires defaultIndex, overIndex, width, and height to also be set.

 
defaultIndex
number. Requires build 2012.824 or higher. If using image sheets, this is the frame index for the button's default (up) state. Requires sheet, overIndex, width, and height to also be set.

 
overIndex
number. Requires build 2012.824 or higher. If using image sheets, this is the frame index for the button's over (down) state. Requires sheet, defaultIndex, width, and height to also be set.

 
onPress
function. This is an optional function to be called as soon as the button is pressed. This callback function does not require you to test for an event.phase (as it only has one) and should return true.

 
onRelease
function. This is an optional function to be called as soon as the user releases the button (while their finger was still over the button). This callback function does not require you to test for an event.phase (as it only has one) and should return true.

 
onDrag
function. This is an optional function to be called while user is moving their finger on-screen, after they have already pressed the button. This callback function does not require you to test for an event.phase (as it only has one) and should return true.

 
onEvent
function. This optional function should only be set if onPress, onRelease, and onDrag are NOT set. This callback function should test for an event.phase of "press", "moved", or "release" and should return true.

 

Event Table

The onPress, onDrag, onRelease, and onEvent callbacks will call the specified listener function and pass an 'event' table as the first argument. Below are the individual keys associated with the button's event table:

 
event.name
This will always be "buttonEvent".

 
event.target
This is a reference to the actual button widget that triggered the event (not the button's .view property, which doesn't exist after build 2012.721).

 
event.phase
For onEvent listeners only, this is so you can detect which "phase" of the event is occurring. Phases include: "press", "moved", and "release".

 

Properties and Methods:

 
view

[NOTE: Deprecated as of build 2012.721—the widget is now the display object]

If you need to do something with the widget's display object (such as place the button into a display group), you need to do so using the object's .view property. Example:

    local myButton = widget.newButton{ label="My Button" }
 
    -- WRONG, will produce error:
    myGroup:insert( myButton )
 
    -- CORRECT: access display group with .view property
    myGroup:insert( myButton.view )

 
x, y
Numbers. Normally, to access display object properties of the widget, you'd do so by using the .view property of the widget. However, you can optionally use the x/y property shortcut to change the on-screen location of the widget. Example:

    -- move the button to specific location on screen:
    myButton.x = 125
    myButton.y = 300

 
button:setLabel()
To change the button's label text, use the setLabel() method. Example:

    myButton:setLabel( "New Label" )

Removing the widget:

This widget can be removed in the same manner as any other display object, by using display.remove() or the removeSelf() method. Example:

    display.remove( myButton )
    myButton = nil
 
    -- or...
 
    myButton:removeSelf()
    myButton = nil
 
    -- IMPORTANT NOTE:
    -- Don't forget to set the reference variable to nil! (as shown above)

Returns:

widget.newButton() returns a widget with it's own properties, methods, and a display object that can be accessed via its .view property. If using a build greater than 2012.721, then the .view property does not exist—the widget itself is the display object in that case.

Remarks:
Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    2011.646
  • Windows:
    2011.646
  • iOS:
    2011.646
  • Android:
    2011.646

Replies

Tom
User offline. Last seen 28 min 24 sec ago. Offline
Staff
Joined: 13 Jul 2010

All, I'm cleaning up (deleting) comments on this page since they are getting out of hand.

In the future please post questions in the forums and not on the API pages.

Thanks

BogeyBox Studio
User offline. Last seen 17 weeks 2 hours ago. Offline
Joined: 27 Jul 2011

maybe someone had already commented before the comment wipe:

someGroup:insert( myButton.view )
won't work

someGroup:insert( myButton )
works

build 2012 765

jbverschoor_bloomsix
User offline. Last seen 22 weeks 1 day ago. Offline
Joined: 7 Apr 2010

Where are:

* disabled image
* the possibility to have different font effects? (for example, I want to have a border and gradient)
* possiblity to use an image from an atlas?

ui.lua is more flexible

jbnam72
User offline. Last seen 1 year 39 weeks ago. Offline
Joined: 20 Mar 2012

Hi people,

I know we can set the label of a widget.newButton() by using the method setLabel().
However, is there any way to get the label?

tetu
User offline. Last seen 7 weeks 6 days ago. Offline
Joined: 3 May 2010

if we use a ui button we can create a function in the ui.lua file that returns the label of the button

can we do the same with the a widget button? is there a widget button lua file that we can edit?

michael37
User offline. Last seen 3 days 28 min ago. Offline
Joined: 8 Oct 2011

I missing a function to disable and enable a button, can be very usefull for working with overlay scene.

hsardaryan
User offline. Last seen 1 year 34 weeks ago. Offline
Joined: 19 Feb 2011

How to use baseDir parameter if my PNGs are located in "gui" folder?

widget.newButton{
baseDir = "gui",
default = "test.png"
}

this example doesn't work.

jonathanbeebe
User offline. Last seen 2 years 1 week ago. Offline
Alumni
Joined: 12 Apr 2011

@hsardaryan: Great question. The answer is, just as you would with any other Corona API:

widget.newButton{
    default = "gui/test.png"
}

You don't have to specify a baseDir if you're referring to system.ResourceDirectory (your project directory), because that's the default.

mark.sandell
User offline. Last seen 1 day 11 hours ago. Offline
Joined: 16 Mar 2012

Why are buttons not sending events? Is it just me? My listener only works if it doesn't have any paramters, like so:

local function onBtnRelease()

hsardaryan
User offline. Last seen 1 year 34 weeks ago. Offline
Joined: 19 Feb 2011

Please show an example with new parameters sheet, defaultIndex, overIndex

dittophantassy
User offline. Last seen 2 weeks 1 day ago. Offline
Joined: 17 May 2012

it would be useful when putting many buttons in a row with different images if you could set only height or width, and the other one would be calculated automatically to keep aspect ratio.

nicholasclayg
User offline. Last seen 2 days 34 min ago. Offline
Joined: 16 May 2011

Interesting.

Some odd behavior, but I think I got it.

I'm so used to ui.lua, guess i'll have to get used to this.

gtt
User offline. Last seen 44 weeks 5 days ago. Offline
Joined: 2 Aug 2011

Too bad newButton doesn't support Tinting.. back to a tweaked "ui" module..

Tima
User offline. Last seen 1 year 8 weeks ago. Offline
Joined: 18 Jan 2011

Why when i want to print the id in the onButtonEvent
the return isn't the id name but this:

userdata: 0107814C (change everytime I click)

With the "UI" module, I can have the id name and making conditional test with that.

roberto_99999
User offline. Last seen 1 year 36 weeks ago. Offline
Joined: 14 Jul 2012

Well, apparently you should be able to use id="mybutton" and then in the handler function you can check:
if event.id=="mybutton" then ...

But as others have pointed out, this doesn´t work. Instead you can use:

if event.target.id="mybutton" then...

which seems to work (probably a bug, so may have been corrected in later builds)..

Tima
User offline. Last seen 1 year 8 weeks ago. Offline
Joined: 18 Jan 2011

Thks !

I'm going to try right now.

cre9eve
User offline. Last seen 28 weeks 5 days ago. Offline
Joined: 18 Aug 2012

How to hide the button? When I am changing the isVisible state, it doesn't work.
Can I do it or I should use newImage instead?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
          local onPlayButtonEvent = function (event )
        if event.phase == "release" then
            playBtn.isVisible = false
        end
    end
    
        local playBtn = widget.newButton{
    id = "play",
    default = "assets/play.png",
    over = "assets/play_over.png",
    width = 80, height = 80,
    onEvent = onPlayButtonEvent
}
        playBtn.x = 320
        playBtn.y = 480
        
        
        localGroup:insert ( playBtn )

wpetzler
User offline. Last seen 30 weeks 6 days ago. Offline
Joined: 30 May 2011

Font size is incorrect (14 appears at what looks like 20px+)
Label color does not appear to work
xOffset and yOffset do not appear to work (And the default appears almost outside the button)

Add to this having the default button look terrible and required a bunch of parameters to tidy up (remove default rounded corners since the jaggies are awful, remove stroke, remove garish red colouring etc).

Tested on both simulators: OSX (2012.894) and Windows (old build). The text on OSX seems to be the correct size though.

se
User offline. Last seen 9 weeks 2 days ago. Offline
Joined: 16 Jun 2012

Is there a way to use a second line of text on a single button? Something a like a subtitle or a description field perhaps?

vfranco10
User offline. Last seen 40 weeks 4 days ago. Offline
Joined: 23 Mar 2011

I really miss the option to enable / disable a button. It would be very useful to add that property and a method modify its value.

umutdemirell
User offline. Last seen 4 days 6 hours ago. Offline
Joined: 12 Jan 2012

enable / disable feature is just what I need as vfranco10 said.

I have a locked button, for game level, I can control the release function by a variable, however I have no control on, default and over properties of button. So even the button is locked, when I press, it does not function but its default state changes to over. :(