Text and Fonts

From OrbEdit Wiki

Introduction to Text

Text Basics

-- Instantiate a new Sprite
local sprite = Sprite:new();
 
-- Set the Sprite's text
sprite:setText("Do you want to continue?");

Text Alignment

-- Align its text along the bottom left
sprite:setTextAlign(orb.TEXTALIGN_TYPE.BottomLeft);

Text Scaling

By default, when a Sprite's size scales up or down, the size of its text scales by the same amount. This can be controlled via the Sprite:setTextScaling() method. TextScaling is useful when creating resolution-independent menus. Often you will want to resize a menu when the screen's resolution changes so the menu shape remains relative in size to the screen, however, it does not always look good to have the menu's text scale with it. To achieve this, disable TextScaling for the Sprites that make up the menu.

-- Disable TextScaling
sprite:setTextScaling(false);
 
-- Now scale the Sprite up; notice the size of the Sprite's text is unaffected
sprite:setScale(2.0, 2.0);

Control Symbols

• |cCOLOR|: Changes the color of the text following the control symbol. COLOR must be a 6-character hex string, representing RGB. For example, |cFF0000| will change the text color to red and |c00FF00| will change the text color to green.
• |fFONT|: Changes the font of the text following the control string. FONT must be the name of a Font defined in the FontRegistry. For example, |fOldLondon40| will change the font to "OldLondon40" and |fToxica20| will change the font to "Toxica20".
• |aALIGN|: Aligns the text following the control symbol and up to the next newline by the number of pixels specified by ALIGN. For example, |a100| moves the following text (up to the next newline) to the right 100 pixels, and |a-100| moves it to the left 100 pixels.
• |n|: Causes the text to wrap to the next line. This acts just like the '\n' character does for normal text but in a platform-neutral way.

Here's how to use control symbols:

-- Set the Sprite's text to some colored words
sprite:setText("|cFF0000|Red |c00FF00|Green |c0000FF|Blue");
 
-- Switch the Sprite's font mid-sentence
sprite:setText("|fOldLondon40|This font is OldLondon, 40 point, but |fToxica20|this font is Toxica, 20 point.");
 
-- Align the second line to the left
sprite:setText("This line is aligned normally, but|n||a-400|this line is way to the left.");

Text Processing

Sprites have another text-setting method, Sprite:printText(), which does some additional processing on your text. Its signature looks like this:

• Sprite:printText(text, rate, eventId, eventId2)

Sprite:printText() displays your text typewriter-style. This means it prints your text one character at a time, separated by a tiny delay. Video games commonly use this style of printing to simulate speech. Another useful feature of Sprite:printText() is line wrapping. As your text is processed, any word that might spill outside the width of the Sprite is automatically wrapped to the next line. This is great for textboxes, as you don't have to write your text to fit within a certain width; that will be taken care of for you automatically.

If an individual word is too long to fit in the Sprite, it will overflow. Sentences are only split apart by spaces.

Sprite:printText() is used just like Sprite:setText():

-- Print some text, typewriter style
sprite:printText("Top 'o the mornin' to ya, gov'nah!");

The first Event ID parameter allows you to be notified each time a character is printed, so you can, for example, play a sound:

local id = orb.gueid();
-- Set a function that will play a tiny sound effect to accompany a character being printed
orb_set(function(text)
          Sound:new("Sounds/Blip.wav"):play();
          return -1;
        end, id);
 
-- Print some text at the default speed and pass the above Event ID
sprite:printText("Welcome to the circus of values!", nil, id);

In addition to typewriter text and line wrapping, Sprite:printText() processes call symbols, as described below. Call symbols let you make Lua calls right in the middle of your text which can be a very useful thing!

Call Symbols

Here are a few examples:

-- Print the amount of time Orb has been running
sprite:printText("You have been playing for {orbx.getTime()} seconds!");
 
-- Print the current Layer count
sprite:printText("This Level has {#orb.Layers} Layer(s).");
 
-- Call symbols can be string literals as well
sprite:printText("The last month in the year is {'December'}.");

Orb offers a handful of special functions that you can use in your call symbols. Many of these functions operate directly on the Sprite that is processing your text, for example, clear() will cause the Sprite to clear itself. Remember that call symbols are not evaluated until they are encountered during text processing.

• clear(): Clears the Sprite's text.
• lf(): Short for linefeed, pauses printing until the Sprite's advanceText() method is called.
• lfc(): Short for linefeed and clear, pauses printing until the Sprite's advanceText() method is called and then clears the Sprite's text.
• br(): Short for break, inserts a newline. Same as "|n|".
• name(): Gets the name of the Sprite.

Some more complicated examples:

-- Print two separate statements, with a 2 second pause between them
sprite:printText("One fish, two fish,{pause(2)|{clear()}|cFF0000|Red|cFFFFFF| fish, |c0000FF|blue|cFFFFFF| fish.");
 
-- Set the Sprite's name and print it using call symbols
sprite:setName("TextBox");
sprite:printText("The name of this Sprite is {name()}");  -- Prints "The name of this Sprite is TextBox"
 
-- Print some text and pause indefinitely
sprite:printText("Once upona  time,{lfc()} in a land far, far away...");  -- Wait for user input
sprite:advanceText();  -- Resume printing

The lf(), lfc(), and Sprite:advanceText() functions are very important for making your text interactive. You will likely call lfc() at the end of each "page" of text and wait for the user to press a button before calling Sprite:advanceText() to continue on to the next page.

Fonts

-- Set the Sprite's Font and text
sprite:setFont(FontRegistry:get("Toxica20"));
sprite:setText("This Font is called 'Toxica'");

As mentioned above, you can also use control symbols to set a Font in-line.

sprite:setText("|fDefault|Switching fonts is |fLilliput20|easy!");