SharpPlot 2.20: Using Picture Formatters

Reference > Glossaries > 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 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.

‘XXXXXXXX’ simply limits the length of each label to a string of this size in the current font. If any of the labels is longer, it is clipped to one character less than the allowed length and the last character is set to an ellipsis. For very short patterns (less than 3 characters) the output is simply clipped to the pattern length.
‘XXXXX;’ will force the text of each label to wrap into the allowed width.

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:\nXXXXXX’ will make 2-line labels prefixed with ‘SKU:’.

Using Picture Formatters

Formatting numeric values

Formatting text labels

See also ...