Sprite Candy text objects are very customizable: you can set an auto-wrapping width, text-flow direction, screen alignment and more. Like all objects, texts can be colorized, too. To save texture memory, you can load a white colored font only and colorize each text object individually. Of course you can add shadows, a colored background or borders to text objects, too. The included Font Candy Studio Editor has been especially designed for use with Sprite Candy and makes it very easy to create and export nice looking font textures.

NOTE:

Font_Handle% = HUD_LoadFont ( textureFile$, dataFile$, [textureMode%], [maskR%],  [maskG%],  [maskB%]  )

Before you can create text objects, you have to load one ore more fonts into memory. This command will load a font texture and its metrics file (as exported from Font Candy Studio) and return a handle to this font. Once a font or texture has been loaded, it can be used on as many layers and as many times as you like, there's no reloading neccessary.

textureFile$
Path and file name of a font texture (exported by Font Candy Studio).

dataFile$
Path and file name of a char metrics file (usually a .bin file, exported together with the font texture image).

textureMode%
Optional texture settings to be applied to the texture loaded:

Texture_Handle% =  HUD_GetTextureHandle (  Font_Handle%  )

Sprite Candy commands like HUD_LoadImageResource or HUD_LoadFont do return internal Sprite Candy ID's, not Blitz texture handles. If you want to modify a texture directly, you can use this command to get the Blitz texture handle of a loaded image or font.

Font_Handle%
The handle of a font loaded with HUD_LoadFont( ).

Example:

; CREATE A HUD, LOAD A FONT (ONCE ONLY)
HUD1%   = HUD_Create      (Cam)
Font1%  = HUD_LoadFont    ("font.bmp","font.dat", 4)

; THEN CREATE A LAYER USING THAT FONT:
Layer1% = HUD_CreateLayer (HUD1, Font1)

; CREATE AS MANY TEXTS ON IT AS YOU LIKE:
Text1%  = HUD_CreateText  (Layer1, 0,0, "SAMPLE TEXT",  "LEFT", 0, "CENTER","BOTTOM")
Text2%  = HUD_CreateText  (Layer1, 0,0, "ANOTHER TEXT", "LEFT", 0, "CENTER","TOP+50")

Text_Handle% =  HUD_CreateText (  Layer_Handle%,  x%,  y%,  text$,  [textFlow$],  [wrapWidth%],  [xAlign$],  [yAlign$],  [zOrder%],  )

This command creates a text object on the specified layer. A font texture must have been attached to this layer first. Most of a text object's parameters can be changed and updated on-the-fly.

Layer_Handle%
The handle of a layer as created with HUD_CreateLayer( ). A loaded font must have been attached to this layer.

x% , y%
The screen x- and y-postion where the created text should be placed, where x may range between 0 (left) and the screen width and y may range between 0 (top) and the height of the screen. These parameters will be ignored, when xAlign$ or yAlign$ have been set (see below).

text$
A string to print. All chars of this string must be contained on the font texture specified with FontID. You can use chr(13) or | (upright slash) to force a line break anywhere inside the string.

textFlow$

Font_Handle% =  HUD_GetFontID (  Text_Handle%  )

This command returns the ID (Sprite Candy handle) of the font used by the specified text object, so you can check what font has been used to create it.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

HUD_SetText (  Text_Handle%,  text$  )

This command changes the text of a text object. You can use it at any time.

Handle%
The handle of a text object created with HUD_CreateText( )

text$
A string to print. All chars of this string must be contained on the font texture. You can use chr(13) or | (upright slash) to force a line break anywhere inside the string.

text$ =  HUD_GetText (  Text_Handle%  )

Returns the current text of a text object.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

HUD_SetTextFlow (  Text_Handle%,  textFlow$  )

This command changes the text-flow direction of a text object at any time.

NOTE: By default, an object's origin (center point) is placed at the center (middle) of an object. There are two exceptions: when you set the text-flow of a text object to "LEFT", the origin is placed on the left side of the object, when text-flow is set to "RIGHT", the origin is placed on the right side of the object.

