It is possible to format values displayed in the user forms components that store numerical data, namely TcxCalcEdit, TcxCurrencyEdit and TcxSpinEdit. Formatting can be used, for example, if you need to display a custom sign (such as the currency sign) next to the component’s value, or round the displayed number with a specified precision. At that, formatting only affects the way the value is displayed in the component and does not affect the value itself.
The TcxCurrencyEdit and TcxSpinEdit components allow different formatting for two modes -- the display mode (when the component does not have the input focus) and the edit mode (when the component is focused). The formatting for these modes are specified by the Properties.DisplayFormat and Properties.EditFormat properties. The TcxCalcEdit component applies the same formatting specified by its Properties.DisplayFormat property to both display and edit modes.
The display and edit formats are specified by format strings that consist of format specifiers. Format strings can contain several sections that specify formats applied to positive, negative and zero values. Sections within the format string are separated from each other by semicolon characters. Depending on the number of sections, the formats are treated as follows:
- If the format string contains one section, it is applied to all values.
- If the format string contains two sections, the first section applies to positive and zero values; the second applies to negative values.
- If the format string contains three sections, the first section applies to positive values, the second - to negative values, and the third - to zero values.
If any of the sections for negative or zero values or both are empty, the positive numbers’s format is used.
You can use the following format specifiers within the format string:
| Specifier | Description | ||
|---|---|---|---|
| 0 | Specifies the digit placeholder. If the component’s value does not have the digit in this position, 0 appears. | ||
| # | Specifies the digit placeholder. If the component does not have the digit in this position, no character appears. | ||
| . | Specifies the position of the decimal separator. If the formatting string includes several decimal point specifiers, all of them are ignored except for the first one.
The actual character used as a decimal separator depends on the system’s regional settings. |
||
| , | Specifies that the resulting string will include thousand separators. The number and position of thousand separator specifiers in the formatting string has no effect on the resulting string.
The actual character used as a decimal separator depends on the system’s regional settings.
|
||
| E+, E-, e+ or e- | Specifies that the component’s value is to be displayed using the scientific format. A 0 that immediately follows E+, E-, e+ or e- specifies the number of digits for the exponent. The maximum number of 0s in this group is 4. If you use E+ or e+, the exponent will always have the sign. If you use the E- or e- specifiers, the sign will only be displayed for negative exponents. | ||
| 'nnn' or "NNN" | Characters included in single or double quotes are included in the displayed value “as-is”. Note that these characters do not affect the value entered into the component or displayed in it. | ||
| ; | Separates parts of the format string (see above). |
Any other character that is not mentioned in the table above can appear in format strings and will be treated as a literal character.
The displayed value is always rounded to as many digits after the decimal point as there are 0 or # specifiers after the decimal point in the formatting string. If the formatting string does not hold the decimal point specifier, the value is rounded to the nearest whole number.