×
A new build of Corona SDK is now available to subscribers. Not a subscriber? Subscribe now.
CoronaSDK 2014.2381 | Released: 30 Jul 2014, 6:32am | What's New | Download Now

native.newTextField()

Description:

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 isVisible, x, y and 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 object:removeSelf().

For multiline text, see native.newTextBox.

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

Syntax:

 native.newTextField( left, top, width, height [, listener] )

Example:

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 ) )

Parameters:

left
X-coordinate of the top left corner of the text field.

top
Y-coordinate of the top left corner of the text field.

width
Width of the text field.

height
Height of the text field.

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". 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.
Returns:

The created native text field object.

Remarks:

Other properties that affect text fields:

object.align
object.font
object.isSecure
object.size
object.text
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
/Interface/NativeDisplayObjects
/Interface/NativeKeyboard2

Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    Build 2011.679
  • Windows:
    --
  • iOS:
    Corona SDK 2.0
  • Android:
    Corona SDK 2.0

Replies

Tom
User offline. Last seen 39 min 25 sec ago. Offline
Staff
Joined: 13 Jul 2010

Please direct requests for changes/features to the Corona Forums. Comments here are intended for documentation correction. The documentation already states textFields are not supported in the simulator.

Thanks.

rludlamjr
User offline. Last seen 4 days 22 hours ago. Offline
Joined: 5 Sep 2011

Hi, I'm wondering if anyone can post an example of how to retrieve the text from an input field once it's been submitted? I'm sure I'm missing something basic, but none of the samples that I've looked at actually show this feature, and all the ways I've tried to use the "object.text" property seem to fail.

thanks!

jwwtaker
User offline. Last seen 7 weeks 3 days ago. Offline
Joined: 28 Apr 2010

i can access the value of the textfield using objectname.text

guruk
User offline. Last seen 16 min 5 sec ago. Offline
Joined: 9 Feb 2010

I try to get the Field ID but without luck
Not with the normal ListenFunction either with an additional AddListener

function pwfunction (event)
print ("eventphase: " .. event.phase)
print ("eventtarget: " .. event.target)
print ("eventtargetid: " .. event.target.id)
end

function pwfunction2 (event)
print ("2eventphase: " .. event.phase)
print ("2eventtarget: " .. event.target)
print ("2eventtargetid: " .. event.target.id)
end

pwField2 = native.newTextField( 50, 250, 680, 60, pwfunction )
pwField2.inputType = "default"
pwField2.text = pw2wert
pwField2.id = 2
pwField2:addEventListener("userInput",pwfunction2)

1. the normal pwfunction only gives me the event.phase
when i ask for the object.id i get an error in the console

2. when i try as mentioned a tablelistener it looks its not even called.

