Advanced Currency Input Control for Silverlight & WPF
One of the new controls introduced in ClientUI 4 is UXCurrencyEditor, an advanced input control specifically designed for currency and numerical input with support for .NET standard and custom numeric format.
In this post, I will share a number of useful features in the UXCurrencyEditor control, and how it can be useful in your Silverlight and WPF business applications.
Introducing UXCurrencyEditor
Often times, users are required to input numerical data such as currency, item quantity, or percentage value. Some of these scenarios also require different text between edit and display. In ClientUI 4, Intersoft has provided a versatile currency input control named UXCurrencyEditor.
Let’s take a quick example of a common business form where the currency value shows a currency sign in the display mode, but exclude the sign in the edit mode. For instance, the value of 25000 will have the following results.
| EditText | 25,000.00 |
|---|---|
| DisplayText | $25,000.00 |
This could be achieved using the supported patterns in the provided EditMask and DisplayMask property. These patterns conform to the .NET standard and custom numeric format. Some patterns are only suitable for DisplayMask and have been noted in the list below.
The following table lists the supported standard and numeric pattern:
| Standard Format | ||
|---|---|---|
| Valid EditMask | Format Specifier | Description |
| V | C, c | Currency A currency value. |
| V | D, d | Decimal Integer digits with optional negative sign. |
| X | E, e | Exponential (scientific) Exponential notation. |
| V | F, f | Fixed-point Integral and decimal digits with optional negative sign. |
| X | G, g | General The most compact of either fixed-point or scientific notation. |
| V | N, n | Number Integral and decimal digits, group separators, and a decimal separator with optional negative sign. |
| V | P, p | Percent Number multiplied by 100 and displayed with a percent symbol. |
| X | R, r | Round-trip A string that can round-trip to an identical number. |
| X | X, x | Hexadecimal A hexadecimal string. |
| *Currently UXCurrencyEditor standard format will not accept custom group sizes. The group sizes will always be 3. | ||
| Custom Format | ||
| Valid EditMask | Format Specifier | Description |
| V | 0 | Zero placeholder Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string. |
| V | # | Digit placeholder Replaces the pound sign with the corresponding digit if one is present; otherwise, no digit appears in the result string. |
| V | . | Decimal point Determines the location of the decimal separator in the result string. |
| V | , | Group separator and number scaling Replaces the pound sign with the corresponding digit if one is present; otherwise, no digit appears in the result string. |
| V | % | Percentage placeholder Multiplies a number by 100 and inserts a localized percentage symbol in the result string. |
| X | E0, E+0, E-0, e0, e+0, e-0 | Exponential notation If followed by at least one 0 (zero), formats the result using exponential notation. The case of "E" or "e" indicates the case of the exponent symbol in the result string. The number of zeros following the "E" or "e" character determines the minimum number of digits in the exponent. A plus sign (+) indicates that a sign character always precedes the exponent. A minus sign (-) indicates that a sign character precedes only negative exponents. |
| V | Escape character Causes the next character to be interpreted as a literal rather than as a custom format specifier. |
|
| V | ‘string’, "string" | Literal string delimiter Indicates that the enclosed characters should be copied to the result string unchanged. |
| V | ; | Section separator Defines sections with separate format strings for positive, negative, and zero numbers. |
Based on the supported pattern described above, the UXCurrencyEditor control with the currency value in the earlier scenario will have the EditMask property set to “#,##0.00” and the DisplayMask property set to “C”.
|
1 2 |
<Intersoft:UXCurrencyEditor EditMask="#,##0.00" DisplayMask="C" UseEditMaskAsDisplayMask="False" /> |
As shown in the snippet code above, you need to set the UseEditMaskAsDisplayMask property to False for the DisplayMask property to take effect.
The Value property of the UXCurrencyEditor control represents the numerical value of the EditText. We decided to use decimal data type to hold the UXCurrencyEditor value in order to accommodate large number value commonly used in financial applications.
UXCurrencyEditor also allows null value which is controlled by the AllowNull property. By default this property value is set to False, hence null value is not allowed by default. When AllowNull is enabled, users can set the value to null at runtime by selecting the whole text and press the Delete key (Ctrl + A, Del).
Negative Value
Another important feature that we think useful in financial applications is the special handling for negative value. By default, UXCurrencyEditor shows negative value in Red foreground and appends the text with – (negative sign). You can easily change the negative format by using the pattern ; (section separator). For instances, in order to show -10000 as (10,000.00), you set the negative format to (#,##0.00). See the following example.
|
1 |
<Intersoft:UXCurrencyEditor EditMask="#,##0.00;(#,##0.00)" /> |
Spin Feature
UXCurrencyEditor also supports spinning feature based on the active caret position. The Up arrow key is used to increment the value, while the down arrow key is used to decrement the value. The caret position determines the amount of value to be incremented or decremented.
| 5|00.00 | increment/decrement the value by 100. |
| |500.00 | increment/decrement value by 1000. |
Localization (Culture)
One of the most difficult challenges in business forms is how the input control can be customized to adapt the currency settings of the user’s culture, such as the currency sign, group separator, and the decimal point. Luckily, UXCurrencyEditor already supports such localization feature by simply setting the Culture property to desired culture string.
The following table shows various results of the UXCurrencyEditor using different culture. The example uses a Value of 10000 and EditMask set to “C”.
| Culture | EditText | ||
|---|---|---|---|
| CodeSnipppet | |||
| en-US | $10,000.00 | ||
|
|||
| en-GB | £10,000.00 | ||
|
|||
| id-ID | Rp10.000 | ||
|
|||
Editing Behavior
Although the UXCurrencyEditor is derived from UXTextBox, the editing behavior is vastly different since UXCurrencyEditor expected numerical data entry. There are several default TextBox operations which are considered invalid and ignored in the UXCurrencyEditor such as:
- Paste
Paste is only valid if all the text are numeric. - Insert
Only numerical value is valid.
Let’s take an example of UXCurrencyEditor with EditMask #,##0.00
|
1 |
<Intersoft:UXCurrencyEditor EditMask="#,##0.00" /> |
| EditText | Action | Result |
|---|---|---|
| Description | ||
| 0|.00 | Input A | 0|.00 |
| Input A is ignored. No change occured, the only accepted input is numerical value. | ||
| 0|.00 | Input 3 | 3|.00 |
| 0 is replaced by 3. Input in major number section is appended to the right and the caret position is not moved after successful insertion. If afterward user press 2 the result will be 32|.00 | ||
| 0.|00 | Input 1 | 0.1|0 |
| 0 is replaced by 1. Input in minor number section is appended to the right and the caret position is moved after successful insertion. | ||
| 0.12| | Input 3 | 0.23| |
| 12 become 23. The minor number format only accept 2 number, UXCurrencyEditor append the 3 to the minor number and get the 2 latest number. | ||
| 1,23|4.00 | Pressing BackSpace | 12|4.00 |
| 3 is deleted, since ‘,’ is not needed in the new value ‘,’ is also omitted. Caret position stays in front of 4. | ||
| 1,|23|4.00 | Pressing BackSpace | 1|4.00 |
| Hightligted text is deleted, ‘,’ is omitted for the same reason as above scenario. Caret positioned at the first deleted hightlight text. | ||
| |1,234.00| | Pressing BackSpace | [AllowNull=True] |
[AllowNull=False] 0|.00 |
| If AllowNull is False, reset EditText to 0.00 and positioned caret at default position. Otherwise, EditText is set to empty string. | ||
| |1,234.00| | Pasting text 1234567 | 1,234,567|.00 |
| The current value will be overrided with the new value. The new value is also formatted using the EditMask. It is also valid to paste value with group separator, such as 1,234,567. | ||
Summary
In this post, you have learned the key features of UXCurrencyEditor. You can play around with the UXCurrencyEditor features through the properties, or try some readily designed samples here. To see all available features, please see UXCurrencyEditor Overview.
You will need the latest 2010 R2 bits which you can download it here. If you have questions or feedback about UXMaskedInput or other ClientUI controls, please feel free to post them to our community forum.
Regards,
Glenn Layaar
