SetPieLabelType
Prev | PHPlot Function Reference | Next

## SetPieLabelType

SetPieLabelType — Set type and format for pie chart labels

## Synopsis

    $plot->SetPieLabelType($source, [$type], [...])

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

`$source`

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

  Source | Description
  --- | ---
  index | Use the ordinal number of the segment (starting at 0)
  label | Use the label string from the data array
  percent | Use the segment's percentage of the whole pie
  value | Use the numeric value of the segment

  An empty string (or NULL) restores the default pie chart label source and format type.

  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.

`$type`

  Optional argument indicating how to format the label string. If supplied, it can be one of the following: `data`, `printf`, or `custom`. 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.

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

`$precision`

  The formatting precision, or number of decimal places (optional). If omitted, the default is 1.

`$prefix`

  A prefix string to be placed before the formatted label values.

`$suffix`

  A suffix string to be placed after the formatted label values. When $source is `percent`, a percent sign '%' should be specified as the suffix.

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

`$format`

  Formatting string, used with `sprintf()`. 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.

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

`$callback`

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

`$callback_arg`

  A pass-through argument for the callback function. If omitted, NULL is used.

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

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

For the default behavior of percentage labels with numeric formatting, do not call `SetPieLabelType`. Result: `25.3%, 16.5%, 8.9%` etc.

      ...

Show segment indexes (ordinal segment number from 0). Result: `0, 1, 2` etc.

      $plot->SetPieLabelType('index');

Show label strings from the data array. Result: `Gold, Silver, Copper` etc.

      $plot->SetPieLabelType('label');

Show label strings from the data array, with quote marks added. Result: `"Gold", "Silver", "Copper"` etc.

      $plot->SetPieLabelType('label', 'printf', '"%s"');

Show the numeric value of each segment, unformatted. Result: `20, 13, 7` etc.

      $plot->SetPieLabelType('value');

Show the numeric value of each segment, formatted with 3 decimal places. Result: `20.000, 13.000, 7.000` etc.

      $plot->SetPieLabelType('value', 'data', 3);

Use a custom formatting function to convert the data array labels to upper case. Result: `GOLD, SILVER, COPPER` etc.

      function mylabels($str)
      {
          return strtoupper($str);
      }
      $plot->SetPieLabelType('label', 'custom', 'mylabels');

Combine multiple label sources: data array label and percentage. Result: `Gold (25.3%), Silver (16.5%), Copper (8.9%)` etc.

      function mylabels($str)
      {
          list($percent, $label) = explode(' ', $str, 2);
          return sprintf("%s (%.1f%%)", $label, $percent);
      }
      $plot->SetPieLabelType(array('percent', 'label'), 'custom', 'mylabels');

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

Prev | Up | Next
SetPieLabelColor | Home | SetPieStartAngle