Mask Type: DateTime

• Jul 02, 2024
• 8 minutes to read

The DateTime mask type allows users to enter a date and/or time. DateTime masks support the Gregorian, Korean, Taiwanese, and Thai Buddhist calendars.

Note

Run the XtraEditors demo to try out input masks.

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 DateTime format is defined by the CultureInfo.DateTimeFormat property. Users can change the regional format in the Windows Settings panel.

Mask	Description	Sample
d	Short “mm/dd/yyyy” date format	8/24/2020
D	Long date format	Monday, August 24, 2020
t	Short “hh:mm AM/PM” time format	7:51 PM
T	Long “hh:mm:ss AM/PM” time format	7:51:13 PM
g	Combines short date and short time masks	8/24/2020 7:51 PM
G	Combines short date and long time masks	8/24/2020 7:51:13 PM
f	Combines long date and short time masks	Monday, August 24, 2020 7:51 PM
F	Full time format according to the FullDateTimePattern property value. In the “en-US” culture, this specifier combines long date and long time masks	August 24, 2020 7:51:13 PM
R or r	Date-time in the RFC1123 format	Sun, 16 Aug 2020 16:08:00 GMT
s	Sortable ISO8601 date-time format	2020-08-16T16:08:00
u	Universal sortable date-time format	2020-08-16 16:08:00Z
M	Full month name and day number	August 24
Y	Full month name and year number	August 2020

Standard masks cannot be combined within a single expression. For instance, if you set the M, t mask - the output will not display as follows: “Month DD, HH:MM AM(PM)”. To get this type of mask, you need to use custom mask placeholders.

Custom Masks

You can combine custom mask placeholders to create custom masks of any complexity. For example, to create the “Month DD, HH:MM AM(PM)” mask, combine custom mask placeholders as follows: “MMMM d, h:mm tt”.

DevExpress editors support the following custom specifiers and placeholders.

Specifier or placeholder	Description	Example
d (%d, if used alone)	Day of month	1, 2, 3 … 31
dd	Day of month, with leading zero for single-digit values	01, 02, 03 … 31
ddd	Read-only abbreviated day of the week. Abbreviated day names are specified by the culture’s AbbreviatedDayNames property.	Mon, Tue, Sat
dddd	Read-only full day of the week. Full day names are specified by the culture’s DayNames property.	Monday, Tuesday, Saturday
F or f (%F or %f, if used alone)	One fraction of a second. You can repeat this specifier up to seven times. Masks that have 4 or more “f” (“F”) specifiers are read-only.	1 to 9 (f or F) 01 to 99 (ff or FF) 0000001 to 9999999 (fffffff or FFFFFFF)
s (%s, if used alone)	Second	1, 2, 3 … 59
ss	Second, with a leading zero for single-digit values	01, 02, 03 … 59
h	Hour in 12-hour format	1, 2, 3 … 12
hh	Hour in 12-hour format, with a leading zero for single-digit values	01, 02, 03 … 12
H	Hour in 24-hour format	0, 1, 2 … 23
HH	Hour in 24-hour format, with a leading zero for single-digit values	00, 01, 02 … 23
m	Minute	0, 1, 2 … 59
mm	Minute, with a leading zero for single-digit values	00, 01, 02 … 59
M	Month number	1, 2, 3 … 12
MM	Month number, with a leading zero for single-digit values	01, 02, 03 … 12
MMM	Abbreviated month name according to the culture (the AbbreviatedMonthNames property)	Jan, Feb, Mar
MMMM	Full month name according to the culture (the MonthNames property)	January, February, March
y (%y, if used alone)	Last two digits of a year	1 for 2001, 20 for 2020
yy	Last two digits of a year with a leading zero for single-digit values	01 for 2001, 20 for 2020
yyyy	Four-digit year	0001 - 9999
g	Read-only era	AD or BC
tt	Time designator	AM or PM
t (%t, if used alone)	First letter of the time designator	A or P
z	Hours offset from UTC, with no leading zeros. Read-only.	-1, +5
zz	Hours offset from UTC, with a leading zero for single-digit values. Read-only.	-01, +05
zzzz	Hours and minutes offset from UTC. Read-only.	-01:00, +05:00
:	Time separator according to the culture (the TimeSeparator property).
/	Date separator according to the culture (the DateSeparator property).
\	Tells the editor to treat the following symbol as a regular character, not a date-time specifier. For instance, the “zz” sequence defines a two-digit time zone mask, and the “\z\z” sequence displays static “zz” text.
' or "	Allows you to add static (read-only) strings	‘Current time:’ HH:mm

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.

