This version of the manual was produced for the
PHPlot Sourceforge project web service site, which requires the logo on each
page.
To download a logo-free copy of the manual, see the
PHPlot project downloads
area.
SetXDataLabelType — Set formatting type for X data labels
$plot->SetXDataLabelType($type, [...])
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. One, two, or three format strings
are specified as additional arguments 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.
There is one required argument, $type. Other arguments depend on the value of the $type argument.
$typeA 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:
$precisionThe formatting precision, or number of decimal places (optional). If omitted, the default is 1.
$prefixA 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.
$suffixA 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 can be one, two, or three optional arguments:
$format1,
[$format2,
[$format3
]]
Format string(s), used with sprintf().
The format string(s) must contain at most one conversion specification
(%-code) which consumes a single argument.
If no format strings are specified, the default value of '%e' uses scientific
notation with default field sizes.
If a single format string is given ($format1),
it is used for all label values.
If two format strings are given ($format1, $format2),
then the first string $format1 is used to format the value
of the label if it is greater than or equal to zero.
The second string $format2 is used to format
the absolute value of the label if it is less than zero.
If three format strings are given ($format1, $format2,
$format3),
then the first string $format1 is used to format the value
of the label if it is greater than zero.
The second string $format2 is used to format
the absolute value of the label if it is less than zero.
The third string $format3 is used when the value of the
label is zero.
For type 'custom', there is one required argument and one optional argument:
$callbackA 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, three, or four arguments: the value of the label to be formatted, the pass-through argument (see next), and the row and column of the data point (if applicable to the label type). See Section 3.6.5.5, “Formatting Labels: Extended 'custom' type” for more on the row and column arguments supplied to the callback.
$callback_argA pass-through argument for the callback function. If omitted, NULL is used.
This function applies to both X axis data labels and X data value labels. (There is no ambiguity, because vertical plots have only X axis data labels, and horizontal plots have only X data value labels.)
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, 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.
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.
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.
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.
This version of the manual was produced for the
PHPlot Sourceforge project web service site, which requires the logo on each
page.
To download a logo-free copy of the manual, see the
PHPlot project downloads
area.