3.8. Text Fonts
Prev | Chapter 3. PHPlot Concepts | Next

## 3.8. Text Fonts

This section contains information about using text fonts in PHPlot. See Section 6.6, “Text Fonts” for PHPlot functions used with text fonts.

### 3.8.1. Overview

PHPlot supports both built-in GD fonts and TrueType fonts (if available on your system). TrueType fonts generally produce higher quality text, but using them requires more internal computations. The built-in GD fonts are faster to render, but are limited to one typeface and 5 available sizes. TrueType fonts can be drawn at any size and angle, and many typefaces are available. On most systems, TrueType fonts are anti-aliased for improved appearance, but under some conditions the GD fonts may be easier to read. TrueType fonts support much wider character sets, including special symbols, while the GD fonts are more limited.

The following figure shows the built-in GD fonts plus a sample TrueType font. (Depending on how you are viewing this manual, the sizes of the fonts in this figure might differ from how they would look in a PHPlot image. For more on font sizes, see the notes with SetFont.)

### 3.8.2. Text Element Names

Each type of text available in PHPlot has an element name. When selecting text fonts with SetFont and related functions, you use the element name to indicate what type of text you are configuring. The following table lists the PHPlot text element names.

Element Name | Used for
--- | ---
generic | Pie chart labels, error image text, message image text
legend | Text in the legend (SetLegend)
title | Main plot title (SetTitle)
x_label | X tick labels and X data labels
y_label | Y tick labels and Y data labels
x_title | X axis title (SetXTitle)
y_title | Y axis title (SetYTitle)

Notes: `generic` is also used for text drawn from a callback when no font is specified. See Section 4.4.5, “Using Callbacks to Annotate Plots” and DrawText. Although `generic` is used for error image text, changing the font or size has no effect because the error handler resets the font to the default before displaying the error. Message image text refers to DrawMessage.

### 3.8.3. TrueType Font Selection

PHPlot text can use built-in GD fonts or TrueType fonts. When using GD fonts, you specify a font name as a number between 1 and 5. This selects from 5 built-in GD fonts. When using TrueType fonts, you need to specify a font filename. The rest of this section discusses only TrueType fonts.

### Note

The material on specifying font files for PHPlot applies to releases starting with PHPlot-5.1.3. Through PHPlot-5.1.2, you generally need to specify the full pathname of a font file, or the full path of a font directory.

On Windows systems, you need to use the font filename, not the font name. You can get the font filename using Control Panel - Fonts. For example, Windows applications may display "Arial Black", or "Arial Black (TrueType)" as a font name, but the actual font filename is "ariblk.ttf". Since GD knows to look for fonts in the Windows font directory, you will not need to specify a full pathname to font files, unless the font is installed in some other directory.

On Windows, you can use the "Character Map" system tool to examine a font. This can also be used to find the Unicode character code of a special character. These will be displayed in hexadecimal, for example U+20AC for the Euro. See Section 3.8.5, “Using Special Characters” for more information on using special characters.

Here are some font selection examples for Windows:

    # For titles, use Arial Bold Italic at 14 points:
    $plot->SetFontTTF('title', 'ARIALBI.TTF', 14)
    # For X Title, use Verdana at 12 points:
    $plot->SetFontTTF('x_title', 'VERDANA.TTF', 12)

On some Linux and similar systems, GD is able to find fonts specified without paths, but on other systems you will have to specify a font directory with either SetTTFPath or as part of the font name in SetFontTTF. If you specify a full pathname to a font, you must also supply the extension (.ttf); you may omit the extension when relying on GD to find the font. Remember that font filenames are case sensitive on most of these systems.

The font search path for GD (bundled with PHP) includes the following directories on Linux and similar systems:

- `/usr/X11R6/lib/X11/fonts/TrueType`

- `/usr/X11R6/lib/X11/fonts/truetype`

- `/usr/X11R6/lib/X11/fonts/TTF`

- `/usr/share/fonts/TrueType`

- `/usr/share/fonts/truetype`

- `/usr/openwin/lib/X11/fonts/TrueType`

If your system has TrueType fonts in one of those directories, you can select them with a filename only. If not, you must use a full directory path in either the font name or with SetTTFPath.

### Note

The environment variable `GDFONTPATH` can be defined to contain a list of directories (separated by a colon ':') to search for fonts. If defined, this replaces the above list.

Your Linux system may include a tool for examining fonts. One such tool is gucharmap. This can also be used to find the Unicode character code of a special character. These may be displayed in hexadecimal, for example U+20AC for the Euro. See the next section for more information on using special characters.

