Description

SetYLabelType sets the formatting type for Y tick labels, and the default formatting type for Y data labels. (If SetYDataLabelType is never called, SetYLabelType effectively sets the formatting type for both Y tick labels and Y data labels.) 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. One, two, or three format strings are specified as additional arguments 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.

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

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

For type 'printf', there can be one, two, or three optional arguments:

For type 'custom', there is one required argument and one optional argument:

Notes

See Section 3.6, “Labels” for more information on labels, and specifically Section 3.6.5, “Formatting Labels” for more information on formatting labels.

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, use SetYLabelType without arguments, or with an empty string argument.

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.

When using 2 or 3 'printf' format strings, the labels being formatted must be numeric values.

When using 2 or 3 'printf' format strings, the second one is used to format the absolute value of the label, so you generally must provide some indication in the format string that the value is negative.

Examples

See SetXLabelType.

History

The 'printf' label format type was extended to support 2 or 3 format strings in PHPlot-6.2.0. Before that release, only a single format string could be used.

Custom label formatting functions are passed the row and column arguments (if applicable) starting with PHPlot-5.8.0.

Through PHPlot-5.0.7, this function set the format type for both Y tick labels and Y data labels. Starting with PHPlot-5.1.0, a new function SetYDataLabelType was added to allow separate control of tick and data labels. SetYLabelType now sets the format type for Y tick labels, and the default format type for Y data labels.

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.

Starting with PHPlot-5.0.6, you can use an empty string or no argument at all to reset to the default of no formatting.

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.