Các công cụ phát triển phần mềm > Nhập liệu (Data Entry) > Biểu mẫu template (Template Form) > Thành phần của Form nhập liệu > Text Box

The Phoebus library allows you to use masks during editing. Masks provide restricted data input as well as formatted data output. The sections in this topic provide general information on the mask functionality:

Phoebus cho phép bạn sử dụng mặt nạ nhập liệu trong suốt quá trình chỉnh sửa. Với mặt nạ nhập liệu, dữ liệu nhập vào phải tuân theo định dạng đã được định nghĩa từ trước. Các phần trong chủ đề này cung cấp những thông tin chung về chức năng mặt nạ nhập liệu.

You can use masks if you need to ensure that end-users enter values only in a particular form. Masks are in effect only in edit mode. When an editor is not in edit mode its display text is formatted according to the editor's RepositoryItem.DisplayFormat format.

Bạn có thể dùng mặt nạ nhập liệu nếu bạn cần đảm bảo rằng người dùng cuối nhập vào các giá trị chỉ trong một hình thức đặt biệt. Mặt nạ nhập liệu chỉ có hiệu lực trong chế độ chỉnh sửa. Khi người dùng không ở trong chế độ chỉnh sửa

The LookUpEdit, GridLookUpEdit, MemoEdit, MemoExEdit and ImageComboBoxEdit controls do not support editing in masked mode.

Using masks in editors is useful when the entered string should match a specific format. For instance, a text editor should accept date/time values in 24-hour format only, or only numeric values. Another example is entering a phone number within an editor (an end-user needs to enter only digits, while hyphens should be automatically skipped while editing). To support these and many other data input formats the masked mode can be used.