Here are some font selection examples for Linux:

    # On systems with fonts in an expected place, like Slackware Linux,
    # just use the font filename:
    # For titles, use Liberation Sans Bold Italic at 14 points:
    $plot->SetFontTTF('title', 'LiberationSans-BoldItalic.ttf', 14)
    # For X Title, use DejaVuSans Bold at 12 points:
    $plot->SetFontTTF('x_title', 'DejaVuSans-Bold.ttf', 12)

    # Ubuntu and Debian use subdirectories under a searched path.
    # You can use a partial path here.
    $plot->SetFontTTF('x_title', 'liberation/LiberationSans-Regular.ttf', 12)
    # Note: Older Ubuntu/Debian used the path ttf-liberation/...

    # Fedora uses subdirectories which are not under a searched path.
    # You must use full paths here.
    $plot->SetTTFPath('/usr/share/fonts/liberation/');
    $plot->SetFontTTF('x_title', 'LiberationSans-Regular.ttf', 12)

### Note

Your Linux system probably has a package called `fontconfig` which is used to provide more consistent access to fonts. But even if your system uses a version of the `gd` library which is built with `fontconfig` (and the one bundled with PHP does not), PHP does not use `fontconfig`. Therefore PHPlot needs to be able to locate font files using other means.

### 3.8.4. Default TrueType Font

### Note

This section applies starting with PHPlot-5.1.3.

If you try to use TrueType text without specifying a font name, PHPlot will use the default font. You can set the default font with SetDefaultTTFont. If you do not set a default font, PHPlot tries to locate a sans-serif font to use. Here are the font names that PHPlot tries in order. First it tries the filename alone, letting GD use its search path, and then it tries with the default font path, as set with SetTTFPath.

- `LiberationSans-Regular.ttf` - Likely to work on Linux and other systems with a correct GD font search path.

- `Verdana.ttf, Arial.ttf, Helvetica.ttf` - One of these is going to work on Windows, maybe other systems too.

- `liberation/LiberationSans-Regular.ttf, ttf-liberation/LiberationSans-Regular.ttf` - This is for Debian, Ubuntu, and similar (the first is for newer releases, such as Ubuntu 12.04 and later, and the second is for older releases).

- `benjamingothic.ttf` - The original PHPlot default, for compatibility.

The last item on the list is used regardless of whether it can be found or not. This means if you enable TrueType fonts without setting a default, and get a fatal error from PHPlot that it can't find the font benjamingothic.ttf, this means PHPlot was unable to find any of the standard fonts in its list. On that system, then, you must provide either a font directory, or use full font pathnames.

### 3.8.5. Using Special Characters

You can include special characters in your PHPlot labels and titles. This refers to characters which you may not be able to type with a single key on your keyboard, including accented characters and special symbols.

PHPlot itself does not do any special processing of text strings, so you should refer to the PHP GD and Image Functions reference for more information.

### Note

This mostly only works with TrueType fonts. The built-in GD fonts do have some extended characters, but they are encoded in ISO8859-2 which is probably not what you might expect, and the GD font routines do not support special character entities.

To use special characters in your PHPlot text strings, you need a TrueType font that contains the characters you want. Ideally, you want a Unicode font. You might have to examine the font using an operating system-specific tool to see if your characters are present and to find their numeric values.

There are two basic ways to include special characters in your text strings. The examples below use the Euro character, which is decimal Unicode value 8364.

- Use HTML-type character entities with decimal numeric encoding. For example, the Unicode Euro symbol is: &#8364;

- Include the UTF-8 encoding of the Unicode value in your string as a series of hex escapes. For example, the Euro symbol is: "\xe2\x82\xac".

These are shown in the example below, both of which set the Y axis title to "Items per €100".

    $plot->SetYTitle("Items per &#8364;100"); # Numeric character entity
    $plot->SetYTitle("Items per \xe2\x82\xac100"); # UTF-8 encoding

You can also use PHP functions to encode your characters for including in PHPlot text strings. See the PHP documentation for the functions `html_entity_decode()` and `iconv()`. Here are some examples (sent in by SourceForge user 'kalvaro'):

    # Encode the Euro symbol into UTF-8:
    $chars = html_entity_decode('&euro;', ENT_NOQUOTES, 'UTF-8');

    # Use iconv() to convert a character value xA4 in ISO-8859-15 to UTF:
    $chars = iconv('iso-8859-15', 'utf-8', chr(0xA4));

### Note

GD does not support using named character entities such as &euro; directly in strings - they must be numerically encoded as described above.

Prev | Up | Next
3.7. Other Plot Elements | Home | 3.9. Error Handling