ComponentOne Input for WinForms
Masked Input
Input for WinForms Tutorials > Masked Input

In this tutorial, you will learn how to use edit mask to facilitate and restrict user input.

  1. Create a new Windows Application project. Place the following components on the form as shown in the figure:
    • C1ExpressConnection1 (C1.Data.Express.C1ExpressConnection)
    • C1ExpressTable1-3 (C1.Data.Express.C1ExpressTable)
    • Label1-4 (all of type System.Windows.Forms.Label)
    • C1TextBox1-7 (C1.Win.C1Input .C1TextBox)
    • C1Label1-4 (C1.Win.Input.C1Label)
    • C1DbNavigator1 (C1.Win.C1Input .C1DbNavigator)
    • Button1 (System.Windows.Forms.Button)

    Note: The labels in blue are all of type System.Windows.Forms.Label. The Text property for each label is as it appears on the form.
  2. From the Properties window, set the following basic properties for the Label, C1Label, and Button controls:
    Control Property Value
    Label1 Name labStoredExpNumber
    Text <stored value>
    Label2 Name labStoredDateTime
    Text <stored value>
    Label3 Name labStoredPhone
    Text <stored value>
    Label4 Name labStoredMultiline
    Text <stored value>
    C1Label1 Name labCompanyName
    Text labCompanyName
    C1Label2 Name labCustomerID
    Text labCustomerID
    C1Label3 Name labOrderDate
    Text labOrderDate
    C1Label4 Name labFreight
    Text labFreight
    Button1 Name btnClose
    Text Close
  3. Select the C1ExpressConnection1 component, go to the Properties window, open the ConnectionString property. Add the following to the ConnectionString property: Provider=Microsoft.Jet.OLEDB.4.0;Data Source=" Documents\ComponentOne Samples\Common ".
  4. Set the properties of C1ExpressTable1-3 as follows:
    Control Property Value
    C1ExpressTable1 ConnectionComponent C1ExpressConnection1
    DbTableName Customers
    C1ExpressTable2 ConnectionComponent C1ExpressConnection1
    DbTableName Orders
    C1ExpressTable3 ConnectionComponent C1ExpressConnection1
    DbTableName <Composite…>

    * See steps below.

