Mask Type: DateOnly
- 6 minutes to read
The DateOnly mask type allows users to enter values of the DateOnly type. DateOnly masks support the Gregorian, Korean, Taiwanese, and Thai Buddhist calendars.
public DateOnly DateOnlyValue { get; set; } = new DateOnly(2020, 8, 24);
// ...
textEdit.EditValue = DateOnlyValue;
Standard Masks
The table below contains standard masks that you can select on the main page of the Mask Settings dialog. Note that patterns depend on the current culture. For example, the same input mask can specify different patterns in the U.S. and France. A culture DateOnly format is defined by the CultureInfo.DateTimeFormat property. Users can change the regional format in the Windows Settings panel.
Mask | Description | Sample |
|---|---|---|
| Short “mm/dd/yyyy” date format | 8/24/2020 |
| Long date format | Monday, August 24, 2020 |
| DateOnly in the RFC1123 format | Mon, 24 Aug 2020 |
| ISO 8601 round-trip format | 2020-08-24 |
| Full month name and day number | August 24 |
| Full month name and year number | August 2020 |
Custom Masks
You can combine custom mask placeholders to create custom masks of any complexity. For example, to create the “Month name Day Year” mask, combine custom mask placeholders as follows: MMMM d yyyy.
DevExpress editors support the following custom specifiers and placeholders:
Specifier or placeholder | Description | Example |
|---|---|---|
| Day of month | 1, 2, 3 … 31 |
| Day of month, with leading zero for single-digit values | 01, 02, 03 … 31 |
| Read-only abbreviated day of the week. | Mon, Tue, Sat |
| Read-only full day of the week. | Monday, Tuesday, Saturday |
| Month number | 1, 2, 3 … 12 |
| Month number, with a leading zero for single-digit values | 01, 02, 03 … 12 |
| Abbreviated month name according to the culture (the AbbreviatedMonthNames property) | Jan, Feb, Mar |
| Full month name according to the culture (the MonthNames property) | January, February, March |
| Last two digits of a year | 1 for 2001, 20 for 2020 |
| Last two digits of a year with a leading zero for single-digit values | 01 for 2001, 20 for 2020 |
| Four-digit year | 0001 - 9999 |
| Read-only era | AD or BC |
| Date separator according to the culture (the DateSeparator property). | |
| Tells the editor to treat the following symbol as a regular character, not a date specifier. For instance, the “MM” sequence defines a month number, and the “\M\M” sequence displays static “MM” text. | |
| Allows you to add static (read-only) strings | ‘Current date:’ MM/dd |
Example 1
yyyy-MM-dd - a four-digit year at the first position, a month number at the second position, and a day number at the third position. The ‘-‘ character is the date separator.
Example 2
yyyy-MMM-dd dddd - the same mask, but month names are abbreviated. A read-only day name is also displayed.
DateOnly Mask Options
When you click the ellipsis button next to the MaskSettings property, the Mask Settings dialog appears. Click “Show Advanced Options” in the bottom left corner to view optional DateOnly settings.
To apply these settings in code, call the MaskSettings.Configure<MaskSettings.DateOnly> method and set up required options for the method return parameter.
Increment or Decrement Neighboring Part Values When Spinning
When a user spins through values of one mask segment (users can spin values with editor buttons or keyboard arrow keys) and that segment’s value passes a minimum or maximum threshold, this setting specifies whether a neighboring segment value should be automatically increased or decreased.
The following animation illustrates editor behavior with this setting enabled:
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateOnly>(settings => {
settings.MaskExpression = "MM/dd";
settings.SpinWithCarry = true;
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateOnly>();
settings.MaskExpression = "MM/dd";
settings.SpinWithCarry = true;
//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[DateOnlyEditMask("MM/dd", SpinWithCarry = true)]
public DateOnly BirthDate { get; set; }
Use Advancing Caret
This option specifies whether the caret moves to the next mask segment when the current segment is filled. For example, in the “d” mask (the “MM/DD/YYYY” date format), a user starts by entering a month number. When two digits are entered, the caret moves to the day number. Two more digits bring the caret to the last segment (year). This behavior allows users to quickly enter dates (for instance, type “11212020” to enter November 21, 2020).
If this setting is disabled, a user stays on the day segment until they press the right arrow key to move the caret.
// Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateOnly>(settings => {
settings.MaskExpression = "d";
settings.UseAdvancingCaret = true;
});
// Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateOnly>();
settings.MaskExpression = "d";
settings.UseAdvancingCaret = true;
// Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[DateOnlyEditMask("d", UseAdvancingCaret = true)]
public DateOnly BirthDate { get; set; }
User Capabilities
- The Up and Down Arrow keys increase and decrease the date value portion under the caret.
- The mouse wheel increases and decreases the date value portion under the caret.
- Keyboard letters select the corresponding month. For example, the ‘j’ character selects “January”. Subsequent presses select “June” and then “July”.
- Keyboard numbers select the corresponding month.
- The Space key moves the caret to the next date value portion.
- The date separator key moves the caret to the next date portion.
- The century is automatically determined based on the culture’s TwoDigitYearMax setting. Type ‘0’ to enter a custom century.