Corona Widget Library

Current version: 0.2 (beta)

Corona's widget library provides easy-access to common user interface widgets. Please see the Known Beta Issues and Recent Changes section (towards the bottom of this page) before you use these widgets in any of your projects.

For a demonstration of basic widget use, you'll find an example project called Widget Demo in the /SampleCode/Interface/WidgetDemo folder included in every Corona SDK download.

Widget API

The following line makes all widgets available under the "widget" namespace.

    local widget = require "widget"

See the Widget Themes section for more information on how to edit/use themes.

API FUNCTION REFERENCE

In case the API names are not descriptive enough, most of the documentation pages show a screenshot of each widget.

• widget.setTheme( themeFilename ) 
• widget.newButton( [options] ) 
• widget.newSlider( [options] ) 
• widget.newScrollView( [options] ) 
• widget.newTableView( [options] ) 
• widget.newTabBar( [options] ) 
• widget.newPickerWheel( [options] ) 

Using Widget Themes

The mechanism used for 'theming' widgets is now completely different, and much more flexible. Themes are now external lua modules that you include in your project folder, which will have tables for the corresponding widgets. The individual widget tables in your theme file will have the parameters, and references to any graphics assets that are needed.

When a widget is instantiated, it first checks to see if there is a corresponding table in your theme file, with corresponding parameters. For parameters that aren't found in your theme file, the default values are used. You can override any theme parameters by setting your own parameters when you create a widget.

Please use the official themes as a reference for creating your own themes. Download links for the current "official" themes are below:

• iOS theme
• Android theme (Coming Soon)

To set a theme, please see the widget.setTheme() API reference page.

IMPORTANT NOTES:

Widgets are not normal display objects

Although widgets contain a display object via their .view property, they are not display objects in and of themselves. Because of this, when you are inserting a widget into a display group, you must insert the widget's .view property instead. Example:

    -- WRONG: Will produce error:
    someGroup:insert( myWidget )
 
    -- CORRECT:
    someGroup:insert( myWidget.view )

Widgets Must Be Removed Manually

Widgets must only be removed via display.remove() or the removeSelf() method. Most display objects are automatically removed when their parent group is removed. For example:

    local someGroup = display.newGroup()
 
    obj1 = display.newImage( "obj1.png" )
    obj2 = display.newImage( "obj2.png" )
    obj3 = display.newImage( "obj3.png" )
 
    someGroup:insert( obj1 )
    someGroup:insert( obj2 )
    someGroup:insert( obj3 )
 
    -- All three objects (obj1, obj2, & obj3) will also be removed:
    display.remove( someGroup )
    someGroup = nil

The above code shows that when you remove a display group, its children objects will also be removed. This is NOT the case with UI widgets. While the widget may no longer appear on the screen, some properties/resources are still kept in memory.

To avoid memory leaks, manually remove any UI widgets:

-- insert widget into a display group
someGroup:insert( myWidget.view )
 
-- remove widget first:
display.remove( myWidget )
myWidget = nil
 
-- then remove the display group:
display.remove( someGroup )
someGroup = nil

DO NOT rely on the removal of a parent group to remove UI widgets, doing so will likely result in unexpected behavior and/or app crashes.

Known Beta Issues

Please consider the following list of known beta issues before filing a bug report.

• Widgets must be removed manually by calling display.remove( widget ) or widget:removeSelf(); they will NOT be removed automatically when their parent group is removed (as with other display objects). 
• tableViews, scrollViews, and pickerWheels cannot be rotated as with other display objects. Right now, you'll have to destroy the widget on orientation events, and restore their state once you have recreated the widgets. 
• scrollViews do not yet have the ability to scroll horizontally (will be added in a future update). 
• scrollViews and tableViews will take up the full height of the screen, despite setting the height parameter unless the maskFile parameter is set, and your bitmap mask is set up properly, and included in your project folder. 
• tableViews and scrollViews no longer have scrollbars. Please be patient with this one, as we are working on creating scrollbars that are much better than the ones in the previous version. 
• pickerWheels do not yet do a soft-land on specific items. Selection is handled by knowing which item is within the "selection area", whether it is centered or not. 
• pickerWheels may be problematic if you use a height other than the default (we're looking into this). 
• pickerWheel columns with two or fewer items can behave a little strangely (we're looking into this). 
• If you plan on using scrollViews or tableViews with a significant amount of rows, please ensure older devices (iPod touch 3rd generation and older) are limited to 30 FPS in config.lua. Newer devices will be fine at 60 FPS. 
• Currently, you cannot move the pickerWheel widget to a different location, or the getValues() function will cease to work. We are working on fixing this in a future update. Many people like to "slide-up" their pickerWheels, so instead, we suggest you make it "fade-in" for the time being if you want some kind of animation when the pickerWheel is shown.