Installing and configuring Font support

JpGraph supports two types of fonts, bitmap and TTF fonts. The advantage with bitmap fonts are that they are supported from within the library without further configuration. TTF fonts require some configuration and possible installation of the actual TTF font specification file. (For more on installing TTF fonts see Configuring TTF fonts.)

The drawbacks, on the other hand, with bitmap fonts are quite a few

You can read more about how to use and select among the different fonts in Chapter 8. Text and font handling

Configuring TTF fonts

Note

This could be considered an optional section since the library will work even without TTF fonts. However, for th reasons listed previously it is strongly recommended that TTF support is configured.

In the following we will assume that the FreeType library is enabled and verified in the PHP installation (See Figure 3.2. phphinfo() GD-Information)

Due to various legal issues no TTF fonts are included in the distribution of JpGraph since many commonly used TTF font files are copyrighted and there distribution restricted. For the most commonly used WEB-fonts (the Microsoft Core Fonts) the status is unclear. For many years Microsoft distributed them freely but they are no longer available from Microsofts home page. Instead they are available from http://corefonts.sourceforge.net/

There are however a fair amount of freely available high quality TTF fonts (see below). The first thing needed is to make sure that the path defines in the file jpg-config.inc.php corresponds to the server setup (so that the library can find the font files)

  1. Open jpg-config.inc.php for editing

  2. Locate the define TTF_DIR (this is the define that possible needs updating depending on your system). By default this path will have a sensible values depending on if the library is installed on a Windows or a Unix system.

  3. If you are on a Windows platform you can just point the TTF directory path in JpGraph to use the standard Window font directory (e.g C:\windows\fonts\)

  4. If you are on a Unix platform, which may not have any TTF fonts installed, you can download and install the core MS WEB-initiative fonts from http://corefonts.sourceforge.net/ many Linux distributions also have automatic ways to install these fonts. These fonts were put in the public domain by the Microsoft Corporation but they are no longer available directly from Microsoft.

  5. You can also chose to install the freely available Vera Bitstream TTF fonts available from http://www.gnome.org/fonts/

  6. You can also chose to install the freely available DejaVu TTF fonts http://sourceforge.net/projects/dejavu

JpGraph uses a standard naming convention for the TTF font files in order to be able to find the correct font file that correspond to a particular font family. This naming convention follows the standard naming of the available font files from the distributions listed above.

If the installation of the library is made on a computer running MS Windows then it is recommended to use the already available font files in Windows (usually located in C:\WINDOWS\FONTS).

If the installation is made on a UNIX derivate running X11 then the font location can differ between versions and UNIX brands. One commonly used path in modern installations are "/usr/share/fonts/truetype/" (In older installations it was common to put the truetype fonts under "/usr/X11R6/lib/X11/fonts/truetype/".)

Finally we note that it is possible to install additional fonts not natively supported by the library by using the SetUserFont() family of methods. (In theory it is also possible to patch the jpgraph source files to include support for other font files natively but since this requires code modifications of the library we do not discuss this further here in the introduction.)

Freely available TTF fonts can be found, for example, from

Using non-latin based fonts with JpGraph

In addition to European fonts it is also possible to use non-latin based fonts such as Cyrillic, Japanese, Chinese, Hebrew and Greek. For any of these languages a suitable TTF font that supports the non-latin based language must be made available to the library. Some specific rules also applies to each of the supported languages due to the necessary character encoding needed due to different convention when writing the character for some languages.

  • For Cyrillic support the define LANGUAGE_CYRILLIC in jpg-config.php must be set to true. It is then possible to use a suitable Cyrillic font as replacement of the ordinary font. This setting combined with the CYRILLIC_FROM_WINDOWS and LANGUAGE_CHARSET is used to fine tune the handling cyrillic input. The rules are as follows:

    1. If LANGUAGE_CYRILLIC is false no specific handling of Cyrillic characters at all will be done.

    2. If CYRILLIC_FROM_WINDOWS is true then it will be assumed the input coding by default is encoded using WINDOWS-1251.

      The conversion is then done via a call to convert_cyr_string($aTxt, 'w', 'k') where $aTxt is replaced with the input string to be encoded.

    3. If CYRILLIC_FROM_WINDOWS is false then it will be assumed the input coding by default is encoded using KOI8-R.

      The conversion is then done via the sequence of callls

      1
      2
      3
      4
      
      <?php
      $isostring = convert_cyr_string($aTxt, "k", "i");
      $unistring = LanguageConv::iso2uni($isostring);
      ?>

      in oder to get a proper utf-8 internal encoding (internally the library only uses utf-8 encoding)

    4. LANGUAGE_CHARSET can be used to dynamically adjust the conversion of the input character set when using cyrillic characters. This constant is used to auto-detect whether cyrillic conversion is really necessary if enabled (via the If LANGUAGE_CYRILLIC=true) . This constant can be set to a variable containing the currently used character input set .A typical such string would be 'UTF-8' or 'utf-8' (the comparison is case-insensitive). If this charset is not 'koi8-r' nor 'windows-1251' derivate then no conversion is done.

  • For Chinese character set JpGraph supports both BIG5 and GB2312 encoding. For BIG5 encoding the PHP installation must have support for the "iconv()" function. Furthermore the define CHINESE_TTF_FONT must be set to the name of the Chinese BIG5 font that is to be used. By default this is set to "bkai00mp.ttf". To use the Chinese BIG5 font in the scripts one must then specify the font family as FF_CHINESE.

    To use the alternative font files "simsun.ttc" and "simhei.ttf" (which uses the GB2312 encoding) the only step needed is to install those fonts in the normal TTF font directory and then specify the font family as FF_SIMSUN, the "simhei.ttf" is used when the font style is specified as FS_BOLD.