Mask Type: Date-time

• Oct 25, 2019
• 7 minutes to read

Overview

The Date-time and Date-time with the advancing caret mask types allow users to enter a date and/or time. The date-time masks support the Gregorian, Korean, Taiwan, and Thai Buddhist calendars.

Note

Run the XtraEditors demo to try out input masks.

Types

Input masks support the following date-time types:

• DateTime - a regular date-time mask type that supports the standard date-time .Net format.
• DateTimeAdvancingCaret - extends the previous type with the caret that automatically moves to the next date-time value portion when the current portion is completed.

The TextEdit.Properties.Mask property provides access to a MaskProperties class instance that specifies an input mask. Set the MaskProperties.MaskType property to DateTime or DateTimeAdvancingCaret to enable the date-time mask type. Use the MaskProperties.EditMask property to specify the mask expression.

Note

The DateEdit control uses the DateTime mask type. To enable the advancing caret, set DateEdit.Properties.Mask.MaskType to DateTimeAdvancingCaret.

Standard Masks

The table below contains input masks that correspond to the standard patterns. Note that patterns depend on the current culture. For example, the same input mask specifies different patterns in the USA and France. A culture’s date-time format is defined by the CultureInfo.DateTimeFormat property. Users can change the regional format in the Windows Settings panel.

Mask	Description	Remarks	Sample (English (USA) culture)
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; 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

Mask specifiers and modifiers in the table below allow you to create custom date-time input masks. For example, the yyyy-MMM-d, HH:mm:ss mask expression specifies the following input mask.

Specifier/Modifier	Description	Remarks
d	A month’ day.	Displays a single digit in the first ten-day interval (1-9). If the ‘d’ specifier is used without other specifiers, precede it with the ‘%’ character; otherwise, it is interpreted as the standard short date pattern (see above).
dd	A month’ day.	Displays two digits in the first ten-day interval (01-09).
ddd	A read-only abbreviated day name.	Day names are automatically calculated based on the current date. Users cannot edit day names. Abbreviated day names are specified by the culture’s AbbreviatedDayNames property.
dddd	A read-only full day name.	Day names are automatically calculated based on the current date. Users cannot edit day names. The full day names are specified by the culture’s DayNames property.
f or F	A single-digit fraction of a second.	If the ‘f’ or ‘F’ specifier is used without other specifiers, precede it with the ‘%’ character; otherwise, it is interpreted as the standard full date pattern (see above).
ff or FF	A two-digit fraction of a second.
fff or FFF	A three-digit fraction of a second.
ffff or FFFF	A read-only four-digit fraction of a second.	Users cannot edit a four-digit fraction of a second.
fffff or FFFFF	A read-only five-digit fraction of a second.	Users cannot edit a five-digit fraction of a second.
ffffff or FFFFFF	A read-only six-digit fraction of a second.	Users cannot edit a six-digit fraction of a second.
fffffff or FFFFFFF	A read-only seven-digit fraction of a second.	Users cannot edit a seven-digit fraction of a second.
g	A read-only era (AD/BC).	Users cannot edit the era.
h	An hour in the 12-hour format.	Displays a single digit in the first-ten interval (1-9).
hh	An hour in the 12-hour format.	Displays two digits in the first-ten interval (01-09).
H	An hour in the 24-hour format.	Displays a single digit in the first-ten interval (1-9).
HH	An hour in the 24-hour format.	Displays two digits in the first-ten interval (01-09).
m	A minute.	Displays a single digit in the first-ten interval (1-9).
mm	A minute.	Displays two digits in the first-ten interval (01-09).
M	A month number.	Displays a single digit in the first-ten interval (1-9).
MM	A month number.	Displays two digits in the first-ten interval (01-09).
MMM	An abbreviated month name.	The abbreviated moth names are specified by the culture’s AbbreviatedMonthNames property.
MMMM	A full month name.	The full month names are specified by the culture’s MonthNames property.
s	A second.	Displays a single digit in the first ten-second interval (1-9). If the ‘s’ specifier is used without other specifiers, precede it with the ‘%’ character; otherwise, it is interpreted as the standard sortable date-time pattern (see above).
ss	A second.	Displays two digits in the first-ten interval (01-09).
t	The A.M./P.M. designator’s first character.	If the ‘t’ specifier is used without other specifiers, precede it with the ‘%’ character; otherwise, it is interpreted as the standard short time pattern (see above).
tt	The A.M./P.M. designator.
y	A two-digit year.	Displays a single digit in the first-ten interval (1-9). If the ‘y’ specifier is used without other specifiers, precede it with the ‘%’ character; otherwise, it is interpreted as the standard year month pattern (see above).
yy	A two-digit year.	Displays two digits in the first-ten interval (01-09).
yyyy	A four-digit year.
z	A read-only time zone. Hours only.	Displays a single digit in the first-ten interval (1-9).
zz	A read-only time zone. Hours only.	Displays two digits in the first-ten interval (01-09).
zzz	A read-only time zone. Hours and minutes.	Displays two digits in the first-ten interval (01-09).
:	The time separator.	The time separator is specified by the culture’s TimeSeparator property.
/	The date separator.	The date separator is specified by the culture’s DateSeparator property.
%<specifier>	The ‘%’ modifier that precedes a mask specifier distinguishes the specifier from the same standard mask pattern (see above).	If a mask specifier is used without other specifiers, it can be interpreted as a standard pattern. For example, the ‘d’ specifier is interpreted as the standard short date pattern, but not a month day. Precede the specifier with the ‘%’ modifier to interpret it as a placeholder, but not a standard pattern.
\<specifier>	The backslash modifier is the escape character.	Precede a specifier with the backslash modifier to display the specifier as a character in the edit box.
"some text" or 'some text'	A read-only custom text.	Use quotes or double quotes to display custom text in the edit box.
	Any other characters.	Any other characters are displayed in the edit box literally.

Examples

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. The result is shown below.

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.

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.