native.newTextField()

Type Function
Library native.*
Return value TextField
Revision Current Public Release (2014.2189)
Keywords text input, text fields, native text
See also native.newTextBox()
native.setKeyboardFocus()
object.inputType
userInput events

Overview

Creates a single-line text field for text input.

Native text fields can listen for userInput events (see example).

Native text fields can display optional placeholder text (nil by default). This can provide a "hint" as to what the user should enter in the field. If set, the placeholder string is displayed using the same style information (except the text color). The placeholder does not appear once actual text has been input into the field and it does not currently participate in determining the size of the text field.

Gotchas

Native text fields are only available in device builds, the Xcode Simulator, and in the Corona Mac Simulator.

Because native text fields 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, and cannot be inserted into display groups.

Also, they do not inherit display group properties like isVisible, x, y, rotation, and alpha. If you need to set display properties on native objects, apply them to the objects directly.

To remove a native text field from the display, use object:removeSelf().

For multiline text, see native.newTextBox().

The native.setKeyboardFocus() API is used to set and clear the keyboard used for text input.

See the TextField object reference for a complete listing of properties and methods (such as inputType, font, size, and more).

Android Sizing

Note that Android text fields have more "chrome," but they can be adjusted to look more consistent to iOS by reducing the font size and increasing the text field height. For example:

local isAndroid = "Android" == system.getInfo( "platformName" )
local inputFontSize = 18
local tHeight = 30

if ( isAndroid ) then
    inputFontSize = inputFontSize - 4
    tHeight = tHeight + 10
end

local defaultField = native.newTextField( 150, 180, 180, tHeight )
defaultField.font = native.newFont( native.systemFontBold, inputFontSize )

Syntax

native.newTextField( centerX, centerY, width, height [, listener] )
centerX, centerY (required)

Numbers. The x and y coordinates that correspond to the center of the text field.

width, height (required)

Numbers. Width and height (size) of the text field.

listener (optional)

Listener. Function to respond to keyboard events. It is recommended you do not use this argument and instead add a "userInput" event listener to the text field object. See userInput for more information.

Examples

Standard
local defaultField

local function textListener( event )

    if ( event.phase == "began" ) then

        -- user begins editing text field
        print( event.text )

    elseif ( event.phase == "ended" ) then

        -- text field loses focus

    elseif ( event.phase == "ended" or event.phase == "submitted" ) then

        -- do something with defaultField's text

    elseif ( event.phase == "editing" ) then

        print( event.newCharacters )
        print( event.oldText )
        print( event.startPosition )
        print( event.text )

    end
end

-- Create text field
defaultField = native.newTextField( 150, 150, 180, 30 )

defaultField:addEventListener( "userInput", textListener )
Numeric Input Only
local function handlerFunction( event )

    if ( event.phase == "began" ) then

        -- user begins editing text field
        print( event.text )
    end   
end

local numericField = native.newTextField( 150, 150, 220, 36 )
numericField.inputType = "number"

numericField:addEventListener( "userInput", handlerFunction )