Textblox.lua

textblox is a custom text and message box framework for LunaLua.

Installation
The latest version of this API is included in SMBX2.

Setup
To enable the textblox library for a specific level, add this line to lunadll.lua: This will load the textblox API.

Fonts
A core element of textblox is the Font class, which allows users to create custom fonts for use with the library. Font objects can reference either one of SMBX's built-in fonts or a custom monospaced spritefont.

To create your own Font, call textblox.Font (fonttype, properties). The first argument is the font type constant (textblox.FONTTYPE_DEFAULT or textblox.FONTTYPE_SPRITE); if DEFAULT is used for the first argument, the second argument is SMBX font number, but if SPRITE is used for the first argument, the second is a table of named arguments.

Example code:

textblox comes with various premade fonts which are stored in textblox.defaultSpritefont[i][k], where i is the font and k is the variation.

Displaying text
Once you've selected or created your font of choice, you can display text using the font via the function textblox.printExt (text, properties). The first argument is the text string, the second is a table of named arguments.

Example code:

Results:

Of note, textblox.printExt  returns the following four values: the total width in pixels, total height, number of line breaks and finally a table containing the width of each line. While these can be used to help with positioning in menus, special effects or even custom message boxes, the Text Block class is generally recommended for more complex needs as it contains all the functionality of printed text and more.

Text Blocks
Text Blocks are, as their name suggests, objects that store blocks of text. Unlike the print function, Text Blocks are instantiated once and continue to exist until they are either closed by the user or close themselves (if they're configured to do so). Text Blocks have their own window graphics and gradually reveal their text through a typewriter effect, so they can serve as useful message boxes for dialogue or player notifications.

Text Blocks are created with textblox.Block (x,y, textStr, properties).

Example code:

Additional Functions
The following functions can be used to further control Text Blocks:

Commands
textblox uses a markup language similar to HTML for special in-text commands. The following commands can be used to insert special characters and control the appearance of text.

'IMPORTANT:''  and  must be used for displaying the corresponding symbols. Trying to use the symbols themselves will break the command processing for that string.'''

These commands are for triggering effects and controlling the timing of Text Blocks:

Overriding SMBX messages
textblox is capable of overriding the built-in SMBX message box. When textblox.overrideMessageBox is set to true, all SMBX message boxes are replaced with Text Block objects using the table of named arguments stored in textblox.overrideProps. By changing the properties stored in textblox.overrideProps, you can thus customize the SMBX message box.