display.newText()

Type Function
Library display.*
Return value TextObject
Revision 2016.2886
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 (height can be zero and will then be calculated to fit the wrapped text).

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.

x, y (optional)

Numbers. Coordinates for the object's x and y center point.

width, height (optional)

Numbers. Optional parameters to specify the size of the text object. Text will be wrapped at width and be cropped at height. Set height 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.

align (optional)

String. This specifies the alignment of the text when the width is known (i.e. it either contains a newline or a width parameter is supplied). Default value is "left". Valid values are "left", "center", or "right". See the code examples below.

Syntax (Legacy)

Note that text alignment, for example "center" or "right", only works with the new 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.

x, y (required)

Numbers. Coordinates for the object's x and y center point.

width, height (optional)

Numbers. Optional arguments to enable multi-line text. Text will be wrapped at width and be cropped at height. Set height 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.

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!", 100, 200, display.contentWidth, display.contentHeight * 0.5, native.systemFont, 16 )
myText:setFillColor( 0, 0.5, 1 )
Updating the Text String Post-Creation
local myText = display.newText( "hello", 100, 200, native.systemFontBold, 12 )
myText:setFillColor( 1, 0, 0.5 )

myText.text = "Hello World!"
Multi-Line Text with Alternate Alignment
local options = 
{
    --parent = textGroup,
    text = "Hello World",     
    x = 100,
    y = 200,
    width = 128,
    font = native.systemFontBold,   
    fontSize = 18,
    align = "right"  -- alignment parameter
}

local myText = display.newText( options )
myText:setFillColor( 1, 0, 0 )
Multi-Line Text Aligned Vertically to Top
-- 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,     --required for multi-line and alignment
    font = native.systemFont,
    fontSize = 18
}
local myText1 = display.newText( options1 )
myText1:setFillColor( 1, 0, 0 )

-- Set anchor Y 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 anchor Y on object to 0 (top)
myText2.anchorY = 0
-- Align object to top alignment axis
myText2.y = topAlignAxis