===== orxTEXT structure =====

==== Summary ====

=== Text ===

<code ini>[TextTemplate]
String = "string to display"
Font   = FontTemplate
</code>

=== Font ===

<code ini>
[FontTemplate]
Texture            = path/to/ImageFile.ext
TextureOrigin      = <vector>
TextureSize        = <vector>
KeepInCache        = <bool>
CharacterList      = "ordered list of character"
CharacterSize      = <vector>
CharacterHeight    = <float>
CharacterWidthList = <float>
CharacterSpacing   = <vector>
</code>

==== Details ====

=== Text ===

Here's a list of available properties for an ''orxTEXT'' structure:

  * ''String'': Defines the content of this orxTEXT as plain text. If this string begins with the character '$', it will be used as a locale key instead of as a plain text. It will then be automatically updated upon a new language selection.
  * ''Font'': Specifies a font to use for this text. If none is provided or 'default' is used, orx's default font will be used. If it begins with the character '$', it will be used as a [[en:orx:config:settings_main:main#Locale localization module|locale key]] instead of as a plain section name. It will then be automatically updated upon a new language selection. See below for an example of multiline text.

Here's a small example.

<code ini>[Text1]
String = This is our first text
Font   = Font1

[Text2]
String = $Greetings
Font   = $FontKey

[MultilineText]
String = "First line
Second line"
Font   = Font1</code>

''Text1'' has a static plain text content with a static custom font called ''Font1'' whereas ''Text2'' points to the localization keys named ''Greetings'' for its text content and ''FontKey'' for its font. This means that its content and font are defined in the [[en:orx:config:settings_main:main#Locale localization module|orxLOCALE module]] and will always be expressed according to the current selected language.

//NB: If the current language is changed at runtime, the text's content and font will be automagically updated without requiring any code.//

=== Font ===

Here's a list of available properties for an ''orxFONT'' structure:

  * ''TextureOrigin'': Specifies the top left origin of the first defined character in the bitmap file, in pixels (Z coordinate being ignored). By default its value is (0, 0, 0) which means the texture for the font object will begin at the top left of the bitmap file. Note: TextureSize must also be supplied for this to take effect.
  * ''TextureSize'': Specifies the size, in pixels, of the bitmap file where characters are defined (Z coordinate being ignored). By default it will use the whole bitmap, ie. its value will be the size of the bitmap.
  * ''KeepInCache'': If true, the associated texture will always stay in cache. Defaults to false.
  * ''CharacterList'': Specifies all the characters that are defined in the bitmap file, ie. all the characters with a glyph in the texture file will have to be specified in order of appearance. The string can be encoded in strict ANSI/ASCII or UTF-8. **ISO-Latin-1 is __not__ supported!** To avoid special characters to be handled by orx's config parser ((such as '#', ';', '"', '~', '$', ...)), the string is likely to be defined as a block using the block marker ('"'). **In order to specify '"' itself in the string, this character needs to be doubled and not in the first position!**
  * ''CharacterSize'': A vector specifying the size of a character, in pixels (Z coordinate being ignored). **If this property is defined, orx assumes the font is monospaced (ie. fixed width, all the characters need to be organized in a grid manner). See the command line tool [[#orxFontGen]] to see how to create custom bitmap fonts from a given TrueType font file.** If defined, CharacterHeight & CharacterWidthList will be ignored. 
  * ''CharacterHeight'': This is only used for non-monospaced fonts, ie. when CharacterSize isn't defined. This property has to be a strictly positive value that will be the font character's height.
  * ''CharacterWidthList'': This is only used for non-monospaced fonts, ie. when CharacterSize isn't defined. There should be exactly one value per character defined in CharacterList in the same order.
  * ''CharacterSpacing'': Empty space between characters, z is ignored. Defaults to (0, 0, 0).

An example of how to use custom fonts can be found in the [[en:tutorials:localization:locale|localization]] tutorial ((at the end of 10_Locale.ini)).

===== orxFontGen =====

orxFontGen is a command-line tool that ships with Orx which allows you create bitmap fonts which can be define with the configuration detailed above. It can be found in the orx/tools/orxFontGen/bin folder. Available to compile for Windows, Linux and Mac. To learn how to use it follow the [[en:tutorials:text-fonts:orxfontgen|orxFontGen tutorial]].


==== Latest config settings for the Development Version ====
{{section>en:orx:config:developmentversion#&noheader&nofooter&noeditbutton}}