SetFont

SetFont — Select which font to use for a plot element

Synopsis

$plot->SetFont($elem, $font, [$size], [$line_spacing])
    

Description

SetFont selects the font and size to use for one plot element (for example, the title). This functions works differently depending on whether or not you are using TrueType fonts. If using TrueType fonts, call either SetDefaultTTFont or SetUseTTF before calling SetFont.

Parameters

$elem

The name of the element to change the font for. Use one of the following strings: 'title', 'legend', 'generic', 'x_label', 'y_label', 'x_title', or 'y_title'. (The 'generic' font is currently used for pie chart percentage labels and error message images.)

$font

Selects the font to use. For TrueType fonts, this is the filename (without path, if the font file is in the default TrueType font directory as set with SetTTFPath, or a full pathname) of the TrueType font file. An empty string or NULL can be used to keep the same TrueType font and change the size. For built-in GD fonts, this is a number between 1 and 5 which selects one of the built-in GD fonts. Font 1 is the smallest, and font 5 is the largest.

$size

The font size in points for TrueType fonts. Ignored for built-in GD fonts. If not specified, a default value of 12 is used. See note below.

$line_spacing

Optional line spacing adjustment for this text element. This is interpreted differently for GD and TrueType text. See SetLineSpacing for details. If not specified, the value set by SetLineSpacing is used.

Notes

When using built-in GD fonts, the default fonts are shown in the following table, where font 1 is the smallest font and font 5 is the biggest font.

ElementDefault Built-in Font
generic2
legend2
title5
x_label1
y_label1
x_title3
y_title3

When using TrueType fonts, the default font sizes are shown in the following table. Use SetDefaultTTFont to set the default TrueType font.

ElementDefault TrueType Font Size (points)
generic8
legend8
title14
x_label6
y_label6
x_title10
y_title10

Simultaneous use of GD and TrueType font text is allowed in the same plot. To mix font types, use SetFontGD and SetFontTTF to specify the font and font type of an element, instead of using SetFont.

SetFont implicitly uses the default font type. When a PHPlot object instance is created, the default font type is GD. Using SetUseTTF(True), or selecting a default font with SetDefaultTTFont, sets the default font type to TrueType. Using SetUseTTF(False) sets the default font type back to GD. Either of these three operations will also reset all current text elements to the defaults indicated above, negating any prior SetFont, SetFontGD, or SetFontTTF calls. Note that SetTTFPath, which selects the directory where TrueType fonts can be found, does not affect the default font type nor does it change any existing font selections.

Although PHP documents the TrueType font sizes as being given in points (where there are about 72 points per inch), it doesn't know the output device resolution, so it just assumes a fixed resolution of 72 pixels per inch. As a result, the TrueType font size argument actually measures the approximate font height in pixels. For example, if you use $size=18, the text will be about 18 pixels high in the user's browser. The actual size seen by the user will depend on the resolution of the user's display. On a 72 pixels per inch display, the text size will be 18 points, but at 96 pixels per inch it would only be 13.5 points.

History

Simultaneous use of GD and TrueType font text was added at PHPlot-5.0.6. Through PHPlot-5.0.5, all text in a plot used GD fonts, or all text used TrueType fonts.

The line_spacing parameter was added at PHPlot-5.0.6 to allow finer control over the line spacing for different elements. Through PHPlot-5.0.5, the same line spacing was used for all text elements.

The described behavior for finding TrueType font files (first using the name as given, then looking in the SetTTFPath font directory) was implemented in PHPlot-5.0rc3.