Mask Type: Date-Time

• Apr 21, 2021
• 12 minutes to read

This document describes the DateTime mask modes, which are specifically designed for entering date/time values in different formats. Specific DateTime masks are dependent upon the current culture’s settings.

For information on the other masked modes, see the mask types document.

Date-Time Mask Modes

The DevExpress WPF Data Editors support the following DateTime mask modes:

• DateTime mask mode;
• DateTimeAdvancingCaret mask mode. This mode is similar to the DateTime mask mode. The difference is that after an end user enters and completes a specific part of a date/time value, the caret moves to the following part of a date/time value that can be edited.

To enable a particular DateTime mask mode, set the TextEdit.MaskType (or the TextEditSettings.MaskType for in-place editors) property to MaskType.DateTime or MaskType.DateTimeAdvancingCaret. The mask itself should be specified via the TextEdit.Mask (or TextEditSettings.Mask for in-place editors) property.

The DateEdit control uses the MaskType.DateTime mask mode by default. To enable automatic caret advancement, set the editor’s mask type to MaskType.DateTimeAdvancingCaret.

You can use either predefined or custom masks. These masks are similar to the display formats described in the Date and Time Format Strings document. Set the TextEdit.MaskUseAsDisplayFormat (TextEditSettings.MaskUseAsDisplayFormat for in-place editors) to format editor values using mask when the editor is not in edit mode.

Most of the masks listed below depend on the current culture. For example, the culture defines the names of months, the symbol to use as the date separator, the short and long date patterns, etc. All these settings are provided by the DateTimeFormat property of the current culture. To customize these settings for your system use the Regional Options dialog in the control panel.

The date/time masks support the following calendars: Gregorian, Korean, Taiwan, and Thai Buddhist.

Predefined Masks

Predefined masks allow end users to edit date/time values according to common patterns. A standard mask consists of a single character which identifies the appropriate pattern. The table below lists the available masks.

Standard mask	Name	Description	Samples Culture: English (U.S.)
d	Short date pattern	The mask matches the pattern specified by the ShortDatePattern property.
D	Long date pattern	The mask matches the pattern specified by the LongDatePattern property.
t	Short time pattern	The mask matches the pattern specified by the ShortTimePattern property.
T	Long time pattern	The mask matches the pattern specified by the LongTimePattern property.
f	Full date/time pattern (short time)	The mask combines the long date and short time patterns, separated by the space character.
F	Full date/time pattern (long time)	The mask matches the pattern specified by the FullDateTimePattern property.
g	General date/time pattern (short time)	The mask combines the short date and short time patterns, separated by the space character.
G	General date/time pattern (long time)	The mask combines the short date and long time patterns, separated by the space character.
M or m	Month day pattern	The mask matches the pattern specified by the MonthDayPattern property.
R or r	RFC1123 pattern	The mask matches the pattern specified by the RFC1123Pattern property.
s	Sortable date/time pattern that conforms to ISO 8601	The mask matches the pattern specified by the SortableDateTimePattern property.
u	Universal sortable date/time pattern	The mask matches the pattern specified by the UniversalSortableDateTimePattern property.
Y or y	Year month pattern	The mask matches the pattern specified by the YearMonthPattern property.

Custom Masks

You can use custom masks if the predefined ones do not suit your particular needs. Use the following mask specifiers to create custom masks for editing date/time values.

