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>SetPieLabelType</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="SetPieLabelColor.html" title="SetPieLabelColor" /><link rel="next" href="SetPieStartAngle.html" title="SetPieStartAngle" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">SetPieLabelType</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="SetPieLabelColor.html">Prev</a> </td><th width="60%" align="center">PHPlot Function Reference</th><td width="20%" align="right"> <a accesskey="n" href="SetPieStartAngle.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="SetPieLabelType"></a><div class="titlepage"></div><div class="refnamediv"><h2><span class="refentrytitle">SetPieLabelType</span></h2><p>SetPieLabelType &#8212; Set type and format for pie chart labels</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">$plot-&gt;SetPieLabelType(<em class="parameter"><code>$source</code></em>, [<span class="optional"><em class="parameter"><code>$type</code></em></span>], [<span class="optional"><em class="parameter"><code>...</code></em></span>])</pre></div><div class="refsect1"><a id="idp1378487924"></a><h2>Description</h2><p>
<code class="function">SetPieLabelType</code> sets the type and format of labels which
will be displayed on a <a class="link" href="conc-plottypes.html#plottype-pie" title="3.4.10. Plot Type: pie (Pie Plot)">pie chart</a>.
The labels identify the segments of the pie. They can show the segment
percentage, a numeric value, or a text string.
    </p></div><div class="refsect1"><a id="idp1378489516"></a><h2>Parameters</h2><p>
There is one required argument, $source, following by an optional argument
$type. If $type is present and not empty, additional arguments are required.
      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>$source</code></em></span></dt><dd><p>
A string or array indicating the source of the label. If a string, it must be
one of the following values (see notes for more details):
              </p><div class="informaltable"><table summary="SetPieLabelType source choices" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Source</th><th>Description</th></tr></thead><tbody><tr><td>index</td><td>Use the ordinal number of the segment (starting at 0)</td></tr><tr><td>label</td><td>Use the label string from the data array</td></tr><tr><td>percent</td><td>Use the segment's percentage of the whole pie</td></tr><tr><td>value</td><td>Use the numeric value of the segment</td></tr></tbody></table></div><p>
An empty string (or NULL) restores the default pie chart label source and
format type.
            </p><p>
An array of strings can be used. Each element in the array must be one of
the string values above. PHPlot will join the multiple sources for the label,
separating each pair with a space. This can be used with custom formatting
types to have pie chart labels with multiple fields (such as percentage and
label, or label and value). See notes below for more.
            </p></dd><dt><span class="term"><em class="replaceable"><code>$type</code></em></span></dt><dd><p>
Optional argument indicating how to format the label string. If supplied,
it can be one of the following:
<code class="literal">data</code>,
<code class="literal">printf</code>, or
<code class="literal">custom</code>.
If the argument is missing or an empty string, this indicates that the
default of no formatting should be used.
If the argument is provided and not empty, additional arguments are
required or optional as shown below.
            </p></dd></dl></div><p>
    </p><p>
If the $type argument is <code class="literal">data</code>,
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.
            </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.
When $source is <code class="literal">percent</code>, a percent sign '%' should be
specified as the suffix.
            </p></dd></dl></div><p>
    </p><p>
If the $type argument is <code class="literal">printf</code>,
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">sprintf()</code>.
The formatting string must contain exactly one conversion specification
(%-code) which consumes a single argument.
If omitted, the default value of '%e' uses scientific notation with default
field sizes.
            </p></dd></dl></div><p>
    </p><p>
If the $type argument is <code class="literal">custom</code>,
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 arguments: the value
of the label to be formatted, and the pass-through argument (see next).
            </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="idp1378509148"></a><h2>Notes</h2><p>
The default formatting if this function is not called is to show the
percentage of each segment, formatted with one decimal point and a percent
sign suffix. This is the same as:
</p><pre class="programlisting">$plot-&gt;SetPieLabelType('percent', 'data', 1, '', '%');
</pre><p>
The default formatting can be restored by passing an empty string or NULL
as the $source argument.
(Note: The default precision can be changed; see History below.)
    </p><p>
