JpGraph supports a number of predefined TTF fonts specified by a symbolic constant in the call to SetFont(). By default the library has predefined constants for the Core WEB TTF and Vera Bitstream fonts since they are the only set of TTF fonts freely available on all platforms.

For users wanting to make available proprietary TTF fonts they are in the possession of for use int the library some manual steps are required. In the rest of this discussion we will explain how to augment the library to handle new fonts.

TTF fonts are usually grouped in font families, e.g. Arial, Vera, Times etc. Within these families several font styles usually exists, for example Italic and Bold. Each of these styles are available as separate font files and it is therefore necessary to identify what font files provide what combination of font family and font style. The file names must be known in order to proceed with these instructions.

The library makes use of one central class that handles TTF fonts class TTF defined in jpgraph_ttf.inc.php. This class is responsible for defining the mapping between symbolic font names and font files. This is handled by the exposed method TTF::File() which given a symbolic font specification (family and type) returns the actual font file. At the time of this writing the following font families are predefined in the library

• FF_COURIER , One of the core web fonts
• FF_GEORGIA , One of the core web fonts
• FF_TREBUCHE, One of the core web fonts
• FF_VERDANA, One of the core web fonts
• FF_TIMES, One of the core web fonts
• FF_COMIC, One of the core web fonts
• FF_ARIAL, One of the core web fonts
• FF_VERA, One of the Vera Bitstream fonts
• FF_VERAMONO , One of the Vera Bitstream fonts
• FF_VERASERIF, One of the Vera Bitstream fonts
• FF_SIMSUN, Chinese fonts
• FF_CHINESE, Synonym for chinese fonts
• FF_MINCHO, Japanese fonts
• FF_PMINCHO, Japanese fonts
• FF_GOTHIC, Japanese fonts
• FF_PGOTHIC, Japanese fonts
• FF_MINCHO, Japanese fonts

In order to make additional fonts available in the library the up to four steps may have to be taken

1. Decide what font family name should be used for each of the new fonts added and then create new symbolic defines for these families. In order to follow the naming convention these defines should have a prefix of "FF_" (for Font Family) and be given a numeric value >= 100. These defines are made in the top of the file jpgraph_ttf.inc.php where there is a section of font family defines.
2. Update the existing define "_FF_LAST" with the highest index used for any font family.
3. Add a new mapping between symbolic font family name (and style) with the actual font file name by updating the mapping array TTF::font_files in the TF class. The mapping should be made for each of the font families and corresponding styles. If a style is not available for a specific family the font file should be specified as an empty string.
4. If the font files is not already available in the defined font directory copy the necessary font files.

After those changes have been made the new font family will be available for usage. In the next section we give a short example on the detailed steps on how to add a new font family.

In order to show in details the steps described above we will demonstrate how to add a new font family called handwrt

Step 1 & 2 - Specify a new font family symbolic name

For this family we decide to use the name FF_HANDWRT. In order to make that name available in the library we add the following new define to the top of the file jpgraph_ttf.inc.php. First locate the following section at the top of the jpgraph_ttf.inc.php

...
// Chinese font
DEFINE("FF_SIMSUN",30);
DEFINE("FF_CHINESE",31);
DEFINE("FF_BIG5",31);

// Japanese font
DEFINE("FF_MINCHO",40);
DEFINE("FF_PMINCHO",41);
DEFINE("FF_GOTHIC",42);
DEFINE("FF_PGOTHIC",43);

// Limits for TTF fonts
DEFINE("_FF_FIRST",10);
DEFINE("_FF_LAST",43);
...

We no add our define DEFINE("FF_HANDWRT",100) in this section and update the _FF_LAST constant as well to get

...
// Chinese font
DEFINE("FF_SIMSUN",30);
DEFINE("FF_CHINESE",31);
DEFINE("FF_BIG5",31);

// Japanese font
DEFINE("FF_MINCHO",40);
DEFINE("FF_PMINCHO",41);
DEFINE("FF_GOTHIC",42);
DEFINE("FF_PGOTHIC",43);

// Custom added font families
DEFINE("FF_HANDWRT",100);

// Limits for TTF fonts
DEFINE("_FF_FIRST",10);
DEFINE("_FF_LAST",100);
...

Where we have marked in bold the changed/added lines.

Step 3 - Update the mapping

The next step is to specify the actual mapping between symbolic names and TTF font file names. In this example we will assume that the font family has the available styles normal, italic and bold but does not support bolditalic. We will further assume that the name of the font files for the different styles are

• normal => "handwrt.ttf"
• italic => "handwrti.ttf"
• bold => "handwrtb.ttf"

First we need to locate the class TTF and the instance variable TTF::font_files, hence we need to locate the following code in jpgraph_ttf.inc.php

...
//===================================================
// CLASS TTF
// Description: Handle TTF font names
//===================================================
class TTF {
    var $font_files,$style_names;
//---------------
// CONSTRUCTOR
    function TTF() {
        $this->style_names=
          array(FS_NORMAL=>'normal',FS_BOLD=>'bold',
                FS_ITALIC=>'italic',FS_BOLDITALIC=>'bolditalic');

	// File names for available fonts
        $this->font_files=array(
	    FF_COURIER => 
              array(FS_NORMAL=>'cour.ttf', FS_BOLD=>'courbd.ttf', 
                    FS_ITALIC=>'couri.ttf', FS_BOLDITALIC=>'courbi.ttf' ),
...

We then need to add the actual mapping as shown in bold below.

...
//===================================================
// CLASS TTF
// Description: Handle TTF font names
//===================================================
class TTF {
    var $font_files,$style_names;
//---------------
// CONSTRUCTOR
    function TTF() {
        $this->style_names=
          array(FS_NORMAL=>'normal',FS_BOLD=>'bold',
                    FS_ITALIC=>'italic',FS_BOLDITALIC=>'bolditalic');

	// File names for available fonts
        $this->font_files=array(

          FF_HANDWRT => 
             array(FS_NORMAL=>'handwr.ttf', FS_BOLD=>'handwrb.ttf',
                   FS_ITALIC=>'handwri.ttf', FS_BOLDITALIC=>'' ), 

	    FF_COURIER => 
              array(FS_NORMAL=>'cour.ttf', FS_BOLD=>'courbd.ttf', 
                    FS_ITALIC=>'couri.ttf', FS_BOLDITALIC=>'courbi.ttf' ),
...

We are now finished. The new font family will be available as any other fonts in the library. So for example to use this new font for a title in a graph we can use the following code snippet

...
$graph->title->SetFont(FF_HANDWRT,FS_BOLD,14);
...

From time to time we are approached to add additional predefined names for fonts that have been added in the way described above. As long as those fonts being added are not publically available we, as a policy, will not add more pre-defined fonts in the core distribution of the library.