Creates a single-line textfield for text input.
Note: Native textfields are only available in device builds and on the Corona Mac Simulator.
Because native textfields are not part of the OpenGL canvas, they do not obey the Corona display object hierarchy. For example, while they can be manipulated using display object methods, they always appear above normal display objects.
Also, they do not inherit display group properties like
alpha. If you need to set display properties on native objects, apply them to the objects directly.
To remove a native textfield from the display, use
For multiline text, see
native.setKeyboardFocus API is used to set and clear the keyboard used for text input.
native.newTextField( left, top, width, height [, listener] )
numericField = native.newTextField( 50, 150, 220, 36, handlerFunction ) numericField.inputType = "number"
This example uses Lua Closures to allow using one listener for multiple Text Fields
local defaultField, numberField -- forward reference (needed for Lua closure) -- TextField Listener local function fieldHandler( getObj ) -- Use Lua closure in order to access the TextField object return function( event ) print( "TextField Object is: " .. tostring( getObj() ) ) if ( "began" == event.phase ) then -- This is the "keyboard has appeared" event elseif ( "ended" == event.phase ) then -- This event is called when the user stops editing a field: -- for example, when they touch a different field or keyboard focus goes away print( "Text entered = " .. tostring( getObj().text ) ) -- display the text entered elseif ( "submitted" == event.phase ) then -- This event occurs when the user presses the "return" key -- (if available) on the onscreen keyboard -- Hide keyboard native.setKeyboardFocus( nil ) end end -- "return function()" end -- Create our Text Field defaultField = native.newTextField( 10, 30, 180, 30, fieldHandler( function() return defaultField end ) ) -- passes the text field object numberField = native.newTextField( 10, 70, 180, 30, fieldHandler( function() return numberField end ) )
X-coordinate of the top left corner of the text field.
Y-coordinate of the top left corner of the text field.
Width of the text field.
Height of the text field.
(Optional) listener function to respond to keyboard events. If you choose to handle this event with a table listener, the event name is
"userInput". These events come with a phase attribute, as follows:
event.phase = "began"-- this is the “keyboard has appeared” event. Depending on your interface design, you may want to adjust the screen contents when the keyboard is onscreen.
event.phase = "ended"-- this event is called when the user stops editing a field: for example, when they touch a different field.
event.phase = "submitted"-- this event occurs when the user presses the “"return"” key (if available) on the onscreen keyboard.
event.phase = "editing"-- this event occurs when the user modifies text in the textbox. During this phase, several other keys are present in the event table:
event.startPosition-- number representing the position the cursor was at when the edit took place.
event.text-- string that represents the text of the textbox (to include the new edit).
event.newCharacters-- string that represents any new characters that were typed in during the event.
event.oldText-- string that represents the characters before the new characters were typed in during the event.
The created native text field object.
Other properties that affect text fields:
native.setKeyboardFocus (used to set/clear the keyboard)
Note: This API is supported in the Corona Mac Simulator but not in the Corona Windows Simulator.
Note: Native Text Field objects, like other native objects don't work in groups and are always displayed on top of regular Display Objects (vector, images, and text).
Sample Programs Using This API
Supported on operating systems and platforms for build numbers shown:
- Mac OS X:Build 2011.679
- iOS:Corona SDK 2.0
- Android:Corona SDK 2.0