The formatting arguments starting with $type work exactly the same way as when
formatting X tick labels (for example) using <a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a>.
See there for formatting examples. Date/time formatted labels would also work
here, but are not documented for pie chart labels because they are unlikely to
be useful.
    </p><p>
If $source is <code class="literal">index</code>, the label source is an integer
starting with 0 for the first pie segment, 1 for the second pie segment, etc.
(By default, segments are drawn counter-clockwise from 0 degrees, but this
can be changed.)
This can be useful with <code class="literal">custom</code> type formatting, by
providing a formatting function to get the label text from an external
array (for example).
    </p><p>
If $source is <code class="literal">label</code>, the label source is taken from the
data array as set with <a class="xref" href="SetDataValues.html" title="SetDataValues"><span class="refentrytitle">SetDataValues</span></a>.
This can only be used with data type
<a class="link" href="conc-datatypes.html#text-data-single">text-data-single</a>,
because that is the only data type where each data array row (and its
label, in the first array position) corresponds to a single pie segment.
    </p><p>
If $source is <code class="literal">percent</code>, the label source is the
percentage of the pie represented by the segment being labeled.
This normally needs to used with $type = <code class="literal">data</code>,
<code class="literal">printf</code>, or <code class="literal">custom</code> formatting, in
order to get a fixed number of decimal places and a percent sign suffix.
Note that the following is probably not useful:
</p><pre class="programlisting">$plot-&gt;SetPieLabelType('percent'); // Do not use
</pre><p>
The resulting labels would display segment percentages, but as unformatted
floating point numbers with no suffix. For example, instead of "48.5%", the
label might display: "48.4865312". This is usually not the desired result.
    </p><p>
If $source is <code class="literal">value</code>, the label source is the numeric
value of the pie segment.  Depending on the data type used, this is a value
or sum of values from the data array.
    </p><p>
If $source is an array, the result is a string containing multiple
space-separated fields. This is most likely to be useful with custom formatting.
A custom label formatting function can split up the fields using
<code class="function">explode(' ', $str)</code>.
Note: If one of the fields is a label which might contain spaces, always place
that field last when specifying the $source array, and use the 3rd parameter
to explode() to limit the number of fields returned. This will ensure that
the complete label is extracted as a single field.  See the last example below.
    </p><p>
To adjust the position of the pie chart labels, see
<a class="xref" href="SetLabelScalePosition.html" title="SetLabelScalePosition"><span class="refentrytitle">SetLabelScalePosition</span></a>.
To turn the labels off completely, use
<code class="literal">SetLabelScalePosition(False)</code>.
    </p><p>
<code class="function">SetPieLabelType</code> also supports the use of two or three
format strings with 'printf' formatting type, as described in
<a class="xref" href="SetXLabelType.html" title="SetXLabelType"><span class="refentrytitle">SetXLabelType</span></a> and
<a class="xref" href="conc-labels.html#conc-labels-format-printf" title="3.6.5.3. Formatting Labels: 'printf' type">Section 3.6.5.3, &#8220;Formatting Labels: 'printf' type&#8221;</a>.
(The additional format strings are used for negative numbers, or zero.)
But this feature is almost never useful with pie charts, where all pie slices
have size greater than zero.
    </p></div><div class="refsect1"><a id="idp1378521236"></a><h2>Examples</h2><p>
In addition to the examples in this section,
see <a class="xref" href="ex-pielabeltype.html" title="5.41. Example - Pie Chart Label Types">Section 5.41, &#8220;Example - Pie Chart Label Types&#8221;</a>.
    </p><p>
