native.newTextBox()

Overview

Creates a scrollable, multi-line TextBox object for text input. For single-line text input, see native.newTextField().

By default, the content of text boxes is not editable. Set the object.isEditable property to true to make the content editable.

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

Gotchas

• Use "\n" to start text on a new line. Text will automatically wrap to the next line if it’s too long.

• Native text boxes are not part of the OpenGL canvas and do not obey the display object hierarchy, so they will always appear in front of normal display objects including images, text, and vector objects. However, native text boxes can be “inserted” (object:insert()) into Corona display groups and they will move in unison with that group.

• Presentation of native controls in the Corona Simulator can only be an approximation of the actual device. Always test on a device and assume that the behavior/appearance on devices is correct.

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

• The native.setKeyboardFocus() API is used to show and hide the keyboard used for text input (applies to device and Xcode Simulator only).

• On Android, due to the fact that Corona runs on multiple threads, getting the .text value of a TextBox immediately after setting it will not return the correct value. This action should be performed following a short timer or during the next time step.

Syntax

native.newTextBox( x, y, width, height )

Properties / Methods

See the TextBox documentation for a list of functions and properties.

Events

See the userInput event documentation for properties related to various TextBox object events.

Example

local defaultBox

local function textListener( event )

    if ( event.phase == "began" ) then
        -- User begins editing "defaultBox"

    elseif ( event.phase == "ended" or event.phase == "submitted" ) then
        -- Output resulting text from "defaultBox"
        print( event.target.text )

    elseif ( event.phase == "editing" ) then
        print( event.newCharacters )
        print( event.oldText )
        print( event.startPosition )
        print( event.text )
    end
end

-- Create text box
defaultBox = native.newTextBox( 200, 200, 280, 140 )
defaultBox.text = "This is line 1.\nAnd this is line2"
defaultBox.isEditable = true
defaultBox:addEventListener( "userInput", textListener )