Introduction to the Masked Edit Control

Description

To add a masked edit control to your form, from the Additional tab of the Tool Palette, click the TMaskEdit button and click on the form. To dynamically create a masked edit objec, declarea variable of type TMaskEdit. Using the new operator, specify the owner of the control. You must also specify the parent of the variable. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	TMaskEdit *Mascot = new TMaskEdit(Form1);
	Mascot->Parent = Form1;
}
//---------------------------------------------------------------------------

A masked edit control is created like theclassic edit control. If you want to make a true masked edit object, set its properties as needed.

1. In the Additional section of the Tool Palette, click TMaskEdit and click the form
2. In the Object Inspector, click Name, type medOrderDate and press Enter

Characteristics of the Masked Edit Control

Editing the Mask

The most important property of a masked edit control, which sets it apart from the (traditional) edit control, is its ability to control what the user can and cannot enter in the text side. To configure this text, the TMaskEdit class is equipped with a property named EditMask. To visually set it, in the Object Inspector, click the EditMask field to reveal its ellipsis button. You have two options:

• If you are familiar with the masking properties of this control, you can type a value using the appropriate symbols. Otherwise you should use an appropriate dialog box to guide you. You have two alternatives. You can double-click the empty area of the EditMask field or you can click the ellipsis button. This would call the Input Mask Editor dialog box
  
  
  
  Once there, you have various alternatives. The easiest way is to select one of the available formats in the Sample Masks list. Once you select a sample, its formatted mask displays in the Input Mask edit box. If the format is satisfying, you can click OK. Otherwise, you can add or delete symbols in the Input Mask edit box as you see fit.
• If none of the samples matches your desired format and you know the symbols used, you can type your own. You can also check masks created for foreign languages to see if one of them would have the mask you need. To do this, click the Masks… button. This would call the Open Mask File dialog box:
  
  
  
  Click one file with a .dem extension and click OK. With the new mask in the Input Mask Editor, examine the samples in the Sample Masks list and select one. You can still customize any of the available masks.
  
  Another alternative is to create your own list of masks. To do this, follow the format used to create a mask. This is:
  
  Name | Sample | Mask
  
  This line is made of three sections. The first and the second, then the second and the third are separated by a beam. To see a sample file, using Notepad, locate the C:\Program Files (x86)\Embarcadero\RAD Studio\7.0\bin folder. After changing the Files of Type to All files, click one of the files with .dem extensions:
  
  
  
  Click Open:
  
  

Create a new file following the example. Each mask is typed on its own line and press Enter at the end of each mask. To save the file, locate the C:\Program Files (x86)\Embarcadero\RAD Studio\7.0\bin folder. In the Save dialog box, change the Save As Type to All Files. Type a name in one word followed by an extension .dem extension. To use your list of masks, invoke the Input Mask Editor, click Masks… Locate the C:\Program Files (x86)\Embarcadero\RAD Studio\7.0\bin folder. Change the Files of Types to All files. Click the file you created and click Open.

You can also set a mask programmatically using the symbols appropriate for the masks. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	// Mask for an 8 character file name + 3-character extension
	// The first character is automatically converted to uppercase
	// After the first character, the user can enter an alphabetical
	// character or a digit to complete the 8 characters.
	// The other 7 characters and the extensions are converted to lowercase
	edtFileName->EditMask = ">L<aaaaaaa.<LLL;1;_";
}
//---------------------------------------------------------------------------

As a text-based control, the content of the MaskEdit control is represented by the Text property, which is a UnicodeString string. Following the EditMask you had set in the Input Mask Editor editor, you can use a default text that would display when the control opens. To set this text, on the Object inspector, click Text and type a value that abides by the rules of the EditText field. At design time, C++Builder will assist you and make sure that the value you type is appropriate. At runtime also, the user will have to follow the rules of the mask.

When a mask is configured for a masked edit control, the compiler reinforces the rule to make sure the user would follow number and types of characters allowed in the edit box. If you add a masked edit control but do not apply a mask to it, you can limit the number of characters that the user can enter in the box. The maximum number of characters allowed is set using the MaxLength property. This property has any effect only if no mask is applied to the control. At design time, type an integer value for the property. At runtime, assign an appropriate value to the control.

The IsMasked Boolean property can be used to check whether a masked edit control has been configured with a mask already.

1. While the masked edit control is still selected on the form, in the Object Inspector, click EditMask and click its ellipsis button
2. In the Input Mask Editor dialog box, in the Sample Masks list, click Date
3. In the Input Mask text box, add 00 to the 00 section to get !99/99/0000;1;
    
   
4. Click OK
5. In the Additional section of the Tool Palette, click TMaskEdit and click the form
6. In the Object Inspector, click Name, type medOrderTime and press Enter
7. Click EditMask and click its ellipsis button
8. In the Sample Masks list of the Input Mask Editor dialog box, click Long Time
9. In the Input Mask text box, remove the last 00 to get !90:00 >LL;1;_
    
   
10. Click OK
11. Complete the design of the form as follows:
     
    

    Control Name Caption Label   O&rder Date: MaskEdit  medOrderDate    Label   Order Ti&me: MaskEdit medOrderTime    LabeledEdit edtFlavor  &Flavor: LabeledEdit edtContainer C&ontainer: LabeledEdit edtIngredient &Ingredient: LabeledEdit edtScoops &Scoops: LabeledEdit edtTotalOrder Or&der Total:

The main event of the MaskEdit control occurs when the content of the control has been altered. The compiler takes care of validating the characters and symbols while the user is editing the edit box. When the user has finished and presses Enter or Tab to possibly shift the focus to another control, a notification is sent to the operating system. If the value entered in the control does not conform to the EditMask property, an error is thrown and the application may stop responding. For this reason, you should use the MaskEdit control only when appropriately needed; or you should write an event handler or function that would deal with errors of this control.