Assume plot type <code class="literal">pie</code>, data type
<code class="literal">text-data-single</code>, and the follow data array:
</p><pre class="programlisting">
$data = array(
    array('Gold',        20),
    array('Silver',      13),
    array('Copper',       7),
    array('Tin',         18),
    array('Bronze',      10),
    array('Iron',         4),
    array('Platinum',     2),
    array('Nickel',       5),
);
</pre><p>
    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
For the default behavior of percentage labels with numeric formatting,
do not call <code class="function">SetPieLabelType</code>.
Result: <code class="literal">25.3%, 16.5%, 8.9%</code> etc.
        </span></dt><dd><pre class="programlisting">...</pre></dd><dt><span class="term">
Show segment indexes (ordinal segment number from 0).
Result: <code class="literal">0, 1, 2</code> etc.
        </span></dt><dd><pre class="programlisting">$plot-&gt;SetPieLabelType('index');
</pre></dd><dt><span class="term">
Show label strings from the data array.
Result: <code class="literal">Gold, Silver, Copper</code> etc.
        </span></dt><dd><pre class="programlisting">$plot-&gt;SetPieLabelType('label');
</pre></dd><dt><span class="term">
Show label strings from the data array, with quote marks added.
Result: <code class="literal">"Gold", "Silver", "Copper"</code> etc.
        </span></dt><dd><pre class="programlisting">$plot-&gt;SetPieLabelType('label', 'printf', '"%s"');
</pre></dd><dt><span class="term">
Show the numeric value of each segment, unformatted.
Result: <code class="literal">20, 13, 7</code> etc.
        </span></dt><dd><pre class="programlisting">$plot-&gt;SetPieLabelType('value');
</pre></dd><dt><span class="term">
Show the numeric value of each segment, formatted with 3 decimal places.
Result: <code class="literal">20.000, 13.000, 7.000</code> etc.
        </span></dt><dd><pre class="programlisting">$plot-&gt;SetPieLabelType('value', 'data', 3);
</pre></dd><dt><span class="term">
Use a custom formatting function to convert the data array labels to
upper case.
Result: <code class="literal">GOLD, SILVER, COPPER</code> etc.
        </span></dt><dd><pre class="programlisting">function mylabels($str)
{
    return strtoupper($str);
}
$plot-&gt;SetPieLabelType('label', 'custom', 'mylabels');
</pre></dd><dt><span class="term">
Combine multiple label sources: data array label and percentage.
Result: <code class="literal">Gold (25.3%), Silver (16.5%), Copper (8.9%)</code> etc.
        </span></dt><dd><pre class="programlisting">function mylabels($str)
{
    list($percent, $label) = explode(' ', $str, 2);
    return sprintf("%s (%.1f%%)", $label, $percent);
}
$plot-&gt;SetPieLabelType(array('percent', 'label'), 'custom', 'mylabels');
</pre></dd></dl></div></div><div class="refsect1"><a id="idp1378535756"></a><h2>History</h2><p>
This function was added in PHPlot-5.6.0. In earlier releases, only 'percent'
label type was available, and the labels were always formatted as fixed-point
values (format type 'data').
    </p><p>
Versions before PHPlot-5.6.0 used a numeric precision set with
<a class="xref" href="SetPrecisionY.html" title="SetPrecisionY"><span class="refentrytitle">SetPrecisionY</span></a> or <a class="xref" href="SetYLabelType.html" title="SetYLabelType"><span class="refentrytitle">SetYLabelType</span></a>
for pie chart percentage labels, with a default of 1 decimal place.
(This was not documented.)
PHPlot-5.6.0 still does that, but only if <code class="function">SetPieLabelType</code>
was never called (or reset to all defaults). That is, if
<code class="function">SetPieLabelType</code> was not called to set up a label source
and formatting type, the Y label precision will be used if set, else 1 digit.
    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="SetPieLabelColor.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="SetPieStartAngle.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SetPieLabelColor </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> SetPieStartAngle</td></tr></table></div></body></html>