Home

VCL Controls: The Masked Edit Control

 

Introduction to the Masked Edit Control

 

Description

The masked edit is a special edit control that provides more control over text entered or displaying in an edit box. The biggest difference between the edit and the masked edit controls is the masking possibilities available on the latter.

Practical LearningPractical Learning: Introducing the Masked Edit Control

  1. To start a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
  2. Change the Caption of the form to Clarksville Ice Cream
  3. In the Tool Palette, click Additional
  4. Click TLabeledEdit and click the form
  5. In the Object Inspector, cchange the following properties:
    Caption: &Flavor:
    Name: ledFlavor
  6. While the labeled edit control is still selected on the form, in the Object Inspector, click LabelPosition
  7. Change its value to lpLeft
  8. While the labeled edit control is still selected on the form, in the Object Inspector, click LabelSpacing
  9. Type 20 and press Enter
  10. Using labeled edit controls, complete the design of the form as follows:
     
    Clarksville Ice Cream
    Control Name Caption
    TLabeledEdit LabeledEdit edtFlavor  &Flavor:
    TLabeledEdit LabeledEdit edtContainer C&ontainer:
    TLabeledEdit LabeledEdit edtIngredient &Ingredient:
    TLabeledEdit LabeledEdit edtScoops &Scoops:
    TLabeledEdit LabeledEdit edtTotalOrder Or&der Total:

Creating a Masked Edit Control

To support the masked edit control, the VCL provides the TMaskEdit class. This class is derived from TCustomMaskEdit, which is based on the TCustomEdit class:

 

TMaskEdit Inheritance

 

To add a masked edit control to your form, from the Additional tab of the Tool Palette, click the TMaskEdit button Mask Edit 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.

Practical LearningPractical Learning: Introducing the Masked Edit Control

  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

    Input Mast Editor

    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:

    Mask

    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:

    Mask

    Click Open:

    Mask

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;_";
}
//---------------------------------------------------------------------------

The Text of a Masked Edit Control

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.

Is It Masked

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

Practical LearningPractical Learning: Masking the Control

  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;
     
    Input Mask Editor
  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;_
     
    Input Mask Editor
  10. Click OK
  11. Complete the design of the form as follows:
     
    Clarksville Ice Cream
    Control Name Caption
    Label Label   O&rder Date:
    MaskEdit  Mask Edit medOrderDate   
    Label Label   Order Ti&me:
    MaskEdit Mask Edit medOrderTime   
    LabeledEdit LabeledEdit edtFlavor  &Flavor:
    LabeledEdit LabeledEdit edtContainer C&ontainer:
    LabeledEdit LabeledEdit edtIngredient &Ingredient:
    LabeledEdit LabeledEdit edtScoops &Scoops:
    LabeledEdit LabeledEdit edtTotalOrder Or&der Total:

MaskEdit Events

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.

 
 
 
 

Home Copyright © 2010-2011 FunctionX, Inc.