display.newText()

Type Function
Library display.*
Return value TextObject
Revision 2016.3002
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.

x, y (optional)

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

width, height (optional)

Numbers. If supplied, text will be wrapped at width and 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, 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 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. If supplied, text will be wrapped at width and 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 Text Post-Creation
local myText = display.newText( "hello", 100, 200, native.systemFont, 12 )
myText:setFillColor( 1, 0, 0.5 )

myText.text = "Hello World!"
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