3.8. Text Fonts

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

3.8.1. 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.

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". You can tell PHPlot to look for fonts in the Windows font directory by passing $_SERVER['windir'] . '\\fonts\\' to SetTTFPath, but this is not necessary since PHP will look there anyway. However, it is important to note that if you include a font directory path, you must also include the file extension ".ttf". If you do not specify a font directory, you can omit the file extension.

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 the next section for more information on using special characters.

Here are some font selection examples for Windows:

   # Set path; this is not really needed.
   $plot->SetTTFPath($_SERVER['windir'] . '\\fonts\\');
   # 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 Linux and similar systems, you should specify a font directory with SetTTFPath. Typically this will be /usr/share/fonts/TTF. However, depending on your system setup, PHP may be able to find fonts without the path. As on Windows, you must provide a font filename with extension if using a path, but the extension can be omitted if no path is used. Remember that font pathnames are case sensitive.

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:

   # Set path; this may or may not be needed.
   $plot->SetTTFPath('/usr/share/fonts/TTF/');
   # 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)

3.8.2. 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: €

  • 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 €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('€', 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);