native.newTextBox()

Type Function
Library native.*
Return value TextBox
Revision Current Public Release (2014.2189)
Keywords text box, text input, native text
See also native.newTextField()
native.setKeyboardFocus()
userInput events

Overview

Creates a scrollable, multi-line text box for displaying text-based content. Text boxes can also be used for text input (and multi-line text input) by setting the isEditable property to true.

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

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

Gotchas

Native text boxes are only available in device builds and on the Corona Mac Simulator.

Because native text boxes 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 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 box from the display, use object:removeSelf().

For single line text, see: native.newTextField().

The native.setKeyboardFocus() API is used to set and clear the keyboard used for text input (shows and hides native device keyboard in Xcode Simulator and on-device only).

Syntax

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

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

width, height (required)

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

listener (optional)

Listener. Function to respond to keyboard events. If you choose to handle this event with a table listener, the event name is "userInput" (recommended). See userInput for more information.

Example

local function inputListener( event )
    if event.phase == "began" then

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

    elseif event.phase == "ended" then

        -- do something with textBox's text

    elseif event.phase == "editing" then

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

    end
end

local textBox = native.newTextBox( 200, 200, 280, 140 )
textBox.text = "This is line 1.\nAnd this is line2"
textBox.isEditable = true
textBox:addEventListener( "userInput", inputListener )