SetXLabelType
Prev | PHPlot Function Reference | Next

## SetXLabelType

SetXLabelType — Set formatting type for X tick labels

## Synopsis

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

## Description

`SetXLabelType` sets the formatting type for X tick labels, and the default formatting type for X data labels. (If SetXDataLabelType is never called, `SetXLabelType` effectively sets the formatting type for both X tick labels and X 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 SetPrecisionX, or as an additional argument to SetXLabelType. A prefix and suffix string can also be specified.

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

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

'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 value set with SetPrecisionX 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 SetXTimeFormat 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()`. 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.

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, 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_arg`

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

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

A side effect of SetPrecisionX is to call this function SetXLabelType and set the format type to 'data'. Note that SetXTimeFormat 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.

## Examples

The following table shows some label formatting examples. These also apply to `SetXLabelType`, SetXDataLabelType, SetYLabelType, and SetYDataLabelType.

Code: | Value: | Result:
--- | --- | ---
Data (numeric) formatting with two digits of precision. Grouping and decimal separators depend on locale.
    $plot->SetXLabelType('data', 2);
| 1234.56 | 1,234.56
Data (numeric) formatting with prefix. &#8364; is the entity code for the Euro sign in Unicode. (Numeric entity codes are handled by the GD library, but not named character entity codes.) Here we use it as a prefix, common usage for English. The Euro sign may appear differently in your browser. But when used with PHPlot it requires a Unicode font on the server.
    $plot->SetXLabelType('data', 0, '&amp;#8364;');
| 100000 | €1,000,000
Data (numeric) formatting with suffix. Here we use the Euro as a suffix, common usage for French. Unlike the previous example, here we represent it as a 3 byte UTF-8 sequence. You can use html_entity_decode() with UTF-8 as the character set to translate &euro; into this sequence. (You cannot used named character entity codes in PHPlot strings that are processed by GD, as GD only handles UTF-8 sequences or numeric entity codes.) The thousands and decimal separator default to locale-dependent values, but here we set them ourselves with SetNumberFormat. The Euro sign may appear differently in your browser. But when used with PHPlot it requires a Unicode font on the server.
    $plot->SetNumberFormat(',', '.');
    $plot->SetXLabelType('data', 2, '',
                         '\xe2\x82\xac');
| 100000 | 1.000.000,00€
Date/time formatting. The given value is mktime(0,0,0,4,15,2008). The format string could be set with SetXTimeFormat instead.
    $plot->SetXLabelType('time', '%m/%Y');
| 1208232000 | 04/2008
Formatting using printf. Note PHP printf may differ from the standard C library. For example, PHP outputs only a one digit exponent here.
    $plot->SetXLabelType('printf', '%8.2e');
| 1234 | 1.23e+3
A custom formatting function is used to format values in decimal degrees as degrees, minutes, and seconds. (This only works for non-negative angles.)
    function deg_min_sec($value)
    {
      $deg = (int)$value;
      $value = ($value - $deg) * 60;
      $min = (int)$value;
      $sec = (int)(($value - $min) * 60);
      return "{$deg}d {$min}m {$sec}s";
    }
    $plot->SetXLabelType('custom', 'deg_min_sec');
| 75.12345 | 75d 7m 24s

## History

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 X tick labels and X data labels. Starting with PHPlot-5.1.0, a new function SetXDataLabelType was added to allow separate control of tick and data labels. `SetXLabelType` now sets the format type for X tick labels, and the default format type for X 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 SetXTimeFormat and SetPrecisionX to set the formatting parameters. Starting with PHPlot-5.0.6, you have the choice of using those, or providing additional arguments to SetXLabelType. 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.

Starting with PHPlot-5.0.4, empty string data labels are ignored when formatting with 'data' or 'time' formats. You can use this to suppress some data labels, or control label density, with 'data' and 'time' formatted labels.

Through PHPlot-5.0rc3, empty strings would still be formatted. With 'data' format, an empty string would result in a zero value, and with 'time' format an empty string would cause an error. As a result, with older releases, if you don't want to use data labels when using 'data' or 'time' formats, you must turn off X data label display with SetXDataLabelPos, even if your data array labels are empty strings.

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.

Prev | Up | Next
SetXLabelAngle | Home | SetXScaleType