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>SetYLabelType</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="SetYLabelAngle.html" title="SetYLabelAngle" /><link rel="next" href="SetYScaleType.html" title="SetYScaleType" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SetYLabelType</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="SetYLabelAngle.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="SetYScaleType.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="SetYLabelType"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">SetYLabelType</span></h2><p>SetYLabelType &#8212; Set formatting type for Y tick labels</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot-&gt;SetYLabelType(<em class="parameter"><code>$type</code></em>, [<span class="optional"><em class="parameter"><code>...</code></em></span>])</pre></div><div class="refsect1"><a id="idp1379195348"></a><h2>Description</h2><p>
<code class="function">SetYLabelType</code> sets the formatting type for Y tick labels,
and the default formatting type for Y data labels.
(If <a class="xref" href="SetYDataLabelType.html" title="SetYDataLabelType"><span class="refentrytitle">SetYDataLabelType</span></a> is never called,
<code class="function">SetYLabelType</code> effectively sets the formatting type
for both Y tick labels and Y 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="SetPrecisionY.html" title="SetPrecisionY"><span class="refentrytitle">SetPrecisionY</span></a>, or as an additional argument to SetYLabelType.
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="SetYTimeFormat.html" title="SetYTimeFormat"><span class="refentrytitle">SetYTimeFormat</span></a>
or using an additional argument to SetYLabelType.
    </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 SetYLabelType.
    </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="idp1379200420"></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 value set with <a class="xref" href="SetPrecisionY.html" title="SetPrecisionY"><span class="refentrytitle">SetPrecisionY</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 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 value set with <a class="xref" href="SetYTimeFormat.html" title="SetYTimeFormat"><span class="refentrytitle">SetYTimeFormat</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 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="idp1379218756"></a><h2>Notes</h2><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,
use SetYLabelType without arguments, or with an empty string argument.
    </p><p>
A side effect of <a class="xref" href="SetPrecisionY.html" title="SetPrecisionY"><span class="refentrytitle">SetPrecisionY</span></a> is to call this function
SetYLabelType and set the format type mode to 'data'.
Note that <a class="xref" href="SetYTimeFormat.html" title="SetYTimeFormat"><span class="refentrytitle">SetYTimeFormat</span></a> does not have a corresponding
side effect on the format type.
    </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="idp1379222932"></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="idp1379223916"></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>
Through PHPlot-5.0.7, this function set the format type for both Y tick
labels and Y data labels.
Starting with PHPlot-5.1.0, a new function <a class="xref" href="SetYDataLabelType.html" title="SetYDataLabelType"><span class="refentrytitle">SetYDataLabelType</span></a>
was added to allow separate control of tick and data labels.
<code class="function">SetYLabelType</code> now sets the format type for Y tick labels,
and the default format type for Y 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, you
must use SetYTimeFormat and SetPrecisionY to set the formatting parameters.
Starting with PHPlot-5.0.6, you have the choice of using those, or
providing additional arguments to SetYLabelType.
Also added was the ability to add a prefix and suffix to 'data' formatted
labels. 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 all
to reset to the default of no formatting.
    </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 your
locale.  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="SetYLabelAngle.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="SetYScaleType.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SetYLabelAngle </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> SetYScaleType</td></tr></table></div></body></html>