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>SetXLabelType</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="reference.html" title="PHPlot Function Reference" /><link rel="prev" href="SetXLabelAngle.html" title="SetXLabelAngle" /><link rel="next" href="SetXScaleType.html" title="SetXScaleType" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SetXLabelType</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="SetXLabelAngle.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="SetXScaleType.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="SetXLabelType"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">SetXLabelType</span></h2><p>SetXLabelType — Set formatting type for X tick labels</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot->SetXLabelType(<em class="parameter"><code>$type</code></em>, [<span class="optional"><em class="parameter"><code>...</code></em></span>])</pre></div><div class="refsect1"><a id="idp1378931732"></a><h2>Description</h2><p><code class="function">SetXLabelType</code> sets the formatting type for X tick labels,and the default formatting type for X data labels.(If <a class="xref" href="SetXDataLabelType.html" title="SetXDataLabelType"><span class="refentrytitle">SetXDataLabelType</span></a> is never called,<code class="function">SetXLabelType</code> effectively sets the formatting typefor both X tick labels and X data labels.)By default, there is no special formatting, so the labels are output as-is.Available format types are 'data', 'time', 'printf', and 'custom'.</p><p>'data' formatting formats the labels as floating point numbers,with digits grouped into thousands (3 digit groups),and with user-defined precision.Grouping separator characters can be set with <a class="xref" href="SetNumberFormat.html" title="SetNumberFormat"><span class="refentrytitle">SetNumberFormat</span></a>.The precision (number of digits after the decimal point) can be set with<a class="xref" href="SetPrecisionX.html" title="SetPrecisionX"><span class="refentrytitle">SetPrecisionX</span></a>, or as an additional argument to SetXLabelType.A prefix and suffix string can also be specified.</p><p>'time' formatting formats the labels as date/time values,using a format specifier set by <a class="xref" href="SetXTimeFormat.html" title="SetXTimeFormat"><span class="refentrytitle">SetXTimeFormat</span></a>or using an additional argument to SetXLabelType.</p><p>'printf' formatting formats the labels using the standard<code class="function">sprintf</code> function. One, two, or three format stringsare specified as additional arguments to SetXLabelType.</p><p>'custom' formatting formats the labels using a caller-provided function,with an optional pass-through argument. This provides the maximumflexibility in formatting labels.</p></div><div class="refsect1"><a id="idp1378936804"></a><h2>Parameters</h2><p>There is one required argument, $type. Other arguments depend on the valueof the $type argument.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$type</code></em></span></dt><dd><p>A string indicating the desired formatting mode: 'data', 'time', 'printf',or 'custom'. Or, an empty string meaning revert to no formatting.</p></dd></dl></div><p></p><p>For type 'data', there are three optional arguments:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$precision</code></em></span></dt><dd><p>The formatting precision, or number of decimal places (optional).If omitted, the value set with <a class="xref" href="SetPrecisionX.html" title="SetPrecisionX"><span class="refentrytitle">SetPrecisionX</span></a> is used,or if that was never called then the default is 1.</p></dd><dt><span class="term"><em class="replaceable"><code>$prefix</code></em></span></dt><dd><p>A prefix string to be placed before the formatted label values. This couldbe used for a currency symbol, for example. The default is an empty string.</p></dd><dt><span class="term"><em class="replaceable"><code>$suffix</code></em></span></dt><dd><p>A suffix string to be placed after the formatted label values. This couldbe used for a currency symbol, for example. The default is an empty string.</p></dd></dl></div><p></p><p>For type 'time', there is one optional argument:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$format</code></em></span></dt><dd><p>Format string, used with <code class="function">strftime()</code>.For example, '%Y-%m-%d' results in formatting a <code class="literal">time_t</code>value as a year, month, and day numbers.If omitted, the value set with <a class="xref" href="SetXTimeFormat.html" title="SetXTimeFormat"><span class="refentrytitle">SetXTimeFormat</span></a> is used,or if that was never called then the default is '%H:%M:%S' (hours, minutes,and seconds).</p></dd></dl></div><p></p><p>For type 'printf', there can be one, two, or three optional arguments:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$format1</code></em>,[<span class="optional"><em class="replaceable"><code>$format2</code></em>,[<span class="optional"><em class="replaceable"><code>$format3</code></em></span>]</span>]</span></dt><dd><p>Format string(s), used with <code class="function">sprintf()</code>.The format string(s) must contain at most one conversion specification(%-code) which consumes a single argument.If no format strings are specified, the default value of '%e' uses scientificnotation with default field sizes.</p><p>If a single format string is given (<code class="literal">$format1</code>),it is used for all label values.</p><p>If two format strings are given (<code class="literal">$format1, $format2</code>),then the first string <code class="literal">$format1</code> is used to format the valueof the label if it is greater than or equal to zero.The second string <code class="literal">$format2</code> is used to formatthe absolute value of the label if it is less than zero.</p><p>If three format strings are given (<code class="literal">$format1, $format2,$format3</code>),then the first string <code class="literal">$format1</code> is used to format the valueof the label if it is greater than zero.The second string <code class="literal">$format2</code> is used to formatthe absolute value of the label if it is less than zero.The third string <code class="literal">$format3</code> is used when the value of thelabel is zero.</p></dd></dl></div><p></p><p>For type 'custom', there is one required argument and one optional argument:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$callback</code></em></span></dt><dd><p>A callback function to format the label. This is either the name of afunction (as a string), or a two-element array with an object instance andmethod name. (Refer to the PHP documentation for more information on thecallback type.)The callback will be called with two, three, or four arguments:the value of the label to be formatted, the pass-through argument (see next),and the row and column of the data point (if applicable to the label type).See <a class="xref" href="conc-labels.html#conc-labels-format-custom2" title="3.6.5.5. Formatting Labels: Extended 'custom' type">Section 3.6.5.5, “Formatting Labels: Extended 'custom' type”</a> for more on the row andcolumn arguments supplied to the callback.</p></dd><dt><span class="term"><em class="replaceable"><code>$callback_arg</code></em></span></dt><dd><p>A pass-through argument for the callback function.If omitted, NULL is used.</p></dd></dl></div><p></p></div><div class="refsect1"><a id="idp1378955132"></a><h2>Notes</h2><p>See <a class="xref" href="conc-labels.html" title="3.6. Labels">Section 3.6, “Labels”</a> for more information on labels, andspecifically <a class="xref" href="conc-labels.html#conc-labels-format" title="3.6.5. Formatting Labels">Section 3.6.5, “Formatting Labels”</a> for more information onformatting labels.</p><p>The default formatting mode is to do no special formatting of the labels.Strings will be output as-is, and numbers will be output using PHP'sdefault formatting.If you need to change label formatting back to the default,use SetXLabelType without arguments, or with an empty string argument.</p><p>A side effect of <a class="xref" href="SetPrecisionX.html" title="SetPrecisionX"><span class="refentrytitle">SetPrecisionX</span></a> is to call this functionSetXLabelType and set the format type to 'data'.Note that <a class="xref" href="SetXTimeFormat.html" title="SetXTimeFormat"><span class="refentrytitle">SetXTimeFormat</span></a> does not have a correspondingside effect on the format type.</p><p>When using a custom label formatting function, do not assume the labels areformatted in any particular order, or only once each.</p><p>When using 2 or 3 'printf' format strings, the labels being formatted mustbe numeric values.</p><p>When using 2 or 3 'printf' format strings, the second one is used to formatthe <span class="emphasis"><em>absolute value</em></span> of the label, so you generally mustprovide some indication in the format string that the value is negative.</p></div><div class="refsect1"><a id="idp1378959308"></a><h2>Examples</h2><p>The following tables show some label formatting examples.These also apply to <code class="function">SetXLabelType</code>,<a class="xref" href="SetXDataLabelType.html" title="SetXDataLabelType"><span class="refentrytitle">SetXDataLabelType</span></a>, <a class="xref" href="SetYLabelType.html" title="SetYLabelType"><span class="refentrytitle">SetYLabelType</span></a>,and <a class="xref" href="SetYDataLabelType.html" title="SetYDataLabelType"><span class="refentrytitle">SetYDataLabelType</span></a>.</p><p>Data (numeric) formatting with two digits of precision.Grouping and decimal separators depend on locale.</p><div class="informaltable"><table summary="Examples of label formatting, Part 1" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td rowspan="2"><pre class="programlisting">$plot->SetXLabelType('data', 2);</pre></td><td>1234.56</td><td>1,234.56</td></tr><tr><td>3.14159</td><td>3.14</td></tr></tbody></table></div><p></p><p>Data (numeric) formatting with prefix.&#8364; is the entity code for the Euro sign in Unicode. (Numeric entitycodes are handled by the GD library, but not named character entity codes.)Here we use it as a prefix, common usage for English.The Euro sign may appear differently in your browser. But when used withPHPlot it requires a Unicode font on the server.</p><div class="informaltable"><table summary="Examples of label formatting, Part 2" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td><pre class="programlisting">$plot->SetXLabelType('data', 0, '&amp;#8364;');</pre></td><td>1000000</td><td>€1,000,000</td></tr></tbody></table></div><p></p><p>Data (numeric) formatting with suffix.Here we use the Euro as a suffix, common usage for French, represented by a3 byte UTF code.You can use html_entity_decode() with UTF-8 as the character setto translate &euro; into this sequence.SetNumberFormat is used here to override the locale settings forthousands and decimal separators.</p><div class="informaltable"><table summary="Examples of label formatting, Part 3" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td rowspan="2"><pre class="programlisting">$plot->SetNumberFormat(',', '.');$plot->SetXLabelType('data', 2, '',"\xe2\x82\xac");</pre></td><td>1e6</td><td>1.000.000,00€</td></tr><tr><td>4321.123</td><td>4.321,123€</td></tr></tbody></table></div><p></p><p>Date/time formatting.The given value is mktime(0,0,0,4,15,2008).The format string could be set with SetXTimeFormat instead.</p><div class="informaltable"><table summary="Examples of label formatting, Part 4" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td><pre class="programlisting">$plot->SetXLabelType('time', '%m/%Y');</pre></td><td>1208232000</td><td>04/2008</td></tr></tbody></table></div><p></p><p>Formatting using printf.Note PHP printf may differ from the standard C library. For example, PHPoutputs only a one digit exponent here.</p><div class="informaltable"><table summary="Examples of label formatting, Part 5" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td><pre class="programlisting">$plot->SetXLabelType('printf', '%8.2e');</pre></td><td>1234</td><td> 1.23e+3</td></tr></tbody></table></div><p></p><p>When two format strings are used with printf formatting, the first is usedfor non-negative values, and the second for negative values (with theabsolute value formatted).</p><div class="informaltable"><table summary="Examples of label formatting, Part 6" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td rowspan="2"><pre class="programlisting">$plot->SetXLabelType('printf', '%.2f', '(%.2f)');</pre></td><td>15.6</td><td>15.60</td></tr><tr><td>-9.87</td><td>(9.87)</td></tr></tbody></table></div><p></p><p>When three format strings are used with printf formatting, the first is usedfor positive values, the second for negative values (with the absolute valueformatted), and the third for zero.You can suppress zero with an empty third format string.</p><div class="informaltable"><table summary="Examples of label formatting, Part 7" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td rowspan="3"><pre class="programlisting">$plot->SetXLabelType('printf', 'GAIN:$%.2f','LOSS:($%.2f)', '[Unchanged]');</pre></td><td>9.1</td><td>GAIN:$9.10</td></tr><tr><td>-26.35</td><td>LOSS:($26.35)</td></tr><tr><td>0</td><td>[Unchanged]</td></tr></tbody></table></div><p></p><p>In this example, a custom formatting function is used to format values indecimal degrees as degrees, minutes, and seconds.(This only works for non-negative angles.)</p><div class="informaltable"><table summary="Examples of label formatting, Part 8" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /></colgroup><thead><tr><th>Code:</th><th>Value:</th><th>Result:</th></tr></thead><tbody><tr><td rowspan="3"><pre class="programlisting">function deg_min_sec($value){$deg = (int)$value;$value = ($value - $deg) * 60;$min = (int)$value;$sec = (int)(($value - $min) * 60);return "{$deg}d {$min}m {$sec}s";}$plot->SetXLabelType('custom', 'deg_min_sec');</pre></td><td>75.12345</td><td>75d 7m 24s</td></tr><tr><td>0</td><td>0d 0m 0s</td></tr><tr><td>136.5</td><td>136d 30m 0s</td></tr></tbody></table></div><p></p></div><div class="refsect1"><a id="idp1379006308"></a><h2>History</h2><p>The 'printf' label format type was extended to support 2 or 3 format stringsin PHPlot-6.2.0. Before that release, only a single format string could be used.</p><p>Custom label formatting functions are passed the row and column arguments(if applicable) starting with PHPlot-5.8.0.</p><p>Through PHPlot-5.0.7, this function set the format type for both X ticklabels and X data labels.Starting with PHPlot-5.1.0, a new function <a class="xref" href="SetXDataLabelType.html" title="SetXDataLabelType"><span class="refentrytitle">SetXDataLabelType</span></a>was added to allow separate control of tick and data labels.<code class="function">SetXLabelType</code> now sets the format type for X tick labels,and the default format type for X data labels.</p><p>New label format types 'printf' and 'custom' were added at PHPlot-5.0.6,as well as all arguments after the first. In PHPlot-5.0.5 and earlier, youmust use SetXTimeFormat and SetPrecisionX to set the formatting parameters.Starting with PHPlot-5.0.6, you have the choice of using those, orproviding additional arguments to SetXLabelType.Also added was the ability to add a prefix and suffix to 'data' formattedlabels. In PHPlot-5.0.5 and earlier, there was an undocumented class variable<em class="parameter"><code>data_units_text</code></em> that was applied as a suffix to 'data'mode labels, for both X and Y. This continues to work, but is deprecated.</p><p>Starting with PHPlot-5.0.6, you can use an empty string or no argument at allto reset to the default of no formatting.</p><p>Starting with PHPlot-5.0.4, empty string data labels are ignored whenformatting with 'data' or 'time' formats. You can use this to suppresssome data labels, or control label density, with 'data' and 'time'formatted labels.</p><p>Through PHPlot-5.0rc3, empty strings would still be formatted. With 'data'format, an empty string would result in a zero value, and with 'time'format an empty string would cause an error. As a result, with older releases,if you don't want to use data labels when using 'data' or 'time' formats,you must turn off X data label display with<a class="xref" href="SetXDataLabelPos.html" title="SetXDataLabelPos"><span class="refentrytitle">SetXDataLabelPos</span></a>,even if your data array labels are empty strings.</p><p>Through PHPlot-5.0rc3, when the formatting mode is 'data'the thousands grouping separator was always a comma,and a period was used as a decimal point.Starting with 5.0.4, PHPlot attempts to get the correct values for yourlocale. You can set the separator characters yourself instead with<a class="xref" href="SetNumberFormat.html" title="SetNumberFormat"><span class="refentrytitle">SetNumberFormat</span></a>.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="SetXLabelAngle.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="SetXScaleType.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SetXLabelAngle </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> SetXScaleType</td></tr></table></div></body></html>