Blame | Last modification | View Log | RSS feed
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?><!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>This section contains information about using text fonts in PHPlot.See <a class="xref" href="ref-textfonts.html" title="6.6. Text Fonts">Section 6.6, “Text Fonts”</a> for PHPlot functions used with textfonts.</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>PHPlot supports both built-in GD fonts and TrueType fonts (if available onyour system).TrueType fonts generally produce higher quality text, but using themrequires more internal computations. The built-in GD fonts are fasterto render, but are limited to one typeface and 5 available sizes.TrueType fonts can be drawn at any size and angle, and many typefaces areavailable.On most systems, TrueType fonts are anti-aliased for improved appearance,but under some conditions the GD fonts may be easier to read.TrueType fonts support much wider character sets, including specialsymbols, while the GD fonts are more limited.</p><p>The following figure shows the built-in GD fonts plus a sample TrueTypefont. (Depending on how you are viewing this manual, the sizes of thefonts in this figure might differ from how they would look in a PHPlotimage. For more on font sizes, see the notes with <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a>.)</p><div class="informalfigure"><div class="mediaobject"><img src="images/fonts.png" alt="A sample of the fonts" /></div></div><p></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>Each type of text available in PHPlot has an <span class="emphasis"><em>elementname</em></span>. When selecting text fonts with <a class="xref" href="SetFont.html" title="SetFont"><span class="refentrytitle">SetFont</span></a> andrelated functions, you use the element name to indicate what type of textyou are configuring. The following table lists the PHPlot text element names.</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>Notes: <code class="literal">generic</code> is also used for text drawn from a callbackwhen 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>and <a class="xref" href="dev-internal.html#DrawText">DrawText</a>. Although <code class="literal">generic</code> isused for error image text, changing the font or size has no effect becausethe error handler resets the font to the default before displaying the error.Message image text refers to <a class="xref" href="DrawMessage.html" title="DrawMessage"><span class="refentrytitle">DrawMessage</span></a>.</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>PHPlot text can use built-in GD fonts or TrueType fonts. When using GDfonts, you specify a font name as a number between 1 and 5. This selectsfrom 5 built-in GD fonts.When using TrueType fonts, you need to specify a font filename.The rest of this section discusses only TrueType fonts.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The material on specifying font files for PHPlot applies to releasesstarting with PHPlot-5.1.3. Through PHPlot-5.1.2, you generally need to specifythe full pathname of a font file, or the full path of a font directory.</p></div><p>On Windows systems, you need to use the font filename, not the font name.You can get the font filename using Control Panel - Fonts.For example, Windows applications may display "Arial Black", or "ArialBlack (TrueType)" as a font name, but the actual font filename is "ariblk.ttf".Since GD knows to look for fonts in the Windows font directory, you willnot need to specify a full pathname to font files, unless the font isinstalled in some other directory.</p><p>On Windows, you can use the "Character Map" system tool to examine a font.This can also be used to find the Unicode character code of a special character.These will be displayed in hexadecimal, for example U+20AC for the Euro.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>for more information on using special characters.</p><p>Here are some font selection examples for Windows:</p><pre class="programlisting"># For titles, use Arial Bold Italic at 14 points:$plot->SetFontTTF('title', 'ARIALBI.TTF', 14)# For X Title, use Verdana at 12 points:$plot->SetFontTTF('x_title', 'VERDANA.TTF', 12)</pre><p></p><p>On some Linux and similar systems, GD is able to find fonts specifiedwithout paths, but on other systems you will have to specify a fontdirectory with either <a class="xref" href="SetTTFPath.html" title="SetTTFPath"><span class="refentrytitle">SetTTFPath</span></a> or as part of thefont name in <a class="xref" href="SetFontTTF.html" title="SetFontTTF"><span class="refentrytitle">SetFontTTF</span></a>.If you specify a full pathname to a font, you must also supply the extension(.ttf); you may omit the extension when relying on GD to find the font.Remember that font filenames are case sensitive on most of these systems.</p><p>The font search path for GD (bundled with PHP) includes the followingdirectories on Linux and similar systems:</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>If your system has TrueType fonts in one of those directories, you canselect them with a filename only. If not, you must use a full directory pathin either the font name or with SetTTFPath.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The environment variable <code class="envar">GDFONTPATH</code> can be defined tocontain a list of directories (separated by a colon ':') to search forfonts. If defined, this replaces the above list.</p></div><p>Your Linux system may include a tool for examining fonts. One such tool is<span class="application">gucharmap</span>.This can also be used to find the Unicode character code of a special character.These may be displayed in hexadecimal, for example U+20AC for the Euro.See the next section for more information on using special characters.</p><p>Here are some font selection examples for Linux:</p><pre class="programlisting"># On systems with fonts in an expected place, like Slackware Linux,# just use the font filename:# For titles, use Liberation Sans Bold Italic at 14 points:$plot->SetFontTTF('title', 'LiberationSans-BoldItalic.ttf', 14)# For X Title, use DejaVuSans Bold at 12 points:$plot->SetFontTTF('x_title', 'DejaVuSans-Bold.ttf', 12)# Ubuntu and Debian use subdirectories under a searched path.# You can use a partial path here.$plot->SetFontTTF('x_title', 'liberation/LiberationSans-Regular.ttf', 12)# Note: Older Ubuntu/Debian used the path ttf-liberation/...# Fedora uses subdirectories which are not under a searched path.# You must use full paths here.$plot->SetTTFPath('/usr/share/fonts/liberation/');$plot->SetFontTTF('x_title', 'LiberationSans-Regular.ttf', 12)</pre><p></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Your Linux system probably has a package called <code class="literal">fontconfig</code>which is used to provide more consistent access to fonts. But even if yoursystem uses a version of the <code class="literal">gd</code> library which is builtwith <code class="literal">fontconfig</code> (and the one bundled with PHP does not),<span class="emphasis"><em>PHP does not use <code class="literal">fontconfig</code></em></span>.Therefore PHPlot needs to be able to locate font files using other means.</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>This section applies starting with PHPlot-5.1.3.</p></div><p>If you try to use TrueType text without specifying a font name, PHPlot willuse the default font. You can set the default font with<a class="xref" href="SetDefaultTTFont.html" title="SetDefaultTTFont"><span class="refentrytitle">SetDefaultTTFont</span></a>. If you do not set a default font,PHPlot tries to locate a sans-serif font to use. Here are the font namesthat PHPlot tries in order. First it tries the filename alone, letting GDuse its search path, and then it tries with the default font path, as setwith <a class="xref" href="SetTTFPath.html" title="SetTTFPath"><span class="refentrytitle">SetTTFPath</span></a>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="filename">LiberationSans-Regular.ttf</code>- Likely to work on Linux and other systems with a correct GD font search path.</p></li><li class="listitem"><p><code class="filename">Verdana.ttf, Arial.ttf, Helvetica.ttf</code>- One of these is going to work on Windows, maybe other systems too.</p></li><li class="listitem"><p><code class="filename">liberation/LiberationSans-Regular.ttf,ttf-liberation/LiberationSans-Regular.ttf</code>- This is for Debian, Ubuntu, and similar (the first is for newer releases,such as Ubuntu 12.04 and later, and the second is for older releases).</p></li><li class="listitem"><p><code class="filename">benjamingothic.ttf</code>- The original PHPlot default, for compatibility.</p></li></ul></div><p>The last item on the list is used regardless of whether it can be found ornot. This means if you enable TrueType fonts without setting a default, andget a fatal error from PHPlot that it can't find the font benjamingothic.ttf,this means PHPlot was unable to find any of the standard fonts in its list.On that system, then, you must provide either a font directory, or use fullfont pathnames.</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>You can include non-ASCII characters in your PHPlot labels and titles.This includes characters from languages other than English, accentedcharacters, and special symbols.</p><p>PHPlot itself does not do any special processing of text strings, so youshould refer to the PHP GD and Image Functions reference for moreinformation, in particular <code class="function">imagettftext()</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This mostly only works with TrueType fonts. The built-in GD fonts dohave some extended characters, but they are encoded in ISO 8859-2 which isprobably not what you might expect, and the GD font routines do not supportspecial character entities.</p></div><p>To use extended characters in your PHPlot text strings, you need a TrueTypefont that contains the characters you want. Ideally, you want a Unicodefont. You might have to examine the font using an operating system-specifictool to see if your characters are present and to find their numeric values.</p><p>There are three basic ways to include extended characters in your textstrings. The examples below use the Euro character, which is decimalUnicode value 8364.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Use HTML-type character entities with decimal numeric encoding. Forexample, the Unicode Euro symbol is: &#8364;</p></li><li class="listitem"><p>Include the UTF-8 encoding of the Unicode value in your string as a seriesof hex escapes. For example, the Euro symbol is: "\xe2\x82\xac".</p></li><li class="listitem"><p>Include the UTF-8 encoding of the Unicode value directly in your characterstring. We can't show you an example of what this looks like, or tell youhow to enter these characters, because it depends on your own hardware,operating system, text editor, and locale.</p></li></ul></div><p></p><p>The first two of these options are shown in the example below, both of whichset the Y axis title to "Items per €100".</p><pre class="programlisting">$plot->SetYTitle("Items per &#8364;100"); # Numeric character entity$plot->SetYTitle("Items per \xe2\x82\xac100"); # UTF-8 encoding</pre><p></p><p>You can also use PHP functions to encode your characters for including inPHPlot text strings. See the PHP documentation for the functions<code class="function">html_entity_decode()</code>and <code class="function">iconv()</code>.Here are some examples (sent in by SourceForge user 'kalvaro'):</p><pre class="programlisting"># Encode the Euro symbol into UTF-8:$chars = html_entity_decode('&euro;', ENT_NOQUOTES, 'UTF-8');# Use iconv() to convert a character value xA4 in ISO-8859-15 to UTF:$chars = iconv('iso-8859-15', 'utf-8', chr(0xA4));</pre><p></p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>GD does not support using named character entities such as &euro; directlyin strings - they must be numerically encoded as described above.</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>