Description

SetPieLabelType sets the type and format of labels which will be displayed on a pie chart. The labels identify the segments of the pie. They can show the segment percentage, a numeric value, or a text string.

Parameters

There is one required argument, $source, following by an optional argument $type. If $type is present and not empty, additional arguments are required.

If the $type argument is data, there are three optional arguments:

If the $type argument is printf, there is one optional argument:

If the $type argument is custom, there is one required argument and one optional argument:

Notes

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:

$plot->SetPieLabelType('percent', 'data', 1, '', '%');

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.)

The formatting arguments starting with $type work exactly the same way as when formatting X tick labels (for example) using SetXLabelType. 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.

If $source is index, 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 custom type formatting, by providing a formatting function to get the label text from an external array (for example).

If $source is label, the label source is taken from the data array as set with SetDataValues. This can only be used with data type text-data-single, 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.

If $source is percent, the label source is the percentage of the pie represented by the segment being labeled. This normally needs to used with $type = data, printf, or custom formatting, in order to get a fixed number of decimal places and a percent sign suffix. Note that the following is probably not useful:

$plot->SetPieLabelType('percent'); // Do not use

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.

If $source is value, 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.

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 explode(' ', $str). 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.

To adjust the position of the pie chart labels, see SetLabelScalePosition. To turn the labels off completely, use SetLabelScalePosition(False).

SetPieLabelType also supports the use of two or three format strings with 'printf' formatting type, as described in SetXLabelType and Section 3.6.5.3, “Formatting Labels: 'printf' type”. (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.

Examples

In addition to the examples in this section, see Section 5.41, “Example - Pie Chart Label Types”.

Assume plot type pie, data type text-data-single, and the follow data array:

$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),
);

History

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').

Versions before PHPlot-5.6.0 used a numeric precision set with SetPrecisionY or SetYLabelType 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 SetPieLabelType was never called (or reset to all defaults). That is, if SetPieLabelType was not called to set up a label source and formatting type, the Y label precision will be used if set, else 1 digit.