Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Collapse]Editors and Simple Controls
    Templated ListBox Items
   [Collapse]Simple Editors
    [Expand]Included Components
    [Expand]Editors Structure
    [Collapse]Editors Features
      Text Editing Overview
     [Collapse]Mask Editors Overview
       Mask Type: Numeric
       Mask Type: Date-time
       Mask Type: Extended Regular Expressions
       Mask Type: Simple
       Mask Type: Simplified Regular Expressions
     [Expand]Formatting and Parsing Values
     [Expand]Editor Buttons Overview
     [Expand]Dropdown Editors Overview
      Image Editing Menu
     [Expand]Data Binding Overview
     [Expand]Appearance Customization
     [Expand]Miscellaneous Features
    [Expand]Member Tables
    [Expand]Examples
   [Expand]Lookup Editors
   [Expand]Token Edit Control
   [Expand]Breadcrumb Edit Control
   [Expand]Range Control
   [Expand]Image Slider
    Camera Control
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Mask Type: Date-time

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

For information on the other masked modes, see the Mask Editors Overview document.

In this topic:

Expanded Date-Time Mask Modes

The XtraEditors library provides two DateTime mask modes:

  • DateTime mask mode;
  • DateTimeAdvancingCaret mask mode. It is similar to the previous mask mode. The only difference is that after an end-user enters and completes a specific portion of a date/time value, the caret automatically moves to the following part of a date/time value that can be edited.
To enable the required DateTime mask mode, set the MaskProperties.MaskType property of the RepositoryItemTextEdit.Mask object to MaskType.DateTime or MaskType.DateTimeAdvancingCaret. The mask itself should be specified via the MaskProperties.EditMask property.

By default, the DateEdit control uses the MaskType.DateTime mask mode. 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 in MSDN. So, the editor's edit mask and display format may match. In this case, the editor's value in edit and display modes will be the same. To customize the editor's display format, use the RepositoryItem.DisplayFormat property.

Most of the masks listed below are affected by 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 System.Globalization.CultureInfo.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 only support the following calendars: Gregorian, Korean, Taiwan, and Thai Buddhist.

Expanded Predefined Masks

Predefined masks allow end-users to edit date/time values using common patterns. A standard mask consists of a single character which identifies the appropriate pattern. The available masks are listed in the following table.

Standard mask Name Description Samples

Culture: English (USA)

d Short date pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.ShortDatePattern property.
D Long date pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.LongDatePattern property.
t Short time pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.ShortTimePattern property.
T Long time pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.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 System.Globalization.DateTimeFormatInfo.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 System.Globalization.DateTimeFormatInfo.MonthDayPattern property.
R or r RFC1123 pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.RFC1123Pattern property.
s Sortable date/time pattern; conforms to ISO 8601 The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.SortableDateTimePattern property.
u Universal sortable date/time pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.UniversalSortableDateTimePattern property.
Y or y Year month pattern The mask matches the pattern specified by the System.Globalization.DateTimeFormatInfo.YearMonthPattern property.

Expanded Custom Masks

Custom masks can be used if the predefined ones don't suit your particular needs. You can 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.

Note that 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's 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.

Note that 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 in the range 1-12.
hh A placeholder for the hour part of the date/time value in the 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 in the range 0-23.
HH A placeholder for the hour part of the date/time value in the 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 in the range 0-59.
mm A placeholder for the minutes of the date/time value in the 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 in the range 1-12.
MM A placeholder for the month in this position, measured as a number in the 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 in the range 0-59.

Note that 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 in the 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.

Note that 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.

Note that 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 only. The offset is always displayed with a leading sign (zero is displayed as "+0"), indicating how many hours ahead of Greenwich Mean Time (+) or hours 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 only. The offset is always displayed with a leading or trailing sign (zero is displayed as "+00"), indicating how many hours ahead of Greenwich Mean Time (+) or hours 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 how many hours ahead of Greenwich Mean Time (+) or hours 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 literally 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.

Note that 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.

Expanded End-User Capabilities

  • Pressing the Up-Arrow and Down-Arrow keys increases and decreases the part of the date/time value indicated by the caret. For example, if the day part is edited, pressing these shortcuts changes the day. If the month part is edited, the month will be changed.
  • 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 selects "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 System.Globalization.Calendar.TwoDigitYearMax topic in MSDN). To insert a year that belongs to the first century, press the '0' character before entering the year.

Expanded 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.

Expanded See Also

How would you rate this topic?​​​​​​​