Subversion Repositories cheapmusic

Rev

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>SetXDataLabelType</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="SetXDataLabelPos.html" title="SetXDataLabelPos" /><link rel="next" href="SetXLabelAngle.html" title="SetXLabelAngle" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SetXDataLabelType</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="SetXDataLabelPos.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="SetXLabelAngle.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="SetXDataLabelType"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">SetXDataLabelType</span></h2><p>SetXDataLabelType &#8212; Set formatting type for X data labels</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot-&gt;SetXDataLabelType(<em class="parameter"><code>$type</code></em>, [<span class="optional"><em class="parameter"><code>...</code></em></span>])</pre></div><div class="refsect1"><a id="idp1378893660"></a><h2>Description</h2><p>
<code class="function">SetXDataLabelType</code> sets the formatting type for X data
labels. By default, data labels are formatted the same as tick labels.
If <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a> is not used, then there is no special
formatting for either label type, 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
as an additional argument to SetXDataLabelType.
A prefix and suffix string can also be specified.
    </p><p>
'time' formatting formats the labels as date/time values, with the
format string specified as an additional argument to SetXDataLabelType.
    </p><p>
'printf' formatting formats the labels using the standard
<code class="function">sprintf</code> function. One, two, or three format strings
are specified as additional arguments to SetXDataLabelType.
    </p><p>
'custom' formatting formats the labels using a caller-provided function,
with an optional pass-through argument. This provides the maximum
flexibility in formatting labels.
    </p></div><div class="refsect1"><a id="idp1378897628"></a><h2>Parameters</h2><p>
There is one required argument, $type. Other arguments depend on the value
of 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 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 could
be 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 could
be 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>
Formatting 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 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 scientific
notation 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 value
of the label if it is greater than or equal to zero.
The second string <code class="literal">$format2</code> is used to format
the 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 value
of the label if it is greater than zero.
The second string <code class="literal">$format2</code> is used to format
the 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 the
label 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 a
function (as a string), or a two-element array with an object instance and
method name. (Refer to the PHP documentation for more information on the
callback 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, &#8220;Formatting Labels: Extended 'custom' type&#8221;</a> for more on the row and
column 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="idp1378915220"></a><h2>Notes</h2><p>
This function applies to both X axis data labels and X data value labels.
(There is no ambiguity, because vertical plots have only X axis data labels,
and horizontal plots have only X data value labels.)
    </p><p>
See <a class="xref" href="conc-labels.html" title="3.6. Labels">Section 3.6, &#8220;Labels&#8221;</a> for more information on labels, and
specifically <a class="xref" href="conc-labels.html#conc-labels-format" title="3.6.5. Formatting Labels">Section 3.6.5, &#8220;Formatting Labels&#8221;</a> for more information on
formatting 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's
default formatting.
If you need to change label formatting back to the default,
or to override a format type you set for tick labels and have no
formatting for data labels,
use SetXDataLabelType without arguments, or with an empty string argument.
    </p><p>
When using a custom label formatting function, do not assume the labels are
formatted in any particular order, or only once each.
    </p><p>
When using 2 or 3 'printf' format strings, the labels being formatted must
be numeric values.
    </p><p>
When using 2 or 3 'printf' format strings, the second one is used to format
the <span class="emphasis"><em>absolute value</em></span> of the label, so you generally must
provide some indication in the format string that the value is negative.
    </p></div><div class="refsect1"><a id="idp1378918884"></a><h2>Examples</h2><p>
See <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a>.
    </p></div><div class="refsect1"><a id="idp1378919868"></a><h2>History</h2><p>
The 'printf' label format type was extended to support 2 or 3 format strings
in 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>
This function was added in PHPlot-5.1.0.
Through PHPlot-5.0.7, data labels and tick labels always used the same
formatting, as set with <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</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="SetXDataLabelPos.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="SetXLabelAngle.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SetXDataLabelPos </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> SetXLabelAngle</td></tr></table></div></body></html>