display.newText()

Type Function
Library display.*
Return value DisplayObject
Revision 2014.2477
Keywords text, text object
See also object:setFillColor()
display.newEmbossedText()

Overview

Creates a text object. The local origin is at the center of the text. Supports multi-line text by specifying a width when the object is created (optional).

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 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. The width parameter is required if you use the align property (see below).

font (required)

String. Name of the font. Obtain an array of available fonts via native.getFontNames(). Alternatively, you can pass the following constants instead of a string:

  • native.systemFont
  • native.systemFontBold
fontSize (required)

Number. The size of the text in content-pixels.

align (optional)

String. This specifies the alignment of the text when a width parameter is supplied. Default value is "left". Valid values are "left", "center", or "right". See the code examples below.

Syntax (Legacy)

Either of the following examples are valid. Note that text alignment, for example "center" or "right", only works with the new syntax (see above).

display.newText( [parentGroup,] text, x, y, font, fontSize )
display.newText( [parentGroup,] text, x, y, [width, height,] font, fontSize )
parentGroup (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. Name of the font. Obtain an array of available fonts via native.getFontNames(). Alternatively, you can pass the following constants instead of a string:

  • native.systemFont
  • native.systemFontBold
fontSize (required)

Number. The size of the text in content-pixels.

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,     --required for multi-line and alignment
    font = native.systemFontBold,   
    fontSize = 18,
    align = "right"  --new 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,     --required for multi-line and alignment
    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