From Serious Documentation
Jump to: navigation, search

Font Resources

Fonts are instantiated in the Resources area.

Codepoints, UTF-8, and Unicode

In order to represent all the characters across all languages, the traditional ASCII character set that only has 8 bits (i.e. 256 characters) is insufficient. Unicode 16 is a standard that maps an unsigned 16 bit value called a "Unicode codepoint" or just "codepoint" to each glyph (character) across all different languages. The first 128 Unicode 16 characters are the same as the first 128 ASCII 8-bit characters. Unicode is well described at

However, storing text strings using uncompressed/unencoded 16-bit (i.e. 2 byte) values for every character can be very inefficient, especially when these strings have a preponderance of traditional ASCII characters including numbers and punctuation that would normally only take one byte each. Therefore various character compression/encoding systems have been developed in the industry attempting to optimize the storage required by text strings better than unencoded Unicode 16.

All strings within SHIP are encoded using the UTF-8 mechanism. UTF-8 is a variable length multi-byte encoding. The traditional 7-bit ASCII characters are all represented exactly the same in UTF-8. A special "escape" character, along with some encoding hints, allows several bytes of data to be combined into a single Unicode 16 value. It is important to recognize that "bytes" does not mean "characters". Each character may be encoded with 1, 2, 3, or even more bytes.

The SHIPTide tool performs all string editing in UTF-8 encoding. It will not be obvious to the user: text strings look normal. Cutting and pasting (for example) from Google Translate will work seamlessly. However, you must be careful if you (for example) copy a script from SHIPTide to your favorite text editor and then paste it back into SHIPTide. If your external text editor does not comprehend UTF-8 natively, any special non-ASCII characters in your embedded strings will be mangled.

There are numerous Sail Functions available for manipulating strings and converting characters to codepoints (and back).

Including Font Files and Codepoints

The first step in making a font available to text within the SHIP GUI is to import a font file and declare what characters from that font file your GUI needs to have available. SHIPTide understands True Type fonts, normally files with a ".ttf" suffix in most operating systems.

The fontfamilyinfo node in the resources area holds this information. You can add a font family into SHIPTide a number of ways:

  • With the resources node) selected, Add New->fontfamilyinfo,
  • Use the File->import media wizard
  • Drag a .ttf file from your OS desktop anywhere into SHIPTide

An example fontfamilyinfo node might look like this:

Example  fontfamilyinfo Node

In this example, the fBigNumbers font uses the Square721BT.ttf True Type font file. It also includes the following codepoints (16-bit unicode characters):

Codepoint(s) Character(s)
0x20..0x46 ASCII " " through capital "F", including "0" to "9"
0x78 ASCII "x"
0xB0 The degrees symbol (°)
0xB1 The plus/minus symbol (±)

This codepoints range gives us the complete hex digit set, plus most symbols including degrees, as well as the lower case "x" so that hex numbers like "0x50" can be displayed.

The fontfamilyinfo' node does not technically require significant SHIPEngine memory, however the specific fontinfo instantiations within the family will grow proportionately to the number of codepoints listed in the fontfamilyinfo node. Specifying a very large codepoint set will, when the sizes/styles are specified in the fontfamilyinfo nodes, drive large or even unsupportable memory requirements depending on the SIM.

Establishing the Font Sizes and Styles Available

Once you have the font resources identified (i.e. fontfamilyinfo nodes created and linked to .ttf files with codepoints selected), the next step is to articulate the set of font sizes and styles your GUI needs from that font.

fontinfo nodes within a   fontfamilyinfo node perform this function.  Each   fontinfo entry describes one font size, in pixels of height.  This entry generates a bitmap array of the codepoints at that size.  

An example fontinfo node within the fBigFonts' fontfamilyinfo node might look like this:

Example  'fontinfo Node

In this example, this GUI has a 64-pixel high set of the codepoints from the .ttf file specified in its parent fBigFonts fontfamilyinfo node.

The height is the full height of the tallest character of the whole font (regardless of the codepoints selected). This spans the lowest descender (commonly a j) to the tallest ascender (commonly a [ or !).

The fontantialias property turns on and off anti-aliasing of the edges of the font, making the font stroke edges much smoother to the eye and less jagged. The number of bits per pixel, the fontbpp property, sets how many bits of opacity information is used in the anti-aliasing. 8 bits per pixel, for example, provide 256 levels of shading on the edges of the drawn characters' stroke.

The more bits available to anti-aliasing, the smoother the character stroke edges will be. However, the size of the fonts and the memory required in the SIM to manage them, goes up significantly as well. In addition, the more the anti-aliasing the slower text rendering will be.

Therefore it is wise to experiment with these properties and set them as low as possible to achieve the look and feel you desire in your GUI.

GUI Font Defaults

It is a good practice to set the font properties for text in a GUI at the display level. All visible text objects within that display will use that font family/size/style unless otherwise directed.

For example, this display node d0, has a default font size, style, color, and family identified:

Example display node with GUI Font Defaults

The background color is left unset, meaning a fully transparent background to characters so regardless of the image or color they're put on top of they'll look fine.

Font Overrides and Selection

In the the Layout area, text/font properties (such as textsize) are inherited by child nodes from their parents. So, by default, a page will inherit its text/font properties from its parent display, and a box within a page will inherit that page's and so on all the way down the branches until the actual text node where the characters are to be rendered in the GUI.

All displayable nodes have the set of text/font properties, and each node can affect the net set of properties on that node and further into the children. For example, this combination of the prior display plus a page with textcolor overridden:

Example display node with page textcolor Override

Results in any text in that page, by default, being the new color.

When the actual text node is rendered, the set of properties inherited and resolved on that node are is used to look up the font combination that matches. If no font matches that combination a default system font is used -- not likely what your GUI will want! If we modify the prior example to specify in the page textsize as 17, this is a problem -- the set of fontinfo entries for the font fMain' does not have a 17 pixel version. Therefore text within this new page will not find a match and instead use the 20-point non-anti-aliased system font.