Posted on by

Here’s the new syntax:

display.newText( string, x, y, [w, h,] font, size )

To enable the text-wrapping capabilities, you must specify the new w and h arguments, which correspond to the width and height (in pixels) of your invisible text area.

Here’s a few examples to demonstrate the new functionality:

Example 1: Support for the newline (n) character:

local textMessage = display.newText( "Hello Corona User!nHope you're having a great day.", 25, 25, "Helvetica", 18 )
textMessage:setTextColor( 0 )

The above code should show this in the simulator screen:

Hello Corona User!

Hope you're having a great day.

Example 2: Text wrapping

local multiText = display.newText( "This text should be wrapped according to the specified width.", 25, 25, 175, 400, "Helvetica", 18 )
multiText:setTextColor( 0 )

The above example will begin wrapping text once it reaches the 175 pixel width we set when calling display.newText().

Important Notes

  • Currently, these changes are only available on the Simulator and on iOS devices (not on Android yet).
  • Previously, the newline (n) character was supported in the simulator but not on any devices.
  • If text goes beyond the specified h (height) parameter, text will be cropped, so be mindful of that.
  • Fonts vary slightly, for example, line spacing may be different in the simulator vs. on device, and native.systemFont on the Mac is different than in iOS—so be sure to do extensive on-device testing as you go.

Remember, at the moment, this feature is only available through the Corona Daily Builds, which you’ll have access to as soon as you become a subscriber, so what are you waiting for?

And speaking of Daily Builds, remember the new homescreen you read about the other day? The ‘New Project’ button, which was previously non-functional, is now working (since build 638)—so go try it out!

Posted by . Thanks for reading...

