SharpPlot Tutorials > General Tutorials > Using Picture Formatters

Using Picture Formatters

You may apply a ‘picture’ format to numeric values, and also to text labels to enforce truncation or wrapping into a given width.

Formatting numeric values

Wherever you can use numeric value as labels (axes and data value tags) you may specify a suitable format string to have the numbers converted to appropriate text. Typical formats would be:

  • ‘##0.00’ allows space for 3 leading digits and always shows 2 decimal places
  • ‘#,###,##0’ inserts commas at the thousands and has no decimal places
  • ‘0000’ formats with leading zeros (always 4 digits)
  • ‘0.0E00’ uses scientific format, showing 2 significant figures
  • ‘##0%’ shows a trailing percent sign but does not scale the data (unlike the .Net ToString method)
  • ‘£##0.00’ floats a leading currency symbol
  • ‘---0.00’ floats a leading minus sign if the numbers are negative
  • ‘(#,##0.00’ shows negative values in parentheses
  • ‘Week #0’ shows ‘Week 1’ .... ‘Week 52’

Note that .Net always shows leading minus signs for negative numbers. If you really want absolute values shown, use a 2-part format such as ‘##0;##0’ to have the negative values formatted without the leading minus.

More formally...

The characters ‘#’, ‘-’ and ‘0’ are used to place the digits. The total number of ‘-#0’ characters in front of the decimal point determines the largest number you can display. Larger numbers are shown as ‘****’ to indicate overflow. Leading ‘0’ characters are zero-filled; leading ‘#’ characters are suppressed if not used. Digits after the decimal point are always shown, so ‘#’ and ‘0’ are equivalent here. Negative numbers are given a leading ‘-’ only if you use ‘-’ rather than ‘#’ as the placeholder.

The common currency symbols ‘$£’ and Euro will float to the front of the result if used as the first character in the format.

The character ‘~’ suppresses the digit in that position, so a vector of years could be formatted as ‘~~00’ to suppress the century part of the 4-digit number.

If the picture begins with an opening parenthesis, negative numbers will be parenthesised, rather than being shown with leading -ve symbols.

If any of the tokens ‘E-0’ ‘E+0’ ‘E0’ occur in the formatter, scientific notation will be used. A ‘+’ in the exponent part will always be shown, but a minus will only be shown when necessary. Floating currency symbols and other leading and trailing characters may be used as normal, for example ‘-##0.00E+00kg’ is a valid formatter here.

All special characters can be escaped with a preceding ‘\’ character, which must therefore be doubled to print out.

All other characters are simply treated as insertions, with the exception of ‘,’ which is only inserted if there were enough digits in the number to require it. The trailing % does not automatically scale the data.

Note that you always use the ‘American’ convention here for the decimal and thousands separators. These will be converted to your local currency symbols by the formatting function before the finished text is written to the chart.

Formatting text labels

A limited subset of the picture formatting capability may be used with text items, such as value tags and axis labels.

  • ‘XXXXX’ and ‘xxxxx’ output as many characters of the formatted string as there are ‘X’s. If the formatted string is longer than the total number of X, the last output character is replaced by an ellipsis.
  • ‘~~~~~’ supresses that many characters from the formatted string.
  • ‘XXXXX;’ and ‘xxxxx;’ will output the rest of the formatted string, wrapping the whole output into the width given by the ‘X’s at target font size.
  • ‘*’ will output the rest of the formatted string, without forcing a wrapping

These special characters may be escaped by preceding them with a backslash ‘\’.

Any other characters are treated as insertions, so a format like ‘SKU:XX/XXXX’ could be used for product codes, or a format such as ‘XXXX-XX-XX’ would be appropriate for text dates in the form 20020612. You may use line-break character as an insertion within the string, for example ‘SKU:\nXX/XXXX’ will make 2-line labels prefixed with ‘SKU:’, and ‘SKU:\nXXXXXX;’ will make a multi-line label wrapping at 6 X-widths in the label font size.

See also ...

SharpPlot.XLabelFormat Property | SharpPlot.YLabelFormat Property

Send comments on this topic
© Dyalog Ltd 2021