ChartDirector 7.0 (PHP Edition)

Font Specification

Font Name

In ChartDirector, the font name is simply the file name that contains the font. For example, under the Windows platform, the "Arial" font is "arial.ttf", while the "Arial Bold" font is "arialbd.ttf".

Font Location

ChartDirector on Windows relies on the operating system font files in the "[windows]\Fonts" directory. You may use the File Explorer to see what fonts are available and their file names.

ChartDirector on MacOS relies on operating system font files in "/Library/Fonts" and "/System/Library/Fonts". You may use the Finder to see what fonts are available and their file names.

In additional to the OS fonts, ChartDirector also supports a private fonts subdirectory, which is the "fonts" subdirectory under the directory that contains the ChartDirector library (chartdir??.dll, or libchartdir.dylib, depending on the OS). This allows using fonts that are not installed in the OS.

On Linux and FreeBSD, there is no standard font directory, so ChartDirector only uses the private fonts subdirectory. To ensure the sample code can run, ChartDirector for Linux and FreeBSD come with several font files in the private fonts subdirectory. Since ChartDirector 6.0, the font files included are the regular, bold, italic and bold italic variants of the "Liberation Sans" and "Liberation Serif" fonts. They are metric compatible with the "Arial" and "Times New Roman" fonts.

If you want ChartDirector to search other directories for the font files, you may list the directories in an environment variable called "FONTPATH".

If you specify an absolute path name for the font file, ChartDirector will use the absolute path name and will not search other directories.

Built-In Font Mapping

The sample programs that come with ChartDirector use only the Arial and Times New Roman fonts based their file name on Windows, which are:

Windows Font File NameFont Style
arialbd.ttfArial Bold
ariali.ttfArial Italic
arialbi.ttfArial Bold Italic
times.ttfTimes New Roman
timesbd.ttfTimes New Roman Bold
timesi.ttfTimes New Roman Italic
timesbi.ttfTimes New Roman Bold Italic

As mentioned in the previous section, on Linux and FreeBSD, these fonts may not exist, and ChartDirector comes with the Liberation family of fonts instead. To ensure the sample code can run unmodified, if ChartDirector cannot find these fonts, it will substitute them with the corresponding Liberation fonts.

On MacOS, the Arial or Times New Roman fonts may use different file names depending on the MacOS version. ChartDirector will map the Windows file name for these two font families to the corresponding MacOS file names.

Artificial Boldening and Italicizing

Whereas most popular font comes with different styles for regular, bold, italic and bold italic, some fonts only come with one style. For example, the Monotype Corsiva font that comes with MS Office only has the regular style (mtcorsva.ttf). For these cases, you may append "Bold" and/or "Italic" after the font file name (separated with a space). ChartDirector will then artificially bolden and/or italicize the font. For example, you may specify the font name as "mtcorsva.ttf Bold".

Font List

Instead of specifying a single font file as the font name, you may specify a list of font files as the font name, separated by semi-colons. This is useful when using international characters that are only available in some fonts.

For example, if you would like to use the Arial font ("arial.ttf") for western characters, and the MingLiu font "mingliu.ttc" for Chinese characters (since the Arial font does not have Chinese characters), you may specify the font name as "arial.ttf;mingliu.ttc". In this case, ChartDirector will try the Arial font first. If it cannot find a certain character there, it will try the MingLiu font.

Indirect Font Names

ChartDirector supports several special keywords for specifying the font name indirectly. When these keywords are used as font names, ChartDirector will look up the actual font names from a font table. The keywords are as follows:

"normal"This default normal font, which is the first font in the font table. This is initially mapped to "arial.ttf" (Arial).
"bold"The default bold font, which is the second font in the font table. This is initially mapped to "arialbd.ttf" (Arial Bold).
"italic"The default italic font, which is the third font in the font table. This is initially mapped to "ariali.ttf" (Arial Italic).
"boldItalic"The default bold-italic font, which is the fourth font in the font table. This is initially mapped to "arialbi.ttf" (Arial Bold Italic).
"fontN"The (N + 1)th font in the font table (the first font is "font0").

The font table can be modified using BaseChart.setFontTable or DrawArea.setFontTable.

The advantage of using indirect font names is that you can change the fonts fonts in your charts in one place.

Font Index

Most font files contain one font. However, it is possible a font file contains multiple fonts (that is, a font collection). For example, in True Type fonts, font files with extension ".ttc" may represent a font collection.

If a font file contains multiple font, the font index can be used to specify which font to use. By default, the font index is 0, which means the first font in the font file will be used.

Font Size

The font size decides how big a font will appear in the image. The font size is expressed in a font unit called points. This is the same unit used in common word processors.

Instead of specifying font size, some ChartDirector API (eg. TextBox.setFontSize) allow you to specify font height and font width separately. You may use different point sizes for font height and font width to create special effects.

Font Color

This is the color to draw the font. (See Color Specification on how colors are represented in ChartDirector.)

Font Angle

This is the angle in degrees by which the font should be rotated anti-clockwise.

Vertical Layout

By default, text are laid out horizontally, with characters being drawn from left to right.

ChartDirector also supports vertical layout, with characters being drawn from top to bottom. For example, you may use BaseChart.addText to add text that are laid out vertically. Vertical layout is common for oriental languages such as Chinese, Japanese and Korean.