[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Collapse]WPF Controls
 [Expand]What's Installed
 [Expand]Common Concepts
 [Expand]MVVM Framework
 [Collapse]Controls and Libraries
  [Expand]Data Grid
  [Expand]Ribbon, Bars and Menu
  [Expand]Charts Suite
  [Expand]Pivot Grid
  [Expand]Rich Text Editor
  [Expand]Tree List
  [Expand]Gauge Controls
  [Expand]Map Control
  [Expand]Layout Management
  [Expand]Windows Modern UI
  [Collapse]Data Editors
    Included Components
   [Expand]Implementation Details
   [Collapse]Getting Started
    [Collapse]How To: Create a Registration Form
      Starting Point
      Lesson 1 - Create Layout
      Lesson 2 - Bind Data Editors
      Lesson 3 - Customize Editors
      Lesson 4 - Implement Input Validation using ValidationRules
      Lesson 5 - Implement Input Validation using IDataErrorInfo
     How to: Enable Masked Input (Text Editor)
     How to: Create a Functional ButtonEdit
     How to: Create a ComboBoxEdit and Bind it to Data
     How to: Customize a DateEdit
     How to: Create and Customize a ProgressBarEdit
     How to: Create and Customize a RangeTrackBarEdit
     How to: Create and Add Palettes in PopupColorEdit
     How to: Customize a SpinEdit to Display Currency Values
     How to: Create a SearchLookUpEdit and Bind it to Data
   [Expand]Editor Types
   [Expand]Common Features
   [Expand]Range Control
   [Expand]Visual Elements
   [Expand]End-User Capabilities
  [Expand]Navigation Controls
  [Expand]Spell Checker
  [Expand]Property Grid
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Gantt Control
  [Expand]Diagram Control
  [Expand]Windows and Utility Controls
   Dialogs, Notifications and Panels
  [Expand]Scheduler (legacy)
 [Expand]Scaffolding Wizard
  Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Lesson 3 - Customize Editors

Open the previously created project or RegistrationForm.Lesson2 to follow along. The RegistrationForm.Lesson3 project from the DXEditorsTutorial example contains the results of this part.

Expanded Step 1 - Customize the FirstName, LastName, and Gender editor fields

If you run the application, you will notice the editor boxes are empty. For instance, there are two unnamed editors in the first LayoutItem (Name), and end-users have to guess that the left and right editors refer to the First Name and Last Name fields, respectively. If you take a look at the Google registration form, you can see the input boxes display gray indicator text when editor values are blank. The NullText feature of DXEditors supports the same.

There are four properties, available on every DevExpress editor, which effect the displayed NullText.

  • BaseEdit.NullValue is the value interpreted by the editor as its blank value (null or System.DBNull.Value by default).
  • BaseEdit.NullText specifies the display text when the editor's value equals NullValue.
  • BaseEdit.ShowNullText determines whether or not the editor will display a NullText in the blank condition.
  • BaseEdit.AllowNullInput controls whether or not an end-user can clear the editor.

Use the NullText feature for the FirstName, LastName, and Gender editors by setting the NullText properties for the editors.

If you run the application right now, you will see that the FirstName and LastName editors correctly show gray text, but the Gender editor does not. This is due to the fact that the Gender ComboBoxEdit is bound to the RegistrationViewModel.Gender property whose default value is -1. The ComboBoxEdit does not know to interpret this value as blank, so set the ComboBoxEdit.NullValue property to -1.

Please note the NullValue property is set with the full XAML property element syntax. An attribute syntax of the form NullValue="-1" would be processed as the -1 string value.

Expanded Step 2 - Customize the Email field

