display.newText()

Type Function
Library display.*
Return value TextObject
Revision Release 2022.3683
Keywords text, text object
See also Using Custom Fonts (guide)
Display Objects (guide)
display.newEmbossedText()
object:setFillColor()

Overview

Creates a text object. The local origin is at the center of the text and the anchor point is initialized to this local origin.

Text is wrapped either at newlines or by specifying a width and height when the object is created.

By default, the text color is white ( 1, 1, 1 ). See object:setFillColor() for more information.

Syntax

display.newText( options )

This function takes a single argument, options, which is a table that accepts the following parameters:

parent (optional)

GroupObject. Display group in which to insert the text object.

text (required)

String. The text to display. Similarly, to change the displayed text for a text object after it has been created, set the object.text property.

x (optional)

Number. The x coordinate of the text object.

y (optional)

Number. The y coordinate of the text object.

width (optional)

Number. If supplied, text will be wrapped at this width.

height (optional)

Number. If supplied, text will be cropped at this height. Set this to 0 and the text box height will adjust to the amount of text, but never exceed the maximum texture height for the device.

font (required)

String, Userdata, or Constant. This can be one of the following:

fontSize (optional)

Number. The size of the text in Corona content points. The system's default font size will be used if this parameter is omitted or if it's set to nil or 0.

Important

To change the font size of a text object after it has been created, set the object.size property, not object.fontSize.

align (optional)

String. This specifies the alignment of the text when the width is known, meaning it either contains a newline or the width parameter is supplied. Default value is "left". Valid values are "left", "center", or "right".

Syntax (Legacy)

Note that text alignment, for example "center" or "right", only works with the modern syntax (see above).

display.newText( [parent,] text, x, y [, width, height], font [, fontSize] )
parent (optional)

GroupObject. Display group in which to insert the text object.

text (required)

String. The text to display. Similarly, to change the displayed text for a text object after it has been created, set the object.text property.

x (required)

Number. The x coordinate of the text object.

y (required)

Number. The y coordinate of the text object.

width (optional)

Number. If supplied, text will be wrapped at this width.

height (optional)

Number. If supplied, text will be cropped at this height. Set this to 0 and the text box height will adjust to the amount of text, but never exceed the maximum texture height for the device.

font (required)

String, Userdata, or Constant. This can be one of the following:

fontSize (optional)

Number. The size of the text in Corona content points. The system's default font size will be used if this parameter is omitted or if it's set to nil or 0.

Important

To change the font size of a text object after it has been created, set the object.size property, not object.fontSize.

Gotchas

Examples

Single-Line Text
local myText = display.newText( "Hello World!", 100, 200, native.systemFont, 16 )
myText:setFillColor( 1, 0, 0 )
Multi-Line Text
local myText = display.newText( "Hello World!", 30, 100, 240, 300, native.systemFont, 16 )
myText:setFillColor( 0, 0.5, 1 )
Updating Text Post-Creation
local myText = display.newText( "hello", 100, 200, native.systemFont, 12 )
myText:setFillColor( 1, 0, 0.5 )

-- Change the displayed text
myText.text = "Hello World!"

-- Increase the font size
myText.size = 16
Multi-Line Text Right-Aligned
local options = 
{
    text = "Hello World",     
    x = 100,
    y = 200,
    width = 128,
    font = native.systemFont,   
    fontSize = 18,
    align = "right"  -- Alignment parameter
}

local myText = display.newText( options )
myText:setFillColor( 1, 0, 0 )
Multi-Line Text Top-Aligned
-- Variable for top alignment axis
local topAlignAxis = 200

-- Create first multi-line text object
local options1 = 
{
    text = "The quick brown fox jumped over the lazy dog.",
    x = 90,
    width = 120,
    font = native.systemFont,
    fontSize = 18
}
local myText1 = display.newText( options1 )
myText1:setFillColor( 1, 0, 0 )

-- Set vertical anchor on object to 0 (top)
myText1.anchorY = 0
-- Align object to top alignment axis
myText1.y = topAlignAxis

-- Create second multi-line text object
local options2 = 
{
    text = "The quick brown fox jumped over the lazy dog, then jumped back again.",
    x = 230,
    width = 120,
    font = native.systemFont,
    fontSize = 18
}
local myText2 = display.newText( options2 )
myText2:setFillColor( 0.6, 0.4, 0.8 )

-- Set vertical anchor on object to 0 (top)
myText2.anchorY = 0
-- Align object to top alignment axis
myText2.y = topAlignAxis