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 Section 3.4.1.)
The drawbacks, on the other hand, with bitmap fonts are quite a few
they look quite crude and are only available in a few sizes
italic font style is not supported for bitmap fonts
they only support 7-bit ASCII characters
they only support 0 and 90 degree rotated text
You can read more about how to use and select among the different fonts in Chapter 8
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)
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)
Open jpg-config.inc.php for editing
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.
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\)
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.
You can also chose to install the freely available Vera Bitstream TTF
fonts available from http://www.gnome.org/fonts/
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
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:
If LANGUAGE_CYRILLIC is false no specific handling of
Cyrillic characters at all will be done.
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.
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 | $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)
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.