SetFont

SetFont
Prev	PHPlot Function Reference	Next

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'.

$font

Selects the font to use. For TrueType fonts, this is either the full pathname of a TrueType font filename, or the filename (without path) if the font file is either located in the default TrueType font directory set with SetTTFPath or can be found by GD using its default search rules. An empty string or NULL can be specified to use the default TrueType font.

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

See also Section 3.8, “Text Fonts”.

The generic font is used for pie chart segment labels, message image text (see DrawMessage), error image text, and can be used from callbacks (see Section 4.4.5, “Using Callbacks to Annotate Plots”). However, changing this font has no effect on error image text, because the PHPlot error handler resets the font to the default before displaying the error.

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.

Element	Default Built-in Font
generic	2
legend	2
title	5
x_label	1
y_label	1
x_title	3
y_title	3

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

Element	Default TrueType Font Size (points)
generic	8
legend	8
title	14
x_label	6
y_label	6
x_title	10
y_title	10

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

Starting with PHPlot-5.1.3, TrueType fonts are validated by trying to use the font with a non-drawing operation, rather than by seeing if the font file exists. See Section 3.8.3, “TrueType Font Selection” for more information.

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.