Mask specifier	Description
d	A placeholder for the day of the month. If the day is a single digit only (1-9), then it’s displayed as a single digit. If the d specifier is used alone, without other custom specifiers, it’s interpreted as the standard mask (short date pattern). If the d specifier is passed with other custom specifiers or the % character, it is interpreted as a custom mask specifier.
dd	A placeholder for the day of the month. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09).
ddd	Displays the abbreviated name of the current day. The abbreviated names are determined by the DateTimeFormatInfo.AbbreviatedDayNames property of the current culture. The value represented by this specifier cannot be edited.
dddd (plus any number of additional “d” characters)	Displays the full name of the current day. The full names of the days are determined by the DateTimeFormatInfo.DayNames property of the current culture. The value represented by this specifier cannot be edited.
f or F	A placeholder for seconds fractions represented in one digit. If the f/F specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (full date/time pattern). If the f/F specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
ff or FF	A placeholder for seconds fractions represented in two digits.
fff or FFF	A placeholder for seconds fractions represented in three digits.
ffff or FFFF	Displays seconds fractions represented in four digits. The value represented by this specifier cannot be edited.
fffff or FFFFF	Displays seconds fractions represented in five digits. The value represented by this specifier cannot be edited.
ffffff or FFFFFF	Displays seconds fractions represented in six digits. The value represented by this specifier cannot be edited.
fffffff or FFFFFFF	Displays seconds fractions represented in seven digits. The value represented by this specifier cannot be edited.
g	Displays the era (“A.D.”, for example) for the current date/time value. The value represented by this specifier cannot be edited.
h	A placeholder for the hour part of the date/time value (range 1-12).
hh	A placeholder for the hour part of the date/time value (range 1-12). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
H	A placeholder for the hour part of the date/time value (range 0-23).
HH	A placeholder for the hour part of the date/time value (range 0-23). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
m	A placeholder for the minutes of the date/time value (range 0-59).
mm	A placeholder for the minutes of the date/time value (range 0-59). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
M	A placeholder for the month in this position, measured as a number (range 1-12).
MM	A placeholder for the month in this position, measured as a number (range 1-12). This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
MMM	A placeholder for the abbreviated name of the month. The abbreviated names of the months are determined by the DateTimeFormatInfo.AbbreviatedMonthNames property of the current culture.
MMMM	A placeholder for the full name of the month. The full names of the months are determined by the DateTimeFormatInfo.MonthNames property of the current culture.
s	A placeholder for the seconds part of the date/time value (range 0-59). If the s specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (sortable date/time pattern). If the s specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
ss	A placeholder for the seconds part of the date/time value (range 0-59). This pattern inserts two placeholders to enter a value. If a single digit is entered it’s preceded with a 0.
t	A placeholder for the first character of the A.M./P.M. designator of the date/time value. If the t specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (short time pattern). If the t specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
tt	A placeholder for the A.M./P.M. designator of the date/time value.
y	A placeholder for entering the last two digits of the year of the date/time value. If the y specifier is used alone without other custom specifiers, it’s interpreted as the standard mask (year month pattern). If the y specifier is passed with other custom specifiers or the % character, it’s interpreted as a custom mask specifier.
yy	A placeholder for entering the last two digits of the year of the date/time value. This pattern inserts two placeholders to enter a value. If a single digit is entered it is preceded with a 0.
yyyy	A placeholder for entering the year part of the date/time value including the century.
z	Displays the time zone offset for the system’s current time zone in whole hours. The offset is always displayed with a leading sign (zero is displayed as +0), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich mean time (-) the current time zone is. The range of values is –12 to +13. If the offset is a single digit (0–9), it’s displayed as a single digit with an appropriate leading sign. The value represented by this specifier cannot be edited.
zz	Displays the time zone offset for the system’s current time zone in whole hours. The offset is always displayed with a leading or trailing sign (zero is displayed as +00), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich Mean Time (-) the current time zone is. The range of values is –12 to +13. If the offset is a single digit (0–9), it’s formatted with a preceding 0 (01–09) with an appropriate leading sign. The value represented by this specifier cannot be edited.
zzz	Displays the time zone offset for the system’s current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as +00:00), indicating the number of hours ahead of Greenwich Mean Time (+) or behind Greenwich Mean Time (-) the current time zone is. The range of values is -12:00 to +13:00. If the offset is a single digit (0–9), it’s formatted with a preceding 0 (01–09) with an appropriate leading sign. The value represented by this specifier cannot be edited.
:	Time separator. The actual time separator is determined by the DateTimeFormatInfo.TimeSeparator property of the current culture.
/	Date separator. The actual date separator is determined by the DateTimeFormatInfo.DateSeparator property of the current culture.
“abc“ or ‘abc‘	Quoted string. Inserts the string enclosed with single or double quotes to the edit box. The string cannot be edited.
%c	Where c is one of the standard mask specifiers, interprets the specifier as a custom mask specifier. If a mask specifier is used alone as a single character, it’s interpreted as a standard mask specifier. Only mask specifiers consisting of two or more characters are interpreted as custom specifiers. In order to use a custom specifier which matches one of the standard specifiers, on its own, it should be preceded with the % character.
\c	The backslash is used as the escape character. It inserts the following character literally to the edit box.
Any other characters.	The other characters are inserted to the edit box literally.

End-User Capabilities

• Up and Down arrow keystrokes increase and decrease the part of the data/time value at the caret position. For example, if the day part is edited, arrow keystrokes change the day. If the month part is edited, then the keystrokes change the month.
• Scrolling the mouse wheel increases and decreases the part of the date/time value indicated by the caret (similar to pressing the Up-Arrow and Down-Arrow keys).
• While the full or abbreviated name of the month is being edited, a specific month can be selected by typing the initial letter of its name. For instance, pressing the ‘j’ character selects “January.” Subsequent presses of the ‘j’ key select “June” and then “July.”
• While the full or abbreviated name of the month is being edited, a specific month can be selected by typing the month’s order number (1-12).
• The Space character can be pressed to move the caret from the current position, to the following part of a date/time value that can be edited.
• The character representing the date separator can be pressed to move the caret from the current position, to the following part of a date value that can be edited.
• The character representing the time separator can be pressed to move the caret from the current position, to the following part of a time value that can be edited.
• If a mask requires a year to be entered using four digits (the yyyy mask), an end user can enter the required year using the last two (or one) digits of this year. The century will be determined automatically based upon the current culture (see the TwoDigitYearMax topic). To insert a year that belongs to the first century, press the ‘0’ character before entering the year.

Examples

The following are examples of custom date/time masks. See the Predefined Masks sub-section for examples of predefined masks.

1. The mask that requires the year to be entered at the first position, the month at the second and the day at the third position. The - characters are used as the date separators: yyyy-MM-dd

   

2. The same mask, but the months are edited using their abbreviated names. In addition, the name of the day is displayed to the right of the value: yyyy-MMM-dd dddd

   The name of the day cannot be edited.

   

Date-Time Mask Options

Increment Neighboring Segments

The DateTimeMaskOptions.ChangeNextPartOnCycleValueChange property specifies whether a neighboring segment value should automatically increase or decrease when a user spins through values of one mask segment with editor buttons or arrow keys, and this value passes the minimum or maximum threshold.

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 the DateTimeMaskOptions.ChangeNextPartOnCycleValueChange property is disabled, or “01:00” when it is enabled. 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 editor behavior with this property enabled:

Change DateTimeKind

The DateTimeKind attached property allows you to explicitly set the DateTime.Kind property (UTC, Local time, or neither) of a DateTime value (returned by the editor’s EditValue property).

Xaml

<dxe:TextEdit MaskType="DateTime" Mask="d" dxe:DateTimeMaskOptions.DateTimeKind="Utc"/>

<dxe:DateEdit dxe:DateTimeMaskOptions.DateTimeKind="Local"/>