An editor's mask settings can be accessed via the RepositoryItemTextEdit.Mask property of the editor's TextEdit.Properties object. The RepositoryItemTextEdit.Mask property represents an instance of the MaskProperties class and this contains mask settings (mask type, mask, whether the mask's literal characters should be saved to the edit value, etc).

mask01

At design time you can use the Mask Editor to customize the mask settings. The editor provides multiple predefined masks. It's also possible to create custom masks. The editor's Test Input box allows you to test the selected mask. To invoke the editor click the ellipsis button (...) for the RepositoryItemTextEdit.Mask property in the Properties grid.

mask02

To enable masked input select the required mask type via the MaskProperties.MaskType property and specify a mask string via the MaskProperties.EditMask property. A mask string identifies a data input pattern. You can use either predefined mask strings or compose your own mask expressions. Mask strings should be set according to the mask type, the available mask types are listed in the following table:

Mask Type	Use this mask if...	Description	Samples
None		Masked mode is disabled.
DateTime DateTimeAdvancingCaret	...an editor should accept date/time values in a specific format.	Masks of the DateTime/DateTimeAdvancingCaret type significantly simplify inputting date/time values. Predefined masks can be used to enter values using common date/time patterns. It's also possible to create custom masks that specify which parts (year, month, day, hour, minute, etc) of a date/time value can be edited. The syntax used for these masks is similar to the date/time formats described in the Date and Time Format Strings topic in MSDN. The data input pattern imposed by the mask is affected by the current culture's settings. These settings can be customized via the Regional Options dialog in the control panel. See the Mask Type: Date-time topic for more information.	EditMask: D (long date pattern); Current culture: English (USA) EditMask: yyyy-MMM-d, HH:mm:ss (custom date pattern); Current culture: French (France)
Numeric	...an editor should accept numeric values in a specific format.	Masks of the Numeric type significantly simplify the input of numeric values (currency, integer, float, etc). Masks in this mode allow numeric values to be entered using various common and custom patterns. It's possible to specify the number of optional and required digits to the left and to the right of the decimal separator, whether to display thousand separators, etc. The syntax used for these masks is similar to the numeric formats described in the Numeric Format Strings topic in MSDN. Specific masks are dependent upon the current culture's settings. See the Mask Type: Numeric topic for more information.	EditMask: c (currency); Current culture: English (USA) EditMask: # ##0.00 $;(# ##0.00 $) (custom); Current culture: French (France)
Simple	...the string an end-user can enter is of a fixed format (without alternatives) and a fixed length (for instance, phone numbers and alpha-numeric sequences).	This mask type also supports optional characters (for instance, it's possible to specify that the code of a phone number should contain 0 to 3 digits). Any auxiliary characters can be included in these masks and these auxiliary characters will be displayed in the edit box as is and will be skipped while editing (for instance, hyphens in phone numbers). See the Mask Type: Simple topic for more information.	EditMask: (999)000-00-00 (phone number)
Regular		In this mode masks use the simplified regular expression syntax, which is similar to the one that was implemented in version 2 of the XtraEditors. This mode is designed for backwards compatibility. Instead, use the RegEx mode which implements Extended Regular Expressions which give you more flexibility to control data input. For information on the regular expression syntax used in this mode see the Mask Type: Simplified Regular Expressions topic.
RegEx	... the length of the string an end-user can enter is not fixed; or ... the value can be entered using one of several alternative forms; or ... characters only from a specific range can be entered at a specific position; or ... the auto-complete feature should be available (an end-user enters text and the editor completes this variant if there are no other alternatives)	In this mode you can construct masks using Extended Regular Expressions. This gives you great flexibility to control data input. For instance, it's possible to create a single mask that will allow end-users to enter a time value using either the 12-hour or 24-hour format. See the Mask Type: Extended Regular Expressions topic for information on the regular expressions syntax used in this mode. The syntax used by masks in this mode is similar to the syntax defined by the POSIX ERE specification.	EditMask: ((\+\d)?$\d{3}$)?\d{3}-\d\d-\d\d (several valid forms to enter a phone number)

The MaskProperties class that encapsulates the mask functionality provides a number of additional customization settings. The following table lists which options are in effect for various mask types (such options are indicated using the icon):

Option	MaskType.DateTime	MaskType.Numeric	MaskType.Simple	MaskType.Regular	MaskType.RegEx
BeepOnError
SaveLiteral
IgnoreMaskBlank
PlaceHolder
ShowPlaceHolders
AutoComplete

For all mask types the Boolean MaskProperties.BeepOnError property is available. Set this property to true to enable beeping when an end-user tries to type an invalid character. Suppose a mask of Numeric type is used. In such cases, an editor will produce a beep sound each time an end-user tries to type a non-numeric character.

For the Simple and Regular mask types you can specify whether constantly displayed mask characters (literals) are included in an editor's value. In other words you can control whether such characters appear in the value obtained via the BaseEdit.EditValue property. The MaskProperties.SaveLiteral property must be set to false to make such characters inaccessible. In such an instance, if the displayed value is '(555)123-76-34', the value obtained via the BaseEdit.EditValue property is '5551237634'.

For the Simple, Regular and RegEx mask types the placeholders in the edit box are represented using the special character determined by the MaskProperties.PlaceHolder property. You can use this property to change the default placeholder (the "_" character).

For the RegEx mask type placeholders can be hidden by setting the MaskProperties.ShowPlaceHolders property to false. The following images show an empty text editor whose mask is set to "CODE-\d{3}-NO-\d{3}" (the mask type is RegEx):

(the ShowPlaceHolders property is set to true; The '_' symbol is used as a placeholder.)

(the ShowPlaceHolders property is set to false)

For the Simple, Regular and RegEx mask types the MaskProperties.IgnoreMaskBlank property is in effect. If this property is set to true an empty editor can lose focus. If the editor's value is only partially completed focus cannot be moved from the editor until an end-user enters the entire value or removes the value by clearing the edit box.

If this property is set to false focus cannot be moved from the editor until the value is completed entirely.

An error in the editor is indicated by an error icon:

To provide an appropriate response when an invalid value is entered the BaseEdit.InvalidValue event can be handled.

For the RegEx mask type the automatic completion feature can be enabled. In this mode, the editor will try to complete a value which has been partially entered by an end-user. Use the MaskProperties.AutoComplete property to specify which auto-complete mode is enabled:

Auto-complete mode

Description

Strong

Each time an end-user types a character the editor determines if the following placeholder can be filled automatically. If only a specific character can be inserted in this position the editor automatically displays this character and moves the caret to the right of this character.

Assume that the edit mask is set to "\R{MonthNames}" (the editor will accept the names of the months). When the "M" character is entered by an end-user in the empty edit box the second placeholder is filled automatically with the "a" character since there are two months starting with "M" (March and May) and both contain an "a" in the second position.

If the "r" character is pressed then the editor automatically completes the input and displays "March":

Optimistic

When an end-user enters a character in the empty edit box for the first time the editor automatically fills all the following placeholders with the default values. For placeholders that accept only numeric values the '0' character is the default. For placeholders that accept word characters the "a" character is the default.

Assume that the mask is set to "\R{MonthNames}". After the "M" character is entered the editor inserts the "May" month automatically (this is the shortest variant between the two alternatives - March and May):

For instance, the edit mask is set to "\d{3}-\d{2}-\d{2}" (a telephone number pattern). When the first character is entered (for instance, "1") in the empty edit box the following placeholders are automatically filled with the default values (the "0" characters) and selected:

If the MaskProperties.AutoComplete property is set to AutoCompleteType.Default the editor will use the AutoCompleteType.Strong auto-complete mode in this case.

Mặt nạ nhập liệu (Masks)

Mặt nạ nhập liệu (Masks)