anyone does know how i could get my pwField2.id in any Listener (just to know what textfield came edited, began, ended
(for sure i could make two functions but ... you know :)

thx
chris

dgaedcke
User offline. Last seen 7 hours 3 min ago. Offline
Joined: 17 Apr 2010

I found table listeners to not work at all, and I found event.target (there is no ID---target IS the Object) to be un-reliable, so I use a closure. If I remember correctly, it's something like:

1
2
3
4
5
6
7
8
local myFutureFunc
 
pwField2 = native.newTextField( 50, 250, 680, 60, myFutureFunc )
 
myFutureFunc = function(event)
   local myTarget = pwField2
   ....do something here
end

guruk
User offline. Last seen 16 min 5 sec ago. Offline
Joined: 9 Feb 2010

i know there is basically no .id i just added it in the hope it would work (as in other events like oncollission etc)

put in that case as you made... its fixed on one object (pwField2) and I could not use the same function for different fields..

not prob.. right now i just call 2 different functions (with the same code each)

Tom
User offline. Last seen 39 min 25 sec ago. Offline
Staff
Joined: 13 Jul 2010

Currently this API doesn't return the target text field but you can use Lua Closures to pass along the textField object. This allows using one listener for multiple text fields (and now text boxes). I updated the API page with example code.

I'll push to add a event.target to this API's listener in future builds of Corona.

dgaedcke
User offline. Last seen 7 hours 3 min ago. Offline
Joined: 17 Apr 2010

Tom....when you guys fix the event.target issue, would you also make sure TABLE listeners are also supported as the docs imply...that just feels like a more standard way to get access to self

Thanks...you guys are doing great!

Tom
User offline. Last seen 39 min 25 sec ago. Offline
Staff
Joined: 13 Jul 2010

Where does it say in the docs that Table Listeners are supported for this native object? Table Listeners are generally used in Tap and Touch events. That is something I don't see changing.

dgaedcke
User offline. Last seen 7 hours 3 min ago. Offline
Joined: 17 Apr 2010

Tom,
You are absolutely right...it never "says" they are supported....however, the WHOLE section on events says you can choose EITHER function or table listeners and native fields are never exempted from those claims....which is why I said "implied by the docs"....

Ok, then if you are not going to change it, then please put the proper notation in the docs (ie exempting native objs from the choice of listener type)

Is it harder with native objs or is there some reason you would not make the standard approach apply??

Jefemcownage
User offline. Last seen 2 years 8 weeks ago. Offline
Joined: 29 Aug 2010

is there a way to set the border?

Jefemcownage
User offline. Last seen 2 years 8 weeks ago. Offline
Joined: 29 Aug 2010

also how do we disable them but still have them visible?

Abica
User offline. Last seen 34 weeks 5 days ago. Offline
Joined: 23 Jun 2009

Yes, I'm also in desperate need to hide the border, though from inspecting the element it still doesn't appear to be possible yet.

john11
User offline. Last seen 1 year 46 weeks ago. Offline
Joined: 13 Sep 2011

Thanks for creating the feature that allows me to see the outline of the native textfields in the Corona simulator. However, after carefully placing the fields, and then running in the iOS simulator my textFields were off-screen.

Is the corona simulator misleading me, or is there a platform-specific coordinate change I must implement in my own code.

Thank you!
John

PS: More I use corona the more I appreciate how simple it is. Great work!

weihua44
User offline. Last seen 1 year 3 weeks ago. Offline
Joined: 7 Feb 2011

Do you have the config.lua file?
Set width and height in config.lua to fixed value and then see if your textfields can work well.

john11
User offline. Last seen 1 year 46 weeks ago. Offline
Joined: 13 Sep 2011

Thanks for the reply,

This was pilot error on my part. Just a plain old bug, only exhibited on the iOS simulator, but not readily apparent because I didn't have that nice console output.

I have had to put platform specific conditional code in to cover the differences in the amount of "chrome" in the native interfaces. But I don't see any way around that.

Again, thanks for getting back to me on this.

Best Regards,
John

paul.cardwell
User offline. Last seen 17 weeks 1 day ago. Offline
Joined: 14 Dec 2011

I am new to Corona, but the below allowed me to pass obj by name (could even be by Id value):

myFieldA = native.newTextField( 50, 150, 220, 36, fieldHandler( (function() return myFieldA end), "myFieldA" ) )
myFieldA.inputType = "number"

Then the handler would look like (borrowed code from the example above):

local function fieldHandler( getObj, idStr )
... do some things...
if ( "myFieldA" == idStr ) then
... do stuff ...
end
... do the remaining things...
end

kwc_jr
User offline. Last seen 9 weeks 2 days ago. Offline
Joined: 11 Jan 2012

I am struggling with getting the text input field positioned correctly on iPhone (maybe all iOS). It seems to have a different reference point than on Android or other display objects. For instance I think this should put the input field exactly on top of the rectangle, and it does on Android:

local r=display.newRect(left, top, width, height)
r:setReferencePoint(display.TopLeftReferencePoint)
r.x = left
r.y = top

local t=native.newTextField(left, top, width, height, function...
t:setReferencePoint(display.TopLeftReferencePoint)
t.x = left
t.y = top

On the iPhone I am testing with (iPhone3) they are aligned horizontally but not vertically. The input field sits exactly above the rectangle - like it has a reference point of BottomLeft.

Any ideas? Thanks

kwc_jr
User offline. Last seen 9 weeks 2 days ago. Offline
Joined: 11 Jan 2012

Ok, finally got back to this. To answer my own question, read the darn documentaion. They clearly say that the textField is positioned on the screen, not in the displayGroup. My displayGroup just happened to be vertically positioned exactly one textField height down from the top of the screen - it was positioned exactly where I told it to be. Quick conversion from group coordinates to screen coordinates and now the input field is where it belongs!

dutchottie
User offline. Last seen 9 weeks 6 days ago. Offline
Joined: 1 Feb 2012

I was wondering if it's needed to remove the listener after you're done with the input field?
If so, how does one access it to :removeSelf() and = nil?

Thanks!

Dutchottie

AlanPlantPot
User offline. Last seen 1 week 2 days ago. Offline
Joined: 16 Aug 2011

Since updating my version of Corona I'm now getting a message when using newTextField's:

"WARNING: The 'listener' argument to native.newTextField( left, top, width, height [, listener] ) is deprecated. Call the object method o:addEventListener( 'userInput', listener ) instead."

Could the example text be updated to show this? Here's my code if that's helpful.

local function fieldHandler( event )

myText.text = tostring(event.text )--update a text field as we type

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

elseif ( "ended" == event.phase ) then
myString = tostring(event.text )--store text if needed
native.setKeyboardFocus( nil )

elseif ( "submitted" == event.phase ) then
myString = tostring(event.text );
-- Hide keyboard
native.setKeyboardFocus( nil )
end
end

defaultField = native.newTextField( 10, 70, 180, 30)
defaultField:addEventListener("userInput", fieldHandler)

dgaedcke
User offline. Last seen 7 hours 3 min ago. Offline
Joined: 17 Apr 2010

And when you update the docs, please clarify if TABLE listeners are now supported (ie the "listener" would get called with TWO (obj, event) params, instead of the former ONE (event) syntax)

I remember quite a while ago, Tom said that native fields did not support table, listeners. Has this changed?

Tom
User offline. Last seen 39 min 25 sec ago. Offline
Staff
Joined: 13 Jul 2010

The comment section for this API has been closed. Please continue the discussion on the Corona forums. http://developer.anscamobile.com/forum/2012/04/02/nativenewtextfield