SetYLabelType

SetYLabelType — Set formatting type for Y tick and data labels

Synopsis

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

Description

SetYLabelType sets the formatting type for Y tick and data labels. (Y data labels are only available with bar charts.) By default, there is no special formatting, 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 with SetPrecisionY, or as an additional argument to SetYLabelType. A prefix and suffix string can also be specified.

'time' formatting formats the labels as date/time values, using a format specifier set by SetYTimeFormat or using an additional argument to SetYLabelType.

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

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

For type 'data', there are three optional arguments:

$precision

The formatting precision, or number of decimal places (optional). If omitted, the value set with SetPrecisionY is used, or if that was never called then 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 value set with SetYTimeFormat is used, or if that was never called then 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.

A side effect of SetPrecisionY is to call this function SetYLabelType and set the format type mode to 'data'. Note that SetYTimeFormat does not have a corresponding side effect on the format type.

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

History

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 data_units_text that was applied as a suffix to 'data' mode labels, for both X and Y. This continues to work, but is deprecated.

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

Examples

See SetXLabelType.