# Font Resources

### Resource options

Each font can have the following properties:

    <font
    	name="my_font"
    	width_offset="offset"
    	height_offset="offset"
    	delims="delimiters">

    	<system
    		font_name="facename"
    		height="height_in_pixels"
    		width="width_in_pixels"
    		bold="[0,1]"
    		italic="[0,1]"
    		underline="[0,1]"
    		strikeout="[0,1]"
    		letters="abcdefghijkl..." />

    	<bitmap
    		glyphs="sprite_resource_id"
    		letters="abcdefghijkl..."
    		spacelen="pixel_width_of_space"
    		monospace="[0,1]" />

    </font>

To setup a font resource, it is required to specify the name attribute of <font> and at least the required attributes for either a <system> font or a <bitmap> font. The required attributes for the system fonts are font_name and height. Required attributes for bitmap fonts are glyphs, letters and spacelen.

### Using <system> fonts

System fonts are generated by the local font system, typically Windows or X11. For performance reasons, the system font is converted into a bitmap font internally in ClanLib, which means it can save texture memory if it is specified more exactly what letters will be used in the font. Aside from that the only limitations are that the font specified by the font_name attribute must be available on the system. If it is not the underlying window system will pick another font, based on criterias that are platform specific.

For system fonts only the font_name and height (specified in pixels) needs to be specified. The remaining flag attributes are optional. If the letters attribute, which specifies characters should be included when creating the bitmap glyphs, is not specified then it will include the default characters in the range 32-128. It is highly adviced to specify the letters as this can save a lot of memory the bigger the font is.

### Using <bitmap> fonts

Bitmap fonts are built using a sprite resource. The attributes in the <bitmap> element specify what sprite resource contains the glyphs (a glyph is the image of a character) to be used in the font. The sprite resource is then used together with the letters attribute to link each frame from the sprite resource to the corresponding glyph character in the font.

To illustrate this, imagine a sprite that contain 10 frames, containing the letters A, B, C, D, E, 4, 3, 2, 1, 0 in that order. The letters attribute should then contain the string "ABCDE43210".

Any character printed not present in the font will be replaced by the space character. The space character gets the width specified by the spacelen attribute.

monospace is an optional attribute that, if set to "1", will cause all characters to use the spacelen as the width of the character (instead of using the glyph's bitmap width).

### Font resource options reference

<font>

- Attribute name: Name of resource.

  Valid values:
  Default value: None, MUST BE PRESENT.

- Attribute width_offset: Width offset of the font.

  Valid values:
  Default value: "0"

- Attribute height_offset: Height offset of the font.

  Valid values:
  Default value: "0"

- Attribute delims: Delimiter characters.

  Valid values:
  Default value: " " (space)

<system>

- Attribute font_name: Font face name.

  Valid values:
  Default value: None, MUST BE PRESENT.

- Attribute height: Font height in pixels.

  Valid values:
  Default value: None, MUST BE PRESENT.

- Attribute width: Font width in pixels.

  Valid values:
  Default value: "0"

- Attribute bold: Bold flag.

  Valid values: "0", "1"
  Default value: "0"

- Attribute italic: Italic flag.

  Valid values: "0", "1"
  Default value: "0"

- Attribute underline: Underline flag.

  Valid values: "0", "1"
  Default value: "0"

- Attribute strikeout: Strikeout flag.

  Valid values: "0", "1"
  Default value: "0"

- Attribute letters: Characters to include in font.

  Valid values:
  Default value: "abcdefghijklmnopqrstuvwxyz0123456789.." - (generally all chars from 32 to 128)

<bitmap>

- Attribute glyphs: Sprite resource containing the glyphs (font characters).

  Valid values: Any sprite resource
  Default value: None, MUST BE PRESENT.

- Attribute letters: Characters to be linked with each sprite frame.

  Valid values: "abcdefghi.."
  Default value: None, MUST BE PRESENT.

- Attribute spacelen: Width of the space character.

  Valid values:
  Default value: None, MUST BE PRESENT.

- Attribute monospace: Monospace flag.

  Valid values: "0", "1"
  Default value: "0"