SetXDataLabelType
Prev | PHPlot Function Reference | Next

## SetXDataLabelType

SetXDataLabelType — Set formatting type for X data labels

## Synopsis

    $plot->SetXDataLabelType($type, [...])

## Description

`SetXDataLabelType` sets the formatting type for X data labels. By default, data labels are formatted the same as tick labels. If SetXLabelType 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'.

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

'time' formatting formats the labels as date/time values, with the format string specified as an additional argument to SetXDataLabelType.

'printf' formatting formats the labels using the standard `sprintf` function, with the format string specified as an additional argument to SetXDataLabelType.

'custom' formatting formats the labels using a caller-provided function, with an optional pass-through argument. This provides the maximum flexibility in formatting labels.

## Parameters

There is one required argument, $type. Other arguments depend on the value of the $type argument.

`$type`

  A string indicating the desired formatting mode: 'data', 'time', 'printf', or 'custom'. Or, an empty string meaning revert to no formatting.

For type '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. This could be used for a currency symbol, for example. The default is an empty string.

`$suffix`

  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.

For type 'time', there is one optional argument:

`$format`

  Formatting string, used with `strftime()`. For example, '%Y-%m-%d' results in formatting a `time_t` value as a year, month, and day numbers. If omitted, the default is '%H:%M:%S' (hours, minutes, and seconds).

For type 'printf', there is one optional argument:

`$format`

  Formatting string, used with `sprintf()`. If omitted, the default value of '%e' uses scientific notation with default field sizes.

For type '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 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.

When using a custom label formatting function, do not assume the labels are formatted in any particular order, or only once each.

## Examples

See SetXLabelType.

## History

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

Prev | Up | Next
SetXDataLabelPos | Home | SetXLabelAngle