Masking for PSP decimal numerics is provided by the PSPDecMask object which controls

• formatted output of numeric values
• the values which can be used for input of decimal places

Note that the size of the decimal number is never specified in the PSPDecMask. This is always controlled separately by the DigitsBeforeDP and DigitsAfterDP properties.

PSPDecMask objects are referenced by both PSPDec and PSPNum objects as follows:

PSPDec Mask

For PSPDec objects, you construct the PSPDecMask separately and use it as follows:

// Create mask
PSPDecMask Mask1 = new PSPDecMask();
// Set/reset mask components
Mask1.set("[DP.][3S,][NB-][OBUS$ ]");
Mask1.set("[ZB*][3S,][PA+][NA-][NB]");
// Create separate PSPDec object
PSPDec Dec1 = new PSPDec(5,2,"12345.67");
// Derive formatted value of PSPDec
String Formatted = Dec1.toString(Mask1);
// Get used mask components
String Used = Mask1.getUsed();

PSPNum Mask

Because each PSPNum has an embedded PSPDecMask, you can set/get the mask values directly using the PSPNum:

// Create PSPNum with embedded mask
PSPNum Num1 = new PSPNum(5,2,"12345.67");
// Set/reset mask components
Num1.setMask("[DP.][3S,][NB-][OBUS$ ]");
Num1.setMask("[ZB*][3S,][PA+][NA-][NB]");
// Derive formatted value of PSPNum
String Formatted = Num1.getText();
// Get used mask components
String Used = Num1.getMaskUsed();

PSP Mask settings

It is generally a good idea to set critical mask values as early as possible for each PSPDec/PSPNum e.g. immediately after it is first created. Common mask settings are:

Mask Components

In the string value assigned to Mask, there must be one or more components delimited by [ ]. The first two characters following the opening '[' identify the mask component being set. Any characters after this and before the closing ']' are the new component value. For example, the mask component [DP.] means that the decimal place in an output formatted numeric value is being set to '.'. As another example, the mask component [DP and ] would set the same decimal place value to the phrase ' and '.

You may specify any number of components in each mask value. The values remain in effect until reset. So you can set/reset some components once, and reset other components repeatedly. All components are optional (do not have to be set in the Mask), with the exception of the DV component.

You can reset most components to NULL (nothing), by simply including no value. For example, the mask component [NB] sets the component identified by the letters 'NB' to NULL.

Most mask components control individual parts of the formatted value as follows:

In addition, two mask components control how input decimal places as in the following table. Note that these apply only to PSPNum objects, not to PSPDec objects.

Rules and recommendations

The following rules apply to mask components:

• Each component value may have a maximum of 30 characters, with the exception of the DI and DV components which must each have only one character.
• No mask component value may include the characters '[' or ']' or the numeric digits '0' through '9'. If these values are found in a component value they will be ignored.
• Trailing whitespace (e.g. blank) characters are automatically removed from NA, PA, ZA and OA components.
• Leading whitespace (e.g. blank) characters are automatically removed from NB, PB, ZL, ZB and OB components.
• The 3S and 4S components may have leading and/or trailing whitespace characters.
• The DP component must have at least one non-whitespace character for the output decimal place.
• The DI and DV component (a single character value) can only be set to a printable character other than whitespace, '+', '-', '[' and ']'.
• The PB and NB components can not have the same value except if both are NULL.
• The PA and NA components can not have the same value except if both are NULL.
• The PB, PA, NB and NA components can not all be NULL or whitespace. That is, you must have at least one distinguishing non-whitespace character for positive and negative values.
• When a PSPDecMask is first created, the default mask setting is equivalent to [NB-][3S,][DP.][DI.][DV.] with all other components initialised to NULL. In the future we may use locales to provide more sensible initial defaults.
• For PSPNum objects, the Mask is one of the persistent properties. This means that any Mask settings you make can be saved for when an application using the PSPNum restarts. In this case the default mask settings described above are overridden with the saved settings.

In addition to the above rules, consider the following recommendations:

• Never set the DP/DI/DV and 3S/4S components to the same value. PSPDec objects may mistake the first thousand-separator for the decimal place.
• Avoid setting other mask components to very similar values.
• If you want complicated formatting beyond the capabilities of a PSPDecMask, extract the unformatted numeric value - using methods such as toString()) - then format and display this separately.
• For PSPNum's any changes to the Text property are immediately applied when you invoke setMask() and not just when the PSPNum loses the input focus. So you may design your application such that your users have an opportunity to reinstate Mask settings if applicable. For example, only confirm Mask settings when an 'OK' button is clicked, or provide a 'Reset' button which restores PSPNum Mask settings saved earlier in the interactive dialog.
• Use the OA and OB mask components with care. For example, in true multi-currency applications it may be better to use a completely different control to show/input currency codes rather than trying to use the OA/OB components of the PSPNum edit mask for currency codes.

Mask Example

In the table below, the effect of new mask values are shown for a PSPNum/PSPDec with DigitsBeforeDP set to 6 and DigitsAfterDP set to 2. Note that mask revisions in the table are cumulative - that is, each row starts with settings from previous rows.