1. INCLUDE THE LIBRARY
Place the library's .lua file in the directory of your project and include it with the following command (just place the name of the library within the quotes, without the ".lua" extension) :

local TextCandy = require("lib_text_candy")


This will load the library as "TextCandy" (but you are also free to use any other identifier you like). You are then ready to go and can access all the library features like this:

TextCandy.AddCharset(...)

2. LOAD A CHARACTER SET
Now load a character set. A character set (or bitmap font) is a sprite sheet where all of a font's chars are placed on. You can load and use as many different character sets as you like to (a set containing huge characters for your title screen, for example, a set with smaller chars for in-game texts and so on...). Text Candy comes with many ready-to-use character sets. You can also create your own using a tool like Zwoptex, for example (which automatically places your char images onto one texture, making optimal use of available texture space). Text Candy supports uniform and non-uniform sized chars. So, to load a character set:

TextCandy.AddCharset("MyFont1", "images/myFontImage", "ABCDEF...", 32)

The first parameter is a name identifier for this char set. You can use any unique name here. The second parameter defines the path (where to find the image texture and the sprite data file). The third parameter defines what chars are placed on the texture and in what order. The fourth parameter defines the width of the space char (the gap size between words).

The loaded font is ready to use now and you can create any number of texts using this font without any additional cost of valuable texture memory!

3. CREATE A TEXT
Once you loaded one or more fonts, creating text objects is as simple as making a cup of coffee (or even simpler, if you got one of those "modern", spacy coffee brewers available nowadays) :

local MyText = TextCandy.CreateText({
	fontName 	= "MyFont1",
	x		= 50,
	y		= 50,
	text	 	= "GET READY TO PLAY!",
	originX	 	= "CENTER",
	originY	 	= "CENTER",
	textFlow 	= "LEFT",
	wrapWidth	= 350,
	charSpacing 	= -12,
	lineSpacing	= 0,
	showOrigin 	= true
	})

As you can see here, you can specify lots of useful things for your text object, such as text-alignment, line spacing, position of the text, automatic wrapping (if wrapWidth has not been specified or set to 0, auto-wrapping will be disabled).

This function returns a handle to the created text object -which is in fact a common group and therefore can be handled like any common Corona® display object. It can be freely rotated, moved, positioned, scaled or whatever.

Important note!
If you stored the returned handle in a variable, you must set this variable to "nil" when you deleted the text object. Otherwise the garbage collector won't be able to remove this text since there is still a reference to it.

4. APPLY DEFORMATIONS
To make your texts look more fancy, you can apply various text deformation effects. After applying a deformation effect you can still change the text object to any text you like -the deformation will then be applied automatically until you remove it again.

MyText:applyDeform({
	type		= TextCandy.DEFORM_WAVE_SCALE,
	frequency	= 25,
	amplitude	= 0.5,
	minScale	= .75,
	scaleX		= false,
	scaleY		= true
	})

5. APPLY ANIMATED EFFECTS
All text objects can be automatically animated at char level. You can attach a premade effect to your text object to let Text Candy automatically fade it in and out, for example. You can also let your text fly in and out, either at once, or char by char. By using animated effects, you can create typewriter-style messages (including typing sounds!), flying chars, zooming texts and a lot more!

MyText:applyInOutTransition( {TABLE_WITH_PROPERTIES} )


Text Candy also provides an easy to use effects API to create your own in and out transition effects. As you can see in the example below, Text Candy can also delete your text automatically when the applied transition has been completed:

MyText:applyInOutTransition({
	inDelay		= 0,
	inCharDelay	= 0,
	inMode   	= "LEFT_RIGHT",
	InSound		= Snd_Beep,
	AnimateFrom	= { alpha = 0.0, time = 2000, transition = easing.linear },

	outDelay	= 3000,
	outCharDelay	= 0,
	outMode   	= "RIGHT_LEFT",
	AnimateTo	= { alpha = 0.0, time = 2000, transition = easing.linear },

	hideCharsBefore = false,
	hideCharsAfter  = false,
	startNow	= true,
	loop		= true,
	autoRemoveText  = false,
	restartOnChange	= true
	})

STEP 6: CLEAN UP
Texts can be removed at any time using:

MyText:delete()

Important note!
If you stored any text handles, you must set these references to the text objects to "nil" after you deleted text objects. Otherwise, they cannot be garbage collected and will remain in memory.


X-PRESSIVE.COM  •  TEXT CANDY FEATURES  •  QUICKSTART  •  API REFERENCE  •  HINTS & TRICKS  •  VIDEOS  •  ORDER  •  SUPPORT