mask

Type: Integer

Availability: Read-only at any time

The mask property of the JadeEditMask control contains a concatenated series of symbols that define the characteristics of the editing requirement and the actions to be taken. The mask property enables you to define the edit mask:

• In the JADE Painter at application development time, by using the Properties dialog to define a mask of the JadeEditMask control selected on the Painter form, specifying the edit mask that you require for the control in the mask property on the Specific sheet of the dialog

• Dynamically at run time, by constructing it in your JADE application logic

This property can be translated when the value of the Schema class formsManagement property is FormsMngmt_Single_Multi (2).

The valid edit mask symbols are listed in the following table. (Note that the MMM month abbreviation for dates in the Symbol column indicates the three-character month abbreviation. Although a locale may have more than three characters for the full abbreviation, JADE uses only the first three.)

Symbol	Description	Comments
A	Alpha (entry required).	a through z or A through Z.
a	Alpha character (entry optional).	a through z or A through Z.
9	Numeric (entry required).	0 through 9.
#	Numeric (entry optional).	0 through 9.
C	Character (entry required).	Any character.
c	Character (entry optional).	Any character.
ddMMyy	Date with 2-digit year and numeric month.	Example: 230901. The date is expected in current locale order.
ddMMMyy	Date with 2-digit year and three‑character alpha month abbreviation.	Example: 23Sep01. The date is expected in current locale order and month name format.
ddMMyyyy	Date with 4-digit year and numeric month.	Example: 23092001. The date is expected in current locale order.
ddMMMyyyy	Date with 4-digit year and three‑character alpha month abbreviation.	Example: 23Sep2001. The date is expected in current locale order and month name format.
dd<d>MM<d>yy	Date with 2-digit year and numeric month. Fields separated by the same delimiter (any character).	Example: 23/09/01. The date is expected in the current locale order.
dd<d>MMM<d>yy	Date with 2-digit year and three‑character alpha month abbreviation. Fields separated by the same delimiter (any character).	Example: 23/Sep/01. The date is expected in current locale order and month name format.
dd<d>MM<d>yyyy	Date with 4-digit year and numeric month. Fields separated by the same delimiter (any character).	Example: 23/09/2001. The date is expected in current locale order.
dd<d>MMM<d>yyyy	Date with 4-digit year and three‑character alpha month abbreviation. Fields separated by the same delimiter (any character).	Example: 23/Mar/2001. The date is expected in current locale order and month name format.
dd	Day of the month.	Separate day number field.
MM	Month number.	Separate month number field.
MMM	Three-character alphanumeric abbreviation of the month.	Separate month name field in current locale format.
yy	2-digit year.	Separate 2-digit year field.
yyyy	4-digit year.	Separate 4-digit year field.
hh	Hour.	Hour number in the range 0 through 23.
mm	Minutes.	Minute number in the range 0 through 59.
ss	Seconds.	Second number in the range 0 through 59.
>	Uppercase next character.	Takes effect only if the next mask character is A, a, C, or c.
>>	Uppercase all characters following in this text box	Applies only to mask characters A, a, C, or c. field.
<	Lowercase next character.	Takes effect only if the next mask character is A, a, C, or c.
<<	Lowercase all characters following in this text box field.	Applies only to mask characters A, a, C, or c.
\	Treat the next character as a literal.	To insert a \ character into the mask, use \\. Similarly, to enter a specific locale-dependent character (for example, use \: for :).
"	Start of a text string terminated by the next double quote " symbol.	Example: ">". To insert a quote character, use \". This symbol is the double quote character only.
H<numeric>	Height of this control (label or text box) field.	Numeric can be any length. Field terminated by the next non-numeric value.
L<numeric>	Left position of this control (label or text box) field.	Numeric can be any length. Field terminated by the next non-numeric value.
T<numeric>	Top position of this control (label or text box) field.	Numeric can be any length. Field terminated by the next non-numeric value.
W<numeric>	Width of a segment (label or text box) of the mask, except for the last segment, which always extends to the right‑hand edge of the control.	Numeric can be any length. Field terminated by the next non-numeric value; for example, W30"Date"@dd/MMM/yyyy, where the label is created with a width of 30.
R	Field is right‑aligned.	Default value is left-aligned.
.	Decimal point.	Actual character expected is locale-dependent.
-	Negative sign.	Actual character expected is locale-dependent.
,	Numeric separator.	Separator is automatically inserted into the numeric as the number is entered. The actual character is locale-dependent.
/	Date separator.	Actual character is locale-dependent.
:	Time separator.	Actual character is locale-dependent.
$	Currency symbol.	Actual character is locale-dependent.
|	List of valid characters that can be entered for the character position.	For example: 'A|abc|' means only a, b, or c can be entered into the alpha field. Can only follow edit mask types A, a, C, or c.
[	Start of numeric range for previous # or 9 numeric field. Must be an integer type field.	For example: '##9[0-255]' means the 3-digit numeric field must be in the range 0 through 255.
]	End of numeric range field else a literal if there was no corresponding [ symbol.	See above (that is, the comments for the [ symbol).
@	End of current label or text box. A new field is begun. Previous field is a label if it consists only of literals.	For example, '999@-@999' to define two numeric fields split by a dash character label.
Any other symbol	Treated as a literal.	For details, see the first item in the following list.

When using the JadeEditMask class mask property, note the following points.

• The Windows Control Panel setting is used to convert a two-digit year into a four-digit year for a two-digit edit mask year of 'yy' when the value of the EnhancedLocaleSupport parameter in the [JadeEnvironment] section of the JADE initialization file is set to true. By default, years:

  • 00 through 29 become 2000 through 2029

  • 30 through 99 become 1930 through 1999

  If the value of the EnhancedLocaleSupport parameter is false (the default), the year is calculated using the current century.

• As JADE reserves the right to implement additional features in the future that will give special meaning to other symbols, it is better to enclose any text box literal that is not in the previous table in double quote symbols (that is, "") or place the \ backslash symbol in front of the literal, to avoid future conflict.

• Having a mask does not guarantee that the data is valid, as a user might enter only part of the data for a field and never complete the rest. For more details, see the isValid and isEmpty methods and the validate event method.

• The user cannot create a date with an invalid day number and month combination. For example, if a user enters 31 and then attempts to enter a month of 4 or Jun, the entry is rejected.

• For a date that has an abbreviated month, the entered characters must appear somewhere in a month name for the month to be valid for a locale-dependent month.

• An invalid day number cannot be entered for a month that has been entered, with the exception of 29th February in leap years. The validity of the leap year cannot be known until entry of the year is completed. For example, entering 29/02/201 is not rejected because the completion of the year is still uncertain (that is, the final year value has yet to be entered).

• Two-digit year fields must have both digits entered before they are considered complete. Similarly, four-digit year fields must have all four digits entered before they are considered complete.

• For dates with alphanumeric month abbreviations, the first character of the month is always converted to uppercase (for example, aug is converted to Aug).

• If the mask has a label field in the control, by default the text of that label is sized to fit.

  The next field is displayed directly after the label text, which is drawn transparently on the JadeEditMask control at paint time, by using the font of the control.

  Areas of the JadeEditMask control that are not text boxes are drawn using the background color of the parent.

• Automatically sized text box fields are created with a size that can accommodate the largest possible text entry in the field. This is necessary because a text field with an edit mask of 'aaa', for example, with text of WWW takes up considerably more space than a field with iii text. In addition, because the prompt character requires more space than the character for which it is prompting, the size can be larger than required.

• Tabbing or setting the focus to a JadeEditMask control gives the focus to the first defined text box that can have data entered. For a control with multiple text boxes, the Tab key operates as though those text boxes were inserted between the JadeEditMask control and the next control in the tab order of the form (in order of their definition).

• Creating a text box containing all literal values is valid and is treated effectively as read-only. These text boxes, which cannot have values entered, are ignored when focus is assigned and when tabbing between text boxes, unless the control does not contain any text box field that can have data entered.

• For numeric fields, the end of the field is defined as the first non-numeric edit character, an optional numeric value following a mandatory numeric value, or an optional numeric value following a mandatory decimal place. For example, '#99#9' defines the ##9 and #9 numeric fields while '#99.9#9' defines the #99.9 and #9 numeric fields.

• Do not use right-aligned text box fields for anything other than fields that accept only numeric data, as the caret remains at the same position. If your field has embedded literal characters, the arrow key would need to be used to position the caret at the next entry segment.

• If no mask is defined, the control acts as a normal TextBox control.