Axis.setMultiFormat

Sets multiple formats for numeric or date/time axis labels.

This method is typically used to format date/time labels. For example, for an axis that spans 90 days, this method can be used to format the first labels of each month in bold as "mmm-dd", while other labels are shown in normal font as "dd".

The multiple formats are defined as a list of filters and format strings. If the label value satisfies the first filter, it will be formatted using the first format string. Otherwise if the label value satisfies the second filter, it will be formatted using the second format string, and so on. If a label value does not satisfy any filter, it will be discarded.

In the above example, the first filter can be a "start of month" filter (created using perlchartdir::StartOfMonthFilter), and the first format string can be "{value|mmm-dd}". The second filter can be the "all pass" filter (created using perlchartdir::AllPassFilter), and the format string can be "{value|dd}".

Supported filters in ChartDirector include:

Filter	Description
perlchartdir::StartOfHourFilter	Creates a data filter that matches date/times that represent the start of a new hour in a date/time series.
perlchartdir::StartOfDayFilter	Creates a data filter that matches date/times that represent the start of a new day in a date/time series.
perlchartdir::StartOfWeekFilter	Creates a data filter that matches date/times that represent the start of a new week in a date/time series.
perlchartdir::StartOfMonthFilter	Creates a data filter that matches date/times that represent the start of a new month in a date/time series.
perlchartdir::StartOfYearFilter	Creates a data filter that matches date/times that represent the start of a new year in a date/time series.
perlchartdir::RegularSpacingFilter	Creates a data filter that matches 1 out of every N elements.
perlchartdir::AllPassFilter	Creates a data filter that matches every element.
perlchartdir::NonePassFilter	Creates a data filter that matches no element.
perlchartdir::SelectItemFilter	Creates a data filter that matches one specified item.

For the format strings, please refer to Parameter Substitution and Formatting on their syntax.

A single setMultiFormat method supports two filters and two format strings. You can use multiple setMultiFormat and/or Axis.setMultiFormat2 methods to add more filters and format strings.

One common issue in putting labels on the axis is that there may be too many labels on the axis. The setMultiFormat method supports a labelSpan argument that specifies how many label positions a single label will occupy. If a label occupies more than 1 position, ChartDirector will not put labels on nearby positions, even if they meet the filter criteria.

The setMultiFormat method supports special handling of the first label on the axis. For example, in the above example, we may want to show the the first label as "mmm-dd", even if it is not actually the "start of month". The promoteFirst argument, if set to true, will cause the first label to be promoted to a higher filter category in the multi-format list. For example, if the first label satisfies only the second filter, it will be formatted as if it satisfies the first filter.

Argument	Default	Description
filter1	(Mandatory)	The filter that defines the first kind of labels.
format1	(Mandatory)	The format string for the first kind of labels.
filter2	(Mandatory)	The filter that defines the second kind of labels.
format2	(Mandatory)	The format string for the second kind of labels.
labelSpan	1	The number of label positions that are claimed by one label. If a label occupies more than 1 position, ChartDirector will not put labels on nearby positions, even if they meet the filter criteria.
promoteFirst	true (non-zero)	If set to true, the first label will be promoted to a higher filter category in the multi-format list.