Example 3

HH:mm:ss - the 24-hour time format.

Date-Time 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 DateTime settings.

To apply these settings in code, call the MaskSettings.Configure<MaskSettings.DateTime> method and set up required options for the method return parameter.

Increment or decrement neighboring segments when a user spins a value

When a user spins through values of one mask segment (users can spin values with editor buttons or keyboard arrow keys) and this value passes a minimum or maximum threshold, this setting specifies whether a neighboring segment value should be automatically increased or decreased. For example, an editor has the “HH:mm” (hours and minutes) mask and the current editor value is “00:59”. If a user spins the minute segment up, the editor value becomes “00:00” if this option is disabled, or “01:00” when it is enabled. Similarly, if a user decreases the minute segment value in an editor with a value of “01:00”, the resulting value is either “01:59” or “00:59” — based on the setting.

The following animation illustrates the editor behavior with this setting enabled:

C#

// Fluent API
using DevExpress.XtraEditors.Mask;

textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateTime>(settings => {
    settings.MaskExpression = "HH:mm";
    settings.SpinWithCarry = true;
});

// Regular API
using DevExpress.XtraEditors.Mask;

var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateTime>();
settings.MaskExpression = "HH:mm";
settings.SpinWithCarry = true;

//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;

[DateTimeEditMask("HH:mm", SpinWithCarry = true)]
public DateTime BirthDate { get; set; }

VB.NET

Imports DevExpress.XtraEditors.Mask

Private textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.DateTime)(Sub(settings)
    settings.MaskExpression = "HH:mm"
    settings.SpinWithCarry = True
End Sub)

' Regular API

Private settings = textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.DateTime)()
settings.MaskExpression = "HH:mm"
settings.SpinWithCarry = True

' Data Source level (for code-first sources)
Using System.ComponentModel.DataAnnotations

<DateTimeEditMask("HH:mm", SpinWithCarry := True)>
public DateTime 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.

C#

// Fluent API
using DevExpress.XtraEditors.Mask;

textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateTime>(settings => {
    settings.MaskExpression = "d";
    settings.UseAdvancingCaret = true;
});

// Regular API
using DevExpress.XtraEditors.Mask;

var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.DateTime>();
settings.MaskExpression = "d";
settings.UseAdvancingCaret = true;

// Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;

[DateTimeEditMask("d", UseAdvancingCaret = true)]
public DateTime BirthDate { get; set; }

VB.NET

' Fluent API
Imports DevExpress.XtraEditors.Mask

Private textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.DateTime)(Sub(settings)
    settings.MaskExpression = "d"
    settings.UseAdvancingCaret = True
End Sub)

' Regular API

Private settings = textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.DateTime)()
settings.MaskExpression = "d"
settings.UseAdvancingCaret = True

' Data Source level (for code-first sources)
Using System.ComponentModel.DataAnnotations

<DateTimeEditMask("d", UseAdvancingCaret := True)>
public DateTime BirthDate {get;set;}

End-User Capabilities

• The Up and Down Arrow keys increase and decrease the date-time value portion under the caret.
• The mouse wheel increases and decreases the date-time 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-time value portion.
• The date separator key moves the caret to the next date portion.
• The time separator key moves the caret to the next time portion.
• The century is automatically determined based on the culture’s TwoDigitYearMax setting. Type ‘0’ to enter a custom century.