typedef struct Font        Font;
  typedef struct Subfont     Subfont;
  typedef struct FontWidth   FontWidth;

  struct Font {
    int             refcount;       /* used when caching fonts */
    int             maximum_width;  /* maximum character width */
    int             height;         /* pixel height of chars */
    char *          name;           /* UTF-8 encoded font name */
    int             style;          /* style */
    App *           app;            /* back pointer to cache */
    int             num_subfonts;
    Subfont **      subfonts;       /* list of subfonts */
    void *          extra;          /* platform-specific data */

  struct Subfont {
    unsigned long   base;           /* Unicode value of first char */
    int             num_widths;     /* list of font width records */
    FontWidth **    widths;
    void *          extra;          /* platform-specific data */

  struct FontWidth {
    int             width;          /* in pixels, -1=non-existent */
    int             num_ranges;     /* number of (start,end) pairs */
    byte *          range_list;     /* (start,end) pairs of bytes */


  Font *new_font(App *app, char *name, int style, int height);
  void  del_font(Font *f);

  int   font_height(Font *f);
  int   font_width(Font *f, char *utf8, int nbytes);

  Font *find_default_font(App *app);

  void  set_font(Graphics *g, Font *f);
  void  set_default_font(Graphics *g);


  enum {
    PLAIN  = 0,
    BOLD   = 1,
    ITALIC = 2,
    NATIVE_FONT   = 32


A Font is a typeface of a certain size and style.

A font can be obtained using new_font. The name parameter is a UTF-8 encoded string like "serif" or "unifont", while the style is a bit-field composed of any of the styles PLAIN, BOLD, ITALIC, PORTABLE_FONT or NATIVE_FONT. Use the bitwise-or operator to combine these styles. The height field specifies a pixel-height for the font. The function may return NULL if it cannot find a suitable font.

Hence new_font(app, "serif", BOLD, 12) returns a bold serif 12-pixel-high font.

If the PORTABLE_FONT style flag is included, only portable fonts supplied with the library will be searched for a matching font. If the NATIVE_FONT style flags is given, only native platform-specific fonts will be searched. Native fonts are inherently non-portable and usually do not handle anything more than ISO-Latin-1 text, but are generally rendered fast. If neither of these flags, or both of them, are given, first portable fonts and then native fonts are searched for a matching name, style and size; the first matching font is returned.

The del_font function releases the memory used by a font. In general this function does not need to be used unless memory is critical, as fonts will automatically be released from memory when the program ends.

The font_height functions reports the pixel height of the font. All characters within the font will use this height as their inter-line spacing.

The font_width function reports the pixel width of the given UTF-8 encoded string in the supplied font. The nbytes parameter specifies the number of bytes within the string, thus allowing '\0' characters to be within the string.

The find_default_font function returns the default font. The supplied App object's font list is searched for the font first, and loaded into that object if it hasn't already been loaded.

The current font used for drawing within a given Graphics context can be set using the set_font function.

The set_default_font function loads the default font and sets that font in the Graphics context. It is the equivalent of set_font(g, find_default_font(g->app));

Three portable fonts are currently supplied with GraphApp: "serif", "plain" and "unifont", the last being the default Unicode font. Portable fonts are stored as bitmaps. Each bitmap contains space for exactly 256 characters, and is called a Subfont. Subfonts are loaded on demand by the font rendering engine, and cached in a list on the Font structure. The details of this caching mechanism, and the other data associated with a subfont, are not, in general, relevant to the programmer.

If a particular character glyph cannot be found on a font by the font rendering engine, it will then search for it on the default font. If it still isn't found, a rectangular box shape will be drawn instead. Since the supplied Unicode font contains some 35,000 characters, this event should be rare in normal usage.