* Selecting the <Composite…> value for the C1ExpressTable3 opens the Composite Table Editor. In the editor, complete the following steps:

  1. Select the Add table button to add Customers table.
  2. Select the Add table button again to add Orders table related as One-to-Many (1-M).
  3. Select the Add join button. The Add new join dialog box appears.
  4. Select CustomerID for the Parent field and Child field.
  5. Click OK.
  6. The new Customers.CustomerID – Orders.CustomerID join appears in the window; click OK.
  7. To bind controls to the data source, set the following properties:
    Note: If all of the fields in the CompositeTable are not appearing in the DataField drop-down, select C1ExpressTable3 and open the C1ExpressTable Tasks menu by clicking the smart tag (). In the C1ExpressTable Tasks menu, click Retrieve Fields. You may have to set the DataSource and DataField properties again.
    Control Property Value
    C1DbNavigator1 DataSource C1ExpressConnection1
    DataMember CompositeTable
    labCompanyName DataSource C1ExpressConnection1
    DataField CompositeTable.CompanyName
    labCustomerID DataSource C1ExpressConnection1
    DataField CompositeTable.CustomerID
    labOrderDate DataSource C1ExpressConnection1
    DataField CompositeTable.OrderDate
    labFreight DataSource C1ExpressConnection1
    DataField CompositeTable.Freight
    C1TextBox5 DataSource C1ExpressConnection1
    DataField CompositeTable.CustomerID
    C1TextBox6 DataSource C1ExpressConnection1
    DataField CompositeTable.OrderDate
    C1TextBox7 DataSource C1ExpressConnection1
    DataField CompositeTable.Freight
  8. The labels located to the right of the C1TextBox1-4 controls display the current Value property of the corresponding C1TextBox. To synchronize them with C1TextBox1-4, create event handlers C1TextBox1(…4)_ValueChanged:

    To write code in Visual Basic

    Visual Basic
    Copy Code
    Private Sub C1TextBox1_ValueChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1TextBox1.ValueChanged
        Try
            labStoredExpNumber.Text = CType(Me.C1TextBox1.Value, String)
        Catch
            labStoredExpNumber.Text = ""
        End Try
    End Sub
     
    Private Sub C1TextBox2_ValueChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1TextBox2.ValueChanged
        Try
            labStoredDateTime.Text = CType(Me.C1TextBox2.Value, String)
        Catch
            labStoredDateTime.Text = ""
        End Try
    End Sub
     
    Private Sub C1TextBox3_ValueChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1TextBox3.ValueChanged
        Try
            labStoredPhone.Text = CType(Me.C1TextBox3.Value, String)
        Catch
            labStoredPhone.Text = ""
        End Try
    End Sub
     
    Private Sub C1TextBox4_ValueChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles C1TextBox4.ValueChanged
        Try
            labStoredMultiline.Text = CType(Me.C1TextBox4.Value, String)
        Catch
            labStoredMultiline.Text = ""
        End Try
    End Sub
    

    To write code in C#

    C#
    Copy Code
    private void c1TextBox1_ValueChanged(object sender, System.EventArgs e)
    {
        try
        {
            labStoredExpNumber.Text = (string)this.c1TextBox1.Value;
        }
        catch
        {
            labStoredExpNumber.Text = "";
        }
    }
     
    private void c1TextBox2_ValueChanged(object sender, System.EventArgs e)
    {
        try
        {
            labStoredDateTime.Text = (string)this.c1TextBox1.Value;
        }
        catch
        {
            labStoredDateTime.Text = "";
        }
    }
     
    private void c1TextBox3_ValueChanged(object sender, System.EventArgs e)
    {
        try
        {
            labStoredPhone.Text = (string)this.c1TextBox1.Value;
        }
        catch
        {
            labStoredPhone.Text = "";
        }
    }
     
    private void c1TextBox4_ValueChanged(object sender, System.EventArgs e)
    {
        try
        {
            labStoredMultiline.Text = (string)this.c1TextBox1.Value;
        }
        catch
        {
            labStoredMultiline.Text = "";
        }
    }
    
  9. C1TextBox1 allows you to enter numbers with or without fractional part and with optional exponent. It uses the WhenNextStarted mode of showing mask literals, so the decimal point appears only when necessary, when the user starts entering the decimal part.

    For C1TextBox1:

  10. Set the EditMask property to !###0.^999e#9.

    Here '#' is an optional position for a digit or sign, '9' is an optional position for a digit, '0' is a required position for a digit, '!' is a special character specifying right justification for the following text, '^' cancels right justification mode, 'e' – a literal.

  11. Then expand the MaskInfo property and set ShowLiterals to WhenNextStarted.
    Note: C1TextBox and C1NumericEdit support a special edit mode, NumericInput mode facilitating input of any numeric data type. It is usually more convenient for numeric input than edit mask. Try NumericInput before using an edit mask for numeric data.
  12. C1TextBox2 is used for entering a date/time value.

    For C1TextBox2:

  13. Set the EditMask property to !90/90/9900 90:90 >PM.

    There are two new special characters used in this mask: '>' causes the next characters to be converted to upper case, 'P' is a non-standard special character (custom placeholder) allowing entering either 'A' or 'P'.

  14. To define a custom placeholder, expand the MaskInfo property and press the ellipsis button in the CustomPlaceholders property to open the Collection Editor. In the Collection Editor, add a new item. Set the properties of the newly added item:
    Property Value
    Placeholder P
    LookupChars AP

    Thus the letter 'P' represents a position in edit mask where the user can type 'A' or 'P'.

  15. Now, we want to specify that entered date/time values are stored in the database in a compact form without literals. For example, the value "11/_8/2002 _1:42 PM" is stored as "11*82002*142P".

    To enable this storage format, set SaveBlanks to True and SaveLiterals to False (both properties are contained in MaskInfo). Also, change StoredEmptyChar from default '_' to '*' to store asterisk in blank positions. If you set SaveBlanks to False, SaveLiterals to True, blank positions will not be saved in the database, the above data will be saved as "11/8/2002 1:42PM".

    Note: C1TextBox and C1DateEdit support a special edit mode, DateTimeInput mode facilitating input of date/time data. It is usually more convenient for date/time input than edit mask. Try DateTimeInput before using an edit mask for date/time data.
    Set up the C1TextBox3 control for telephone number input with mask (999) 0099-00099. Here ‘9’ is an optional digit position, ‘0’ is a required digit position.

    For C1TextBox3:

  16. Set the EditMask property to (999) 0099-00099.
  17. Expand the MaskInfo property and set AutoTabWhenFilled to True. This will automatically move the input focus to the next control once the user fills the last mask position.
  18. The C1TextBox4 control demonstrates multiline mask input.

    For the C1TextBox4:

    • Set its Multiline property to True.
    • Set its ScrollBars property to Vertical.
    • Set the EditMask property to the following:
      "First Name:  "CCCCCCCCCCCCCCC\n"Last Name: "CCCCCCCCCCCCCCCCCCCC\n"
      
    • Date of Birth:  "!90/90/9900^\n"Work Status:  "CCCCCCCCCCCCCCC\n"Salary:  
      
    • $"!######0.^99
      

      Here ‘\n’ represents a line break.

    • Expand the MaskInfo property and set SaveBlanks to True.

    This ensures that all positions left blank by the user are saved as spaces. If SaveBlanks is set to False, optional positions not filled by the user will be ignored. Additionally, you can set SaveLiterals to False, which will prevent saving literal texts, so only the information typed by the user is saved.

  19. All the previous controls were unbound. Let us also configure some data bound C1Label and C1TextBox controls. They are located at the bottom of the form. Their data binding properties were set on Step 4. Set their other properties as follows:
    Control Property Value
    labCustomerID MaskInfo.EditMask >LLLLL
    C1TextBox5 EditMask >LLLLL
    labOrderDate FormatType CustomFormat
    CustomFormat M/d/yyyy
    MaskInfo.EditMask !90/90/0000
    C1TextBox6 FormatType CustomFormat
    CustomFormat M/d/yyyy
    EditMask !90/90/0000
    labFreight FormatType CustomFormat
    CustomFormat $ ####0.##
    MaskInfo.EditMask $ !99990.^99
    C1TextBox7 FormatType CustomFormat
    CustomFormat $ ####0.##
    EditMask $ !99990.^99

Run the program and observe the following:

See Also