Mask Type: TimeSpan
- 11 minutes to read
Overview
The TimeSpan mask type allows users to enter time intervals. This type supports the standard time span .Net format.
Run this Demo Center module to test various mask types: Mask Box.
Standard Masks
The table below contains input masks that correspond to the standard patterns. These patterns do not depend on culture settings.
Mask | Description | Remarks | Sample (the English (U.S.) culture) |
|---|---|---|---|
| Constant Format | Matches the |
|
| General Short Format | Matches the |
|
| General Long Format | Matches the |
|
Custom Masks
Mask specifiers and modifiers in the table below allow you to create custom time span input masks. For example, the mm MM, ss SS mask expression specifies the following input mask:
Specifier/Placeholder | Description | Remarks |
|---|---|---|
| Number of whole days. | Allows a user to enter days. Any number of digits, with no leading zeros. |
| Number of whole days. | Allows a user to enter days. The number of |
| Short caption for days. | ‘d‘ in the English (U.S.) locale. |
| Long caption for days. | ‘day‘ or ‘days‘ in the English (U.S.) locale. |
| Number of whole hours. | Displays a single digit in the first ten-day interval (1-9). |
| Number of whole hours. | Displays two digits in the first-ten interval (01-09). |
| Short caption for hours. | ‘h‘ in the English (U.S.) locale. |
| Long caption for hours. | ‘hour‘ or ‘hours‘ in the English (U.S.) locale |
| Number of whole minutes. | Displays a single digit in the first ten-day interval (1-9). |
| Number of whole minutes. | Displays two digits in the first-ten interval (01-09). |
| Short caption for minutes. | ‘m‘ in the English (U.S.) locale. |
| Long caption for minutes. | ‘minute‘ or ‘minutes‘ in the English (U.S.) locale. |
| Number of whole seconds. | Displays a single digit in the first-ten interval (1-9). |
| Number of whole seconds. | Displays two digits in the first-ten interval (01-09). |
| Short caption for seconds. | ‘s‘ in the English (U.S.) locale |
| Long caption for seconds. | ‘second‘ or ‘seconds‘ in the English (U.S.) locale. |
| Number of whole milliseconds. | Displays a single digit in the first-ten interval (1-9). |
| Number of whole milliseconds. | Displays two digits in the first-ten interval (01-09). |
| Number of whole milliseconds. | Displays leading zeros. |
| Short caption for milliseconds. | ‘ms‘ in the English (U.S.) locale. |
| Long caption for milliseconds. | ‘milliseconds‘ in the English (U.S.) locale. |
| Number of second fractions. | |
| Number of second fractions. | Any fractional trailing zeros are not included. |
| Number of second fractions. | An editor displays zeros for empty placeholders. |
| Short caption for fractional part of seconds. | ‘f‘ in the English (U.S.) locale. |
| Long caption for fractional part of seconds. | ‘fractional‘ in the English (U.S.) locale. |
| Elements in square brackets are optional. | |
| Time separator. | Does not depend on the current culture. |
| Decimal separator. | Depends on the current culture. |
| Quoted string. Inserts the string enclosed in single or double quotes into the edit box. | The string cannot be edited in the text editor. |
| 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. |
| 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. |
Any other characters. | Any other characters are displayed in the edit box literally. |
Example 1
d'.'hh':'mm':'ss - allows users to input days, hours, minutes, and seconds. The ‘.‘ and ‘:‘ characters are separators.
Example 2
d DD 'left' - allows users to input days. Displays custom text and the ‘days‘ caption according to the culture.
TimeSpan Settings
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 TimeSpan settings.
“Default part”
If a mask contains multiple segments, this property specifies the default segment that is initially selected when a user focuses this editor. For example, if a user focuses an editor with the “hh’:’mm’:’ss” mask and the default “Minutes” segment, and enters “20” in the editor, this value is assigned to the minutes portion of the TimeSpan.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.DefaultPart = TimeSpanMaskPart.Minutes;
});
//Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.DefaultPart = TimeSpanMaskPart.Minutes;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("d'.'hh':'mm':'ss", DefaultPart = TimeSpanMaskPart.Minutes)]
public TimeSpan TimeLeft { get; set; }
“Input Mode”
This setting allows you to switch between the following modes:
- Restricted - users are allowed to enter only valid numbers for each mask segment (0-23 hours, 0-59 minutes, 0-59 seconds, etc.).
- NotRestricted - users can enter any number into any mask part. If the resulting value is out of the range limit, its neighboring segment is automatically increased. For example, if the editor value is “10 hours 05 minutes” and a user enters “65” into the minutes segment, the editor value becomes “11 hours 10 minutes”.
- NotRestrictedLargestUnit - users can enter any values to the largest mask part only. For remaining mask segments, this mode behaves in a manner similar to “Restricted” mode.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.InputMode = TimeSpanMaskInputMode.NotRestricted;
});
//Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.InputMode = TimeSpanMaskInputMode.NotRestricted;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("d'.'hh':'mm':'ss", InputMode = TimeSpanMaskInputMode.NotRestricted)]
public object TimeSpan { get; set; }
“Allow Negative Values”
Specifies whether users can enter negative time offsets. Note that if this setting is disabled and a negative value is assigned directly to the editor’s EditValue property, this value is converted to a positive value only after a user modifies it. Until that time, the editor value remains negative.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.AllowNegativeValues = false;
});
//Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.AllowNegativeValues = false;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("d'.'hh':'mm':'ss", AllowNegativeValues = false)]
public object TimeSpan { get; set; }
“Enable mnemonics”
Specifies whether users can press letters to quickly navigate to corresponding mask segments. For the “en-US” culture, press “d” for days, “h” for hours, “m” for minutes and “s” for seconds. For example, users can type “h5” to set the hours segment of the mask to 5 hours, regardless of the current caret position.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.EnableMnemonics = true;
});
//Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.EnableMnemonics = true;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("d'.'hh':'mm':'ss", EnableMnemonics = true)]
public TimeSpan TimeLeft { get; set; }
“Hide middle optional segments with zero values”
You can enclose mask segments in square brackets to mark them as optional. For instance, the “[hh HH ][mm MM ]ss SS” mask requires that users enter seconds, while hours and minutes are optional. If a user enters hours and seconds in the editor, and leaves the minutes segment blank, this option specifies whether the editor should display the zero segment: “02 hours 00 minutes 23 seconds” (disabled) or “02 hours 23 seconds” (enabled).
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "[hh HH ][mm MM ]ss SS";
settings.HideInsignificantParts = true;
});
//regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "[hh HH ][mm MM ]ss SS";
settings.HideInsignificantParts = true;
//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("[hh HH ][mm MM ]ss SS", HideInsignificantParts = true)]
public TimeSpan TimeLeft { get; set; }
“Increment or decrement neighboring segments when spinning”
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.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "hh':'mm";
settings.SpinWithCarry = true;
});
//regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "hh':'mm";
settings.SpinWithCarry = true;
//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("hh':'mm", SpinWithCarry = true)]
public TimeSpan TimeLeft { get; set; }
“Reset segments on Select All input”
This option specifies whether all segments, except the default segment, should reset their values when a user selects an entire editor and enters a new value. In the following code, the editor should reset all segments, and the value entered by a user is assigned to the “Minutes” segment.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.DefaultPart = TimeSpanMaskPart.Minutes;
settings.ResetPartsOnSelectAllInput = true;
});
//Regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "d'.'hh':'mm':'ss";
settings.DefaultPart = TimeSpanMaskPart.Minutes;
settings.ResetPartsOnSelectAllInput = true;
//Data Annotation Attribute (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("d'.'hh':'mm':'ss", DefaultPart = TimeSpanMaskPart.Minutes, ResetPartsOnSelectAllInput = true;)]
public TimeSpan TimeLeft { get; set; }
Use advancing caret
This option specifies whether the caret moves to the next mask segment when the current segment is filled.
//Fluent API
using DevExpress.XtraEditors.Mask;
textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>(settings => {
settings.MaskExpression = "hh':'mm";
settings.UseAdvancingCaret = true;
});
//regular API
using DevExpress.XtraEditors.Mask;
var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeSpan>();
settings.MaskExpression = "hh':'mm";
settings.UseAdvancingCaret = true;
//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;
[TimeSpanEditMask("hh':'mm", UseAdvancingCaret = true)]
public TimeSpan TimeLeft { get; set; }
End-User Capabilities
- The Up and Down Arrow keys increase and decrease the time span value portion under the caret.
- The mouse wheel increases and decreases the time span value portion under the caret.
- The Left and Right Arrow keys move the caret in the corresponding direction.
- The Space key moves the caret to the next time span value portion.
- The time separator key moves the caret to the next time portion.