| 98 |
- |
1 |
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
|
|
|
2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>3.8. Text Fonts</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="concepts.html" title="Chapter 3. PHPlot Concepts" /><link rel="prev" href="conc-otherelements.html" title="3.7. Other Plot Elements" /><link rel="next" href="conc-errors.html" title="3.9. Error Handling" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.8. Text Fonts</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="conc-otherelements.html">Prev</a> </td><th width="60%" align="center">Chapter 3. PHPlot Concepts</th><td width="20%" align="right"> <a accesskey="n" href="conc-errors.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="conc-text"></a>3.8. Text Fonts</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>
|
|
|
3 |
This section contains information about using text fonts in PHPlot.
|
|
|
4 |
See <a class="xref" href="ref-textfonts.html" title="6.6. Text Fonts">Section 6.6, “Text Fonts”</a> for PHPlot functions used with text
|
|
|
5 |
fonts.
|
|
|
6 |
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-text-overview"></a>3.8.1. Overview</h3></div></div></div><p>
|
|
|
7 |
PHPlot supports both built-in GD fonts and TrueType fonts (if available on
|
|
|
8 |
your system).
|
|
|
9 |
TrueType fonts generally produce higher quality text, but using them
|
|
|
10 |
requires more internal computations. The built-in GD fonts are faster
|
|
|
11 |
to render, but are limited to one typeface and 5 available sizes.
|
|
|
12 |
TrueType fonts can be drawn at any size and angle, and many typefaces are
|
|
|
13 |
available.
|
|
|
14 |
On most systems, TrueType fonts are anti-aliased for improved appearance,
|
|
|
15 |
but under some conditions the GD fonts may be easier to read.
|
|
|
16 |
TrueType fonts support much wider character sets, including special
|
|
|
17 |
symbols, while the GD fonts are more limited.
|
|
|
18 |
</p><p>
|
|
|
19 |
|
|
|
20 |
The following figure shows the built-in GD fonts plus a sample TrueType
|
|
|
21 |
font. (Depending on how you are viewing this manual, the sizes of the
|
|
|
22 |
fonts in this figure might differ from how they would look in a PHPlot
|
|
|
23 |
image. For more on font sizes, see the notes with <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a>.)
|
|
|
24 |
</p><div class="informalfigure"><div class="mediaobject"><img src="images/fonts.png" alt="A sample of the fonts" /></div></div><p>
|
|
|
25 |
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-text-elements"></a>3.8.2. Text Element Names</h3></div></div></div><p>
|
|
|
26 |
Each type of text available in PHPlot has an <span class="emphasis"><em>element
|
|
|
27 |
name</em></span>. When selecting text fonts with <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a> and
|
|
|
28 |
related functions, you use the element name to indicate what type of text
|
|
|
29 |
you are configuring. The following table lists the PHPlot text element names.
|
|
|
30 |
</p><div class="informaltable"><table summary="Text element names" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Element Name</th><th>Used for</th></tr></thead><tbody><tr><td>generic</td><td>Pie chart labels, error image text, message image text</td></tr><tr><td>legend</td><td>Text in the legend (<a class="xref" href="SetLegend.html" title="SetLegend"><span class="refentrytitle">SetLegend</span></a>)</td></tr><tr><td>title</td><td>Main plot title (<a class="xref" href="SetTitle.html" title="SetTitle"><span class="refentrytitle">SetTitle</span></a>)</td></tr><tr><td>x_label</td><td>X tick labels and X data labels</td></tr><tr><td>y_label</td><td>Y tick labels and Y data labels</td></tr><tr><td>x_title</td><td>X axis title (<a class="xref" href="SetXTitle.html" title="SetXTitle"><span class="refentrytitle">SetXTitle</span></a>)</td></tr><tr><td>y_title</td><td>Y axis title (<a class="xref" href="SetYTitle.html" title="SetYTitle"><span class="refentrytitle">SetYTitle</span></a>)</td></tr></tbody></table></div><p>
|
|
|
31 |
Notes: <code class="literal">generic</code> is also used for text drawn from a callback
|
|
|
32 |
when no font is specified. See <a class="xref" href="callbacks.html#callbacks-drawing" title="4.4.5. Using Callbacks to Annotate Plots">Section 4.4.5, “Using Callbacks to Annotate Plots”</a>
|
|
|
33 |
and <a class="xref" href="dev-internal.html#DrawText">DrawText</a>. Although <code class="literal">generic</code> is
|
|
|
34 |
used for error image text, changing the font or size has no effect because
|
|
|
35 |
the error handler resets the font to the default before displaying the error.
|
|
|
36 |
Message image text refers to <a class="xref" href="DrawMessage.html" title="DrawMessage"><span class="refentrytitle">DrawMessage</span></a>.
|
|
|
37 |
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-text-fonts"></a>3.8.3. TrueType Font Selection</h3></div></div></div><p>
|
|
|
38 |
PHPlot text can use built-in GD fonts or TrueType fonts. When using GD
|
|
|
39 |
fonts, you specify a font name as a number between 1 and 5. This selects
|
|
|
40 |
from 5 built-in GD fonts.
|
|
|
41 |
When using TrueType fonts, you need to specify a font filename.
|
|
|
42 |
The rest of this section discusses only TrueType fonts.
|
|
|
43 |
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
44 |
The material on specifying font files for PHPlot applies to releases
|
|
|
45 |
starting with PHPlot-5.1.3. Through PHPlot-5.1.2, you generally need to specify
|
|
|
46 |
the full pathname of a font file, or the full path of a font directory.
|
|
|
47 |
</p></div><p>
|
|
|
48 |
On Windows systems, you need to use the font filename, not the font name.
|
|
|
49 |
You can get the font filename using Control Panel - Fonts.
|
|
|
50 |
For example, Windows applications may display "Arial Black", or "Arial
|
|
|
51 |
Black (TrueType)" as a font name, but the actual font filename is "ariblk.ttf".
|
|
|
52 |
Since GD knows to look for fonts in the Windows font directory, you will
|
|
|
53 |
not need to specify a full pathname to font files, unless the font is
|
|
|
54 |
installed in some other directory.
|
|
|
55 |
</p><p>
|
|
|
56 |
On Windows, you can use the "Character Map" system tool to examine a font.
|
|
|
57 |
This can also be used to find the Unicode character code of a special character.
|
|
|
58 |
These will be displayed in hexadecimal, for example U+20AC for the Euro.
|
|
|
59 |
See <a class="xref" href="conc-text.html#conc-text-special" title="3.8.5. Using Extended Characters">Section 3.8.5, “Using Extended Characters”</a>
|
|
|
60 |
for more information on using special characters.
|
|
|
61 |
</p><p>
|
|
|
62 |
Here are some font selection examples for Windows:
|
|
|
63 |
</p><pre class="programlisting"># For titles, use Arial Bold Italic at 14 points:
|
|
|
64 |
$plot->SetFontTTF('title', 'ARIALBI.TTF', 14)
|
|
|
65 |
# For X Title, use Verdana at 12 points:
|
|
|
66 |
$plot->SetFontTTF('x_title', 'VERDANA.TTF', 12)
|
|
|
67 |
</pre><p>
|
|
|
68 |
</p><p>
|
|
|
69 |
On some Linux and similar systems, GD is able to find fonts specified
|
|
|
70 |
without paths, but on other systems you will have to specify a font
|
|
|
71 |
directory with either <a class="xref" href="SetTTFPath.html" title="SetTTFPath"><span class="refentrytitle">SetTTFPath</span></a> or as part of the
|
|
|
72 |
font name in <a class="xref" href="SetFontTTF.html" title="SetFontTTF"><span class="refentrytitle">SetFontTTF</span></a>.
|
|
|
73 |
If you specify a full pathname to a font, you must also supply the extension
|
|
|
74 |
(.ttf); you may omit the extension when relying on GD to find the font.
|
|
|
75 |
Remember that font filenames are case sensitive on most of these systems.
|
|
|
76 |
</p><p>
|
|
|
77 |
The font search path for GD (bundled with PHP) includes the following
|
|
|
78 |
directories on Linux and similar systems:
|
|
|
79 |
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="filename">/usr/X11R6/lib/X11/fonts/TrueType</code></p></li><li class="listitem"><p><code class="filename">/usr/X11R6/lib/X11/fonts/truetype</code></p></li><li class="listitem"><p><code class="filename">/usr/X11R6/lib/X11/fonts/TTF</code></p></li><li class="listitem"><p><code class="filename">/usr/share/fonts/TrueType</code></p></li><li class="listitem"><p><code class="filename">/usr/share/fonts/truetype</code></p></li><li class="listitem"><p><code class="filename">/usr/openwin/lib/X11/fonts/TrueType</code></p></li></ul></div><p>
|
|
|
80 |
If your system has TrueType fonts in one of those directories, you can
|
|
|
81 |
select them with a filename only. If not, you must use a full directory path
|
|
|
82 |
in either the font name or with SetTTFPath.
|
|
|
83 |
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
84 |
The environment variable <code class="envar">GDFONTPATH</code> can be defined to
|
|
|
85 |
contain a list of directories (separated by a colon ':') to search for
|
|
|
86 |
fonts. If defined, this replaces the above list.
|
|
|
87 |
</p></div><p>
|
|
|
88 |
Your Linux system may include a tool for examining fonts. One such tool is
|
|
|
89 |
<span class="application">gucharmap</span>.
|
|
|
90 |
This can also be used to find the Unicode character code of a special character.
|
|
|
91 |
These may be displayed in hexadecimal, for example U+20AC for the Euro.
|
|
|
92 |
See the next section for more information on using special characters.
|
|
|
93 |
</p><p>
|
|
|
94 |
Here are some font selection examples for Linux:
|
|
|
95 |
</p><pre class="programlisting"># On systems with fonts in an expected place, like Slackware Linux,
|
|
|
96 |
# just use the font filename:
|
|
|
97 |
# For titles, use Liberation Sans Bold Italic at 14 points:
|
|
|
98 |
$plot->SetFontTTF('title', 'LiberationSans-BoldItalic.ttf', 14)
|
|
|
99 |
# For X Title, use DejaVuSans Bold at 12 points:
|
|
|
100 |
$plot->SetFontTTF('x_title', 'DejaVuSans-Bold.ttf', 12)
|
|
|
101 |
|
|
|
102 |
# Ubuntu and Debian use subdirectories under a searched path.
|
|
|
103 |
# You can use a partial path here.
|
|
|
104 |
$plot->SetFontTTF('x_title', 'liberation/LiberationSans-Regular.ttf', 12)
|
|
|
105 |
# Note: Older Ubuntu/Debian used the path ttf-liberation/...
|
|
|
106 |
|
|
|
107 |
# Fedora uses subdirectories which are not under a searched path.
|
|
|
108 |
# You must use full paths here.
|
|
|
109 |
$plot->SetTTFPath('/usr/share/fonts/liberation/');
|
|
|
110 |
$plot->SetFontTTF('x_title', 'LiberationSans-Regular.ttf', 12)
|
|
|
111 |
</pre><p>
|
|
|
112 |
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
113 |
Your Linux system probably has a package called <code class="literal">fontconfig</code>
|
|
|
114 |
which is used to provide more consistent access to fonts. But even if your
|
|
|
115 |
system uses a version of the <code class="literal">gd</code> library which is built
|
|
|
116 |
with <code class="literal">fontconfig</code> (and the one bundled with PHP does not),
|
|
|
117 |
<span class="emphasis"><em>PHP does not use <code class="literal">fontconfig</code></em></span>.
|
|
|
118 |
Therefore PHPlot needs to be able to locate font files using other means.
|
|
|
119 |
</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-text-defaultfont"></a>3.8.4. Default TrueType Font</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
120 |
This section applies starting with PHPlot-5.1.3.
|
|
|
121 |
</p></div><p>
|
|
|
122 |
If you try to use TrueType text without specifying a font name, PHPlot will
|
|
|
123 |
use the default font. You can set the default font with
|
|
|
124 |
<a class="xref" href="SetDefaultTTFont.html" title="SetDefaultTTFont"><span class="refentrytitle">SetDefaultTTFont</span></a>. If you do not set a default font,
|
|
|
125 |
PHPlot tries to locate a sans-serif font to use. Here are the font names
|
|
|
126 |
that PHPlot tries in order. First it tries the filename alone, letting GD
|
|
|
127 |
use its search path, and then it tries with the default font path, as set
|
|
|
128 |
with <a class="xref" href="SetTTFPath.html" title="SetTTFPath"><span class="refentrytitle">SetTTFPath</span></a>.
|
|
|
129 |
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
|
|
130 |
<code class="filename">LiberationSans-Regular.ttf</code>
|
|
|
131 |
- Likely to work on Linux and other systems with a correct GD font search path.
|
|
|
132 |
</p></li><li class="listitem"><p>
|
|
|
133 |
<code class="filename">Verdana.ttf, Arial.ttf, Helvetica.ttf</code>
|
|
|
134 |
- One of these is going to work on Windows, maybe other systems too.
|
|
|
135 |
</p></li><li class="listitem"><p>
|
|
|
136 |
<code class="filename">liberation/LiberationSans-Regular.ttf,
|
|
|
137 |
ttf-liberation/LiberationSans-Regular.ttf</code>
|
|
|
138 |
- This is for Debian, Ubuntu, and similar (the first is for newer releases,
|
|
|
139 |
such as Ubuntu 12.04 and later, and the second is for older releases).
|
|
|
140 |
</p></li><li class="listitem"><p>
|
|
|
141 |
<code class="filename">benjamingothic.ttf</code>
|
|
|
142 |
- The original PHPlot default, for compatibility.
|
|
|
143 |
</p></li></ul></div><p>
|
|
|
144 |
The last item on the list is used regardless of whether it can be found or
|
|
|
145 |
not. This means if you enable TrueType fonts without setting a default, and
|
|
|
146 |
get a fatal error from PHPlot that it can't find the font benjamingothic.ttf,
|
|
|
147 |
this means PHPlot was unable to find any of the standard fonts in its list.
|
|
|
148 |
On that system, then, you must provide either a font directory, or use full
|
|
|
149 |
font pathnames.
|
|
|
150 |
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-text-special"></a>3.8.5. Using Extended Characters</h3></div></div></div><p>
|
|
|
151 |
You can include non-ASCII characters in your PHPlot labels and titles.
|
|
|
152 |
This includes characters from languages other than English, accented
|
|
|
153 |
characters, and special symbols.
|
|
|
154 |
</p><p>
|
|
|
155 |
PHPlot itself does not do any special processing of text strings, so you
|
|
|
156 |
should refer to the PHP GD and Image Functions reference for more
|
|
|
157 |
information, in particular <code class="function">imagettftext()</code>.
|
|
|
158 |
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
159 |
This mostly only works with TrueType fonts. The built-in GD fonts do
|
|
|
160 |
have some extended characters, but they are encoded in ISO 8859-2 which is
|
|
|
161 |
probably not what you might expect, and the GD font routines do not support
|
|
|
162 |
special character entities.
|
|
|
163 |
</p></div><p>
|
|
|
164 |
To use extended characters in your PHPlot text strings, you need a TrueType
|
|
|
165 |
font that contains the characters you want. Ideally, you want a Unicode
|
|
|
166 |
font. You might have to examine the font using an operating system-specific
|
|
|
167 |
tool to see if your characters are present and to find their numeric values.
|
|
|
168 |
</p><p>
|
|
|
169 |
There are three basic ways to include extended characters in your text
|
|
|
170 |
strings. The examples below use the Euro character, which is decimal
|
|
|
171 |
Unicode value 8364.
|
|
|
172 |
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
|
|
173 |
Use HTML-type character entities with decimal numeric encoding. For
|
|
|
174 |
example, the Unicode Euro symbol is: &#8364;
|
|
|
175 |
</p></li><li class="listitem"><p>
|
|
|
176 |
Include the UTF-8 encoding of the Unicode value in your string as a series
|
|
|
177 |
of hex escapes. For example, the Euro symbol is: "\xe2\x82\xac".
|
|
|
178 |
</p></li><li class="listitem"><p>
|
|
|
179 |
Include the UTF-8 encoding of the Unicode value directly in your character
|
|
|
180 |
string. We can't show you an example of what this looks like, or tell you
|
|
|
181 |
how to enter these characters, because it depends on your own hardware,
|
|
|
182 |
operating system, text editor, and locale.
|
|
|
183 |
</p></li></ul></div><p>
|
|
|
184 |
</p><p>
|
|
|
185 |
The first two of these options are shown in the example below, both of which
|
|
|
186 |
set the Y axis title to "Items per €100".
|
|
|
187 |
</p><pre class="programlisting">$plot->SetYTitle("Items per &#8364;100"); # Numeric character entity
|
|
|
188 |
$plot->SetYTitle("Items per \xe2\x82\xac100"); # UTF-8 encoding
|
|
|
189 |
</pre><p>
|
|
|
190 |
</p><p>
|
|
|
191 |
You can also use PHP functions to encode your characters for including in
|
|
|
192 |
PHPlot text strings. See the PHP documentation for the functions
|
|
|
193 |
<code class="function">html_entity_decode()</code>
|
|
|
194 |
and <code class="function">iconv()</code>.
|
|
|
195 |
Here are some examples (sent in by SourceForge user 'kalvaro'):
|
|
|
196 |
</p><pre class="programlisting"># Encode the Euro symbol into UTF-8:
|
|
|
197 |
$chars = html_entity_decode('&euro;', ENT_NOQUOTES, 'UTF-8');
|
|
|
198 |
|
|
|
199 |
# Use iconv() to convert a character value xA4 in ISO-8859-15 to UTF:
|
|
|
200 |
$chars = iconv('iso-8859-15', 'utf-8', chr(0xA4));
|
|
|
201 |
</pre><p>
|
|
|
202 |
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
|
|
|
203 |
GD does not support using named character entities such as &euro; directly
|
|
|
204 |
in strings - they must be numerically encoded as described above.
|
|
|
205 |
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="conc-otherelements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concepts.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="conc-errors.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.7. Other Plot Elements </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.9. Error Handling</td></tr></table></div></body></html>
|