Encoded Text
[Context: HL Kit … Basic Concepts and Terminology … Visual Building Blocks]
While not exactly a true "building block", encoded text is an important facet of the visual presentation for any game system. Encoded text is the term used for inserting control over colors, fonts, and even bitmaps within text strings. If you want to highlight a word within a string in red, you'll use encoded text. If you want to change the font size for a few works or put a keyword in bold, you'll use encoded text. You can also insert bitmaps into the text stream with encoded text, which makes it possible to do things like display the sequence of dots for traits within the World of Darkness game system.
The encoding syntax uses the characters '{' and '}' to identify the special codes, much like HTML uses the '<' and '>' characters to wrap special codes. The text found between the '{' and '}' characters is interpreted based on the table given below.
{br} Inserts a carriage return into the text at this position. {nbsp} Inserts a non-breaking space into the text at this position. Word-wrapping behavior is not allowed to occur on a non-breaking space, so the space is tied to whatever other text appears before and/or after it. This can be useful for placing padding around text that changes foreground and/or background colors. {spc} From this point forward in the text, all sequences of multiple spaces are collapsed into a single space. {b} {/b} Text following the "{b}" sequence is rendered in bold. This persists until the "{/b}" sequence turns off bold rendering. {i} {/i} Text following the "{i}" sequence is rendered in italics. This persists until the "{/i}" sequence turns off italics rendering. {u} {/u} Text following the "{u}" sequence is underlined. This persists until the "{/u}" sequence turns off underline rendering. {font name} From this point forward in the text, the font with the specified "name" will be used for output. The prevailing size and style are used in conjunction with the new font. NOTE! Use of a font that is not a standard Windows font will result in the new font being ignored on any computer that does not possess the font. So be sure to only use standard Windows fonts if you plan on distributing your data files to others.
{size value} From this point forward in the text, the font size is changed to the given "value". In order to support fractional point sizes, the value is the number of quarter-points, so a value of 40 would translate to a point size of 10, while a value of 38 would translate to a point size of 9.5. The prevailing font and style are used in conjunction with the new size. {revert} From this point forward in the text, the original default font characteristics are restored. All states for bold, italics, and underline are reset to off, regardless of the default font characteristics restored. The primary use for this encoding is to output some text in the default font, configure the text properly for a short segment, and then revert to outputting the rest of the text in the original font. This way, the same encoded text works consistently even when the default font varies between situations. {text xxxxxx} This sequence changes the foreground text color to the color given by "xxxxxx". The format for the color uses standard HTML color syntax, with each character representing a hexadecimal digit. The first two characters define the Red color value, the next two Green, and the last two Blue. For example, the encoding "{text ff0080}" specifies a Red value of "ff", a Green value of "00", and a Blue value of "80". To revert the foreground text color back to the default, use a color value of "010101". {back xxxxxx} This sequence changes the background text color to the color given by "xxxxxx". The color format uses standard HTML syntax, as described for "{text}" above. To disable use of a background color and display text transparently, use a color value of "010101". {align position} From this point forward in the text, each new line of text will be aligned based on the given "position". The position must be one of the following values: "left" for left-aligned text, "right" for right-aligned text, or "center" for centered text. {vert value} Vertical spacing is immediately inserted into the output, with "value" indicating the number of pixels worth of gap to insert. {horz value} Horizontal spacing is immediately inserted into the output, with "value" indicating the number of pixels worth of gap to insert. {bmp name} Inserts into the output the bitmap image with the file name of "name.bmp" that resides in the data file directory for the game system. This bitmap is assumed to be transparent, with the pixel at (0,0) indicating the transparent color. For example, the code "{bmp foo}" would insert the bitmap file named "foo.bmp" that is found in the game system directory. NOTE! If the bitmap is not found or the output doesn't support encoding, the "name" is inserted as text. So if the filename is "[R].bmp" and referenced as "{bmp [R]}", the text inserted would be "[R]". NOTE! By default, bitmaps are never scaled when output, but individual styles can explicitly enable scaling of bitmaps inserted via encoded text. If scaling is enabled, the bitmaps may not look ideal due to the scaling.
{macro name} Looks for the macro with the unique id given by name and processes the contents of that macro as if it were found in the text instead. This means that macros MAY include encoded text that will be properly processed when the macro is evaluated. NOTE! Macros MAY be nested within each other, but only to a limited extent, so use nesting sparingly. If a macro references another macro within it, the nested macro will be correctly processed, up to a small number of nesting levels. NOTE! If an undefined macro is referenced, a message of the form "[Undefined macro: name]" is inserted into the resulting text where the macro would be.
{ref name} Designates the start of a reference region (or "hot zone") that the user can click within to obtain additional information. The name specifies the predefined reference to show when the user clicks in the zone. The zone spans all text from this point forward until the zone is terminated. Terminating a reference zone is accomplished by leaving the name blank. The following is an example of using a reference: "before {ref foo}hot zone{ref} after". NOTE! If an undefined reference is used, a message of the form "[Undefined reference: name]" is displayed when the reference hot zone is clicked within by the user.
{url name} Designates the start of a hot zone corresponding to an internet URL. The name specifies the actual URL to which the user will be sent when the zone is clicked within (e.g. "http://www.wolflair.com"). The zone spans all text from this point forward until the zone is terminated. Terminating a URL zone is accomplished by leaving the name blank. The following is an example of using a URL zone: "before {url http://www.wolflair.com}hot zone{url} after". NOTE! When clicked, Windows is instructed to launch the default web browser that is currently configured by the user and to load the specified URL into that browser. If no browser is properly configured, an error will be reported. If the URL is invalid, the web browser will report that to the user.
\n Identical to “{br}”. This is a programming convenience for automated conversion programs written in C/C++.
IMPORTANT! Not everything within HL makes use of encoded text, so be sure to check the documentation first. If you use encoded text in a place where it's not supported, you will see your embedded special codes within the text displayed.
NOTE! Encoded text sequences ignore case, so "{BR}" is identical to "{br}". Exceptions to this are macro and reference names, which are case-sensitive. Similarly, URLs are case-sensitive if the website being addressed uses case-sensitive URLs.
NOTE! If the text within an encoding does not correctly match one of the codes defined above, the text is left unchanged, except as noted above.