The email field should be specially formatted to restrict invalid input. The Masked Input feature of the DXEditors provides restricted data input as well as formatted data output. Before continuing, please open the Mask Types documentation article in a separate window. This article describes each Mask Type. Email addresses use a complex string format, so the RegEx mask will be useful. Review the Mask Type: Extended Regular Expressions topic for a table of meta-characters you will use to build the Email mask.

  • Set the TextEdit.MaskType property to RegEx.
  • It is necessary to format each of the text sections (&lt;sometext&gt;@<sometext>.<sometext>).

    • The first section of the address pattern accepts lowercase and capital letters, digits, dots, the percentage symbol, underscore, apostrophe and the plus and minus symbols: [a-zA-Z0-9.'_%+-].
    • The “@” symbol is the second element of the pattern.
    • The second text section forming the email domain name accepts lowercase and capital letters, digits, period, and hyphen: [a-zA-Z0-9.-].
    • A period “.” immediately follows the domain name section.
    • The final text section admits lowercase and capital letters. This section is 2, 3, or 4 characters in length: [a-zA-Z]{2,4}.
  • Combine the mask section patterns and assign the result to the TextEdit.Mask property: Mask="[a-zA-Z0-9.'_%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}".

To suppress validation errors when the editor is empty, set the TextEdit.MaskIgnoreBlank property to True.

To permit focus to leave the editor while in a validation error state, set the BaseEdit.InvalidValueBehavior property to AllowLeaveEditor. If this property is assigned to the InvalidValueBehavior.WaitForValidValue, the editor locks the application until a correct value is entered.

The resulting code is the following.

Expanded Step 3 - Customize the Birthday field

You will need to limit the input to a particular range of acceptable birthdates. DateEdit supports a DateEdit.MinValue and DateEdit.MaxValue property. Set corresponding properties in the RegistrationViewModel class and then bind the DateEdit.MinValue and DateEdit.MaxValue properties to the ViewModel properties.

Running the application and clicking the Drop Down button of the Birthday field displays a calendar for selecting dates from the defined range. It is necessary to extend the input capability to support typing dates directly in the input box. Text input of dates is enabled by default with the caveat that the date range specified by the DateEdit MaxDate and MinDate is not applied. Additionally, the DateEdit will lock the application until a valid date is inputted; the default value of the DateEdit.InvalidValueBehavior property is WaitForValidValue. Setting this property to the AllowLeaveEditor allows focus to leave the editor even when its input has not been validated.

The DateEdit dropdown can alternatively display the DatePicker control instead of the Calendar. To use the DatePicker, set the BaseEdit.StyleSettings property to DateEditPickerStyleSettings.

Expanded Step 4 - Customize the Gender field

The Gender field is represented by a ComboBoxEdit control which provides two options: Male, Female. The Gender.cs file in your project contains code that provides a list of these possible options.

Bind the GenderList to the ComboBoxEdit.ItemsSource property:

As seen above, the ListBoxEdit.ValueMember and ListBoxEdit.DisplayMember properties are also set for the ComboBoxEdit control . The ValueMember sends the property value of the ComboBoxEdit.SelectedItem (a Gender in this case) with the matching property name to the ComboBoxEdit.EditValue. The DisplayMember shows the property value with the matching property name on the screen.

If you run the application right now, you can see that the Gender ComboBoxEdit does not allow values to be directly typed into its input box. You will want to correct this. The end-user will need the following input capabilities.

  • Clicking a value from the drop down.
  • Typing a value in the editor box.
  • Displaying the drop down list as a value is being typed.
  • The Drop Down list remains unchanged when the user is typing input.
  • Pressing the Enter key to submit typed input.

Implement the necessary behavior.

  • The editor already supports selecting values from the drop down list.
  • Typing in the Gender ComboBoxEdit is disabled because the BaseEdit.ValidateOnTextInput property is set to True by default. For now, set the ValidateOnTextInput property to False. In the next lesson, you will know how the ValidateOnTextInput property functions in greater detail.
  • Set the LookUpEditBase.ImmediatePopup property to True to display the drop down list as the end-user is typing.
  • DXEditors may filter a drop down list for matches to the input value. To disable this behavior, set the LookUpEditBase.IncrementalFiltering property to False.
  • DXEditors support an AutoComplete feature. The text typed by an end-user in an edit box is automatically completed for a value matching a drop down item.

The markup for the Gender ComboBox is shown below.

Expanded Result

The resulting form is displayed below.

Expanded See Also

Is this topic helpful?​​​​​​​