ObjectHandle%
The handle of a text object created with HUD_CreateText( )

textFlow$

textFlow$ =  HUD_GetTextFlow (  Text_Handle%  )

Returns the current text-flow (text-alignment) of a text object. Possible values are:

HUD_SetWrapWidth (  Text_Handle%,  wrapWidth%  )

This command will set the maximum width (wrapping width) of a text object. You can use it at any time. When a text exceeds the given width, it will be wrapped automatically. You can disable the auto-wrapping by setting a text's wrapping width to 0.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

wrapWidth%
The maximum width of the text (in pixels). Using 0 disables text wrapping for this text. You can always force new lines (line breaks) by using chr(13) or | (upright slash) anywhere inside the text.

wrapWidth% =  HUD_GetWrapWidth (  Text_Handle%  )

Returns the wrapping width of the specified text object.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

HUD_SetCharSpacing (  Text_Handle%,  spacing%  )

This command modifies the character spacing (also called 'kerning') of a text object.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

spacing%
The specified value will be added to the default character spacing of the text object. Default value is '0' (the normal character spacing as saved with the font's metrics file will be used then). You can specify negative and positive values, where negative values will shrink the spacing between the chars and positive values will enlarge the spacing.

spacing% =  HUD_GetCharSpacing (  Text_Handle%  )

Returns the character spacing value as specified with HUD_SetCharSpacing.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

num_lines% =  HUD_CountLines (  Text_Handle%  )

Returns the current number of lines of a text object (after wrapping, for example).

Text_Handle%
The handle of a text object created with HUD_CreateText( )

width% =  HUD_GetTextWidth (  Font_Handle%,  text$  )

Returns the width that a given text would use on screen with a specified font.

Font_Handle%
The handle of a font loaded with HUD_LoadFont( ).

text$
A string containing any text (single line only, no line breaks).

charWidth% =  HUD_GetCharWidth (  Font_Handle%,  char$  )

Returns the width of char when using a specified font.

Font_Handle%
The retrieved handle of a font loaded with HUD_LoadFont( ).

text$
A text string containing a single char.

lineHeight% =  HUD_GetLineHeight (  Font_Handle%  )

Returns the line height (vertical char spacing) of a loaded font. This is usually the same for all characters of a font.

Font_Handle%
The retrieved handle of a font loaded with HUD_LoadFont( ).

numberOfLines% =  HUD_GetLines (  Font_Handle%,  text$,  wrapWidth%  )

Returns the number of lines a text would have on screen when using the specified font and wrapping width.

Font_Handle%
The retrieved handle of a font loaded with HUD_LoadFont( ).

text$
Any text string.

wrapWidth%
The maximum width of the text.

HUD_SetTextLineColor (  Text_Handle%,  line_number%,  R%, G%, B%,  [Alpha#]  )

Using this command, you can easily colorize a specified line of a text. This command uses HUD_SetVertexColor. This effect will disappear if the text object is altered again (changing its text, for example). In this case you'll have to apply it again.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

line_number%
The line number of the text's line that should be colorized, starting with 1 (first line).

R%, G%, B%
Specify a color here using a red, green and blue color value (0-255 each).

Alpha#
Specifies the alpha value (transparency). 0.0 means completely transparent (invisible), 1.0 is fully opaque.

HUD_SetScrollText (  Text_Handle%,  text$,  start_line%,  number_lines%  )

Similar to HUD_SetText( ), but this command can be used to show certain lines of a text only. Use this command if you want to create a scrollable text. This command takes a string, containing the complete text you want to use with the text object, and displays the wanted lines only. You can define a line number to start and the amount of lines that should be visible. All other lines of the specified text will not be shown. The specified text will be wrapped automatically, using the text object's current wrap width.

Text_Handle%
The handle of a text object created with HUD_CreateText( )

text$
A text string that contains the complete text you want to use. Only the specified lines will be shown.

start_line% , number_lines%
Specifies the number of lines that will be visible and the line to start with. If start_line has been set to 1, for example, and number_lines to 5, only the lines 1 to 5 of the complete text will be shown. You can scroll a text by using this command at any time -simply increase or decrease the start line number.
The minimum value that can be used for start_line is 1 (will start at the first line).

lines_scrolled% =  HUD_GetCurrentScroll (  Text_Handle%  )

If you use HUD_SetScrollText( ) to fill a text object, you can use this command to check what line is currently the top-most line that is visible. If you get a value of 1, for example, you know that the first line is still visible (the text has not been scrolled down then). A value of 2 will mean that the second line of the complete text is currently displayed as the topmost line and so on...

Text_Handle%
The handle of a text object that has been filled using HUD_SetScrollText( )

max_lines_to_scroll% =  HUD_GetMaxScroll (  Text_Handle%  )

If you use HUD_SetScrollText( ) to fill a text object, you can use this command to find out, how many lines a text can be scrolled down until the last line has been reached. You know that a text has been scrolled down completely, for example, if HUD_GetMaxScroll( ) and HUD_GetCurrentScroll( ) are the same.

Text_Handle%
The handle of a text object that has been filled using HUD_SetScrollText( )

HUD_AttachScrollbar (  Text_Handle%,  Slider_Handle%,  x-offset%,  [Bar_Handle%]  )

To make text scrolling more comfortable, you can add a scroll bar to a text that is filled using HUD_SetScrollText( ). You can specify the object handle of an existing shape (a rectangle is quite useful) or an image object. The specified object will then be resized and positioned automatically to work as a scroll bar that can be used to scroll the text up or down.

Text_Handle%
The handle of a text object that has been filled using HUD_SetScrollText( )

Slider_Handle%
The handle of an existing shape (rectangle, for example) or image object that you want to use as a scroll slider. The specified object will then be resized and positioned automatically to work as a scroll slider that can be used to scroll the text up or down.

x-offset%
Sets the horizontal position of the scroll bar object, counted from the text's current x-coordinate.

Bar_Handle%
Optional handle of an existing shape (rectangle, for example) or image object that you want to use as a scroll bar (the bar behind the slider button). The specified object will then be resized and positioned automatically.

HUD_DetachScrollbar (  Text_Handle%  )

Detaches (unlinks) a currently attached scroll bar object from the text. The object you used as a scroll bar will not be deleted, it will lose it's scroll bar functionality only and can then be used like a common object again.

Text_Handle%
The handle of a text object that has been filled using HUD_SetScrollText( ) and has a scroll bar object attached.

HUD_EnableTextInput (  Text_Handle%,  maxChars%,  cursor$,  allowedChars$,  [uppercase%],  [SoundHandle%],  )

Use this command with an existing text object to enable dynamic text input. A blinking cursor will appear within the text field and the user will be able to enter some text. You can define a custom cursor, as well as the maximum length of the input text or what chars are allowed (any other chars will be ignored). A typing sound can be set, too.

Text_Handle%
The handle of a text object

maxChars%
The maximum amount of chars allowed to enter.

cursor$
Any char that will be used as a blinking cursor (for example '_'). The char used as cursor may NOT be inlcuded within the string of allowed chars.

allowedChars$
A string that contains all chars that a user may enter. Any other chars will be ignored. Note, that you must also include a space char if spaces should be included, too.
Example string: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789  "
With this example, the user may enter upper- and lowercase letters, numbers and spaces.

uppercase%

HUD_DisableTextInput (  )

Use this command to disable a currently active input text manually. Sprite Candy will also disable an input text automatically when a button has been clicked, another text object has been set to input mode, the text object has been set to 'hidden' or the user has used the ENTER key.

Handle% =  HUD_GetActiveInputText (  )

If an input text is currently active, this command will return the text object's handle, otherwise '0'. Use this command to check if and what input text is currently active.

Handle% =  HUD_InputTextClosed (  )

If an active input text has been closed (the user has pressed ENTER, for example), this command will return the handle of the regarding text object. Use this command to detect the last recently changed input text. You can use this command to do some text verifications on the regarding text, for example).

Text_Handle%
Handle of a text object