50 Responses to “Multiple Lines in display.newText()”

  1. W2MD

    This is awesome! It’s so simple but so useful! Does this mean we are going to have multi-line text on buttons for the widget api soon too?!

  2. Thy Toeung

    Is it possible to not specify the height parameter if we want the text to wrap, but don’t care about the length?

  3. Jason Schroeder App Designs

    Woot! Thanks, Ansca!

    I hate to rain on the multi-line parade by asking for new features, but if it’s possible to work out some sort of “isScrollable” parameter into the new-and-improved display.newText, that would be amazing!

    For example, if I have a very long string of text that cannot fit within the defined height, if “isScrollable” was set to “YES”, then the user could scroll the text up and down within the boundaries of the newText display object.

    But don’t mistake this request for ingratitude – you guys are improving the SDK daily, and I know all of us Corona devs are grateful!

  4. lano78

    What you’re asking for is pretty much like textbox?

    I would suggest that the height is set by the amount of text that is being rendered or have a define this feature as

    display.newParagraph(“Lot’s of text”, x, y, width, alignment, font, size)
    and in this case the hight is set by how much text is rendered to avoid clipping.

    or here’s another suggestion;

    widget.newParagraph (title = “String”, x, y, font, size, color = {r,g,b,a}, {paragraph = “lot’s of text”, x, y, width, font, size, color = {r,g,b,a}} )

    and in this case the paragraph height is the same as previous example.

  5. Jason Schroeder App Designs

    @lano78: D’oh! You are right. I tend to avoid native elements when I can because they can’t be placed in display groups, so I hadn’t really checked out the native.newTextBox API. I have now, and it may come in handy. Thanks!

    However, since these new and improved text fields can be placed in groups (for better-looking apps!), I’d still love to see some sort of scrolling parameter. And +1 for alignment support and auto-height, per lano78’s comment.

  6. Naveen

    Any chance for getting alignment? It looks pretty bad sometimes when it cuts off a line and starts a new one because a word is too long to fit on the current line.

  7. Ruben

    This is a great feature, but as lano78 pointed out, in case you don’t define the height parameter, it should be set by the amount of text entered.

    That would allow newText to be used efficiently to make long paragraphs (especially in combo with widget.newScrollView)

  8. Harmik

    Thank you!
    Of course I just spent good half of previous day setting all the texts up in the app.
    This would have probably saved most of that time :p

  9. Lano78

    I’m inserting my “paragraphs” into a scrollView and it look much better than textboxes. There is another option for paragraphs, get CrawlspaceLib. It got a very handy paragraph feature but make sure you remove the text scale part when using it with widgets or else youre in for a big surprise…

  10. Vivendo

    Great new feature! Can we please have one more parameter for text justification (left/center/right)? This would make this feature even more useful. I am assuming that for now the text is left-justified?

  11. vweb20

    Can you make it behave like util.wrappedText (widely used util library)? That seems to handle any length text without truncating it. Then we can create this type of display object and add it to scrollview. That way, if the text is long, it scrolls correctly.

    It might be a better idea to create Corona approved libraries, instead of changing the core API for such things. (Currently the only option is to find out these libraries from other shared code available on the web). Maybe open source it so people can contribute to it, but corona can keep them in one place.

  12. Steve B

    Thank you so much. This is great.

    +1 for alignment support and auto-height and for adding this for Android as soon as that is practical, per other’s comments. You folks rock!

  13. Walter

    Thanks for the feedback!

    Auto height should be available in the next daily build (640 or after). Pass 0 for the height argument and the height will change according to amount of text — except it will *not* exceed the maximum texture height for the device.

    Coming to Android soon.

  14. Mario

    OOOOKKKK, not sure what the heck is going on, but I have the latest build (640) and none of these examples are wrapping anything? Hell, the text doesn’t even show up for me unless I delete the

    multiText:setTextColor( 0 )




  15. Mario

    Wait…I meant build 639! I’m not time travelling here…..yet. ;)

    But yeah, still now text wrapping love in my simulator…on windows….did I miss another important notes section?

  16. Joshua Quick


    The simulator for Windows doesn’t have text wrapping support yet because the Windows developer (that would be me) was too busy adding this feature to Android… which you’ll find in daily build 640. :)

  17. Alex

    Mario, the multiText:SetTextColor(0) sets the text color to black, that’s why you are not seeing it (just replace to (255) and you will get it).

    Jonathan/Walter, I couldn’t make the n work at all (copying and paste the above examples). Am I missing something on the newline character?

    • bp

      In the instructions above there is a back-slash missing from the ‘n’ for some reason. Try “\n” as the newline character.

  18. Stefan

    Am I correct that libraries such a CrawlspaceLib will need to be updated to accommodate these changes?

  19. Pop

    Awesome, been waiting for this for a while.

    One small request: could there be an optional “line spacing/height” parameter? It’d be great to be able to force the exact same layout across all devices – and also to be able to control the spacing for stylistic purposes.

    • Jules

      I’m going mad trying to find a way to set the line spacing/height. Did you get anywhere with this?

  20. Dave Haynes

    This is excellent. I’m just waiting for the dust to settle on this feature before I start using it, but it will make things so much simpler for me.

  21. Harmik

    This has been a great help, thanks one more time :)

    I found that the text width doesn’t scale with other content on different devices. So if it’s set to certain width in pixels the same width will be used also on higher resolution screens making the textfield really small.

    Should I place some device check and alter the width for different devices (namely normal and retina displays) or is there a better way to accomplish this?

  22. Dan

    The new display.newText() routine can wrap long stings to create a multi-line string which can effectively be used as a paragraph.

    But I couldn’t find a way to space succeeding paragraphs below the preceding paragraph because there’s no way to get the y coordinate of the bottom of the preceding multi-line wrapped string tat was created by display.newText(). I tried using object.contentHeight() but that returns a fixed value which is the 5th (height) argument in the call to display.newText().

    Since there’s no telling how high the line-wrapped multi-line string will be in advance, what is required is a dynamic height value, generated by display.newText() depending on how many lines it created. I found that using 0 as the 5th argument causes display.newText() to calculate how much vertical space it needs to create the new multi-line string. Then object.contentHeight() will return the height dynamically. This return value can be used to properly space succeeding paragraphs vertically.

    The only problem is that display.newText() outputs a series of warning messages to the terminal, causing a bit of a slowdown. It’d be nice to have an argument that turns these warning messages off.

    FYI the messages are:

    “WARNING: Due to system limitations, display.newText() height is going to be increased to nearest multiple of 4: 0 ===> 24.”

  23. lano78

    There’s a little issue with this feature on Retina devices that the text is only half size on both simulator and device.

    For those of you who want line breaks just use nn to get that Paragraph look in your texts.

    I also seem to have an issue with setting different device fonts and none worked, I tried anything from Helvetica, Verdana-Italic, Zapfino etc.

  24. HH

    Hi – I’ve just started using Corona so excuse me if this is a stupid question…

    I’m using the new fixed width text item for an input box, and I want to add a cursor to show where your next keypress will appear (not using Native UI stuff for this as I need to react to each keypress as it happens).

    Previously, when it was just one line long, I was using the text item width and height to show me where the end of my text was, so I could position a cursor there. Now, of course, they’re fixed, so that won’t work.

    Is there an way to find the x,y coordinate of the end point of my new, multiline text? Or to find out how many lines the text has wrapped to so I can work it out?


  25. HH

    Ah… I see Dan asks the same thing, above. Another question – trying this on an Android device (daily build 645) – I’m finding the y position for my text is too high when displayed. The amount ‘out’ it is seems to be relative to the fixed height of the text box (ie the bigger the box, the more out the ‘y’ is).

    It’s fine in the simulator, and also on iPhone hardware.

    Anyone else found this?


  26. HH

    I guess I should try a custom font rather than relying on the system ones, so I get a consistent result?

  27. finefin

    nice. n works, at least if you use witdh/height parameters for your text field.
    the next nice thing would be t for tabulators…

  28. Luis Galhardo

    Lots of “WARNING: Due to system limitations, display.newText() height is going to be increased to nearest multiple of 4: 0 ===> 24.”

    Performance slows down…lots of simulator slow refreshes and transition effects stop working or perform real bad

  29. Ziao

    I agree, the terminal spam has to be fixed, it causes slowdown when creating a lot of texts on the device itself. At the very least turn it off when height and width are set to 0.

  30. Pedro Valentini


    I’m receiving this warn too:
    WARNING: Due to system limitations, display.newText() height is going to be increased to nearest multiple of 4: 0 ===> 896

    But I’m with a terrible bug in device that sometimes, with long text I get a BLACK text area in my iPod Touch 4.

    This is a bug or a limitation of the device? What is the solution to remove this limitation?

    Thank you

    My code:

    pageText = display.newText( currentScene.text, 0, 20, 280, 0, native.systemFont, 16 )
    pageText:setTextColor(0, 0, 0)
    pageText:setReferencePoint( display.TopLeftReferencePoint )
    pageText.x = 20
    pageText.y = 20
    scroll:insert( pageText )

    • Mitaten

      Did you manage to fix that issue? I’m receiving lots of complaints by users regarding this bug but I can’t seem to reproduce it myself..

    • Sabir Ahmed

      Hi Pedro,
      In coronaSDK display text you can display maximum 59942 character. If your text is exceed this limit, It will became BLACK text area. So you need to break your long text and then display.

    • kirkilj

      Yesterday, I tried to eliminate the same spew of warnings you mentioned. I get them even if I ensure that the values are multiples of 4 by running those variables through a function to round up to the nearest multiple of 4. It injects lots of noise into my console output when trying to debug.

    • Craig

      Not sure if you’re aware of the simple solution.
      When you first create the textbox, set the height to 0. That is it, the textbox will automatically resize the height but lock the width.

  31. Peter

    Has the code been changed? This no longer works. Neither does \n, Please help Thanks you.

  32. Sabir

    I am getting the bug with long text I get a BLACK text area in my simulator as well as device.
    How do I fix this problem?


Leave a Reply

  • (Will Not Be Published)