Mask Type: TimeSpan

• Jan 11, 2023
• 7 minutes to read

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

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

TimeSpan Mask Modes

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

• TimeSpan mask mode;
• TimeSpanAdvancingCaret mask mode. This mode is similar to the TimeSpan mask mode. The difference is that after an end-user enters and completes a specific part of a time interval value, the caret moves to the following part of a time interval value.

Enable TimeSpan Masks

To enable a particular TimeSpan mask mode, set the TextEdit.MaskType property (or the TextEditSettings.MaskType for in-place editors) to MaskType.TimeSpan or MaskType.TimeSpanAdvancingCaret. Use the TextEdit.Mask property (or TextEditSettings.Mask for in-place editors) to specify the mask itself.

Mask as a Display Format

The TimeSpan masks are similar to the display formats described in the Standard TimeSpan Format Strings document. Set the TextEdit.MaskUseAsDisplayFormat (TextEditSettings.MaskUseAsDisplayFormat for in-place editors) to format editor values using its mask when the editor is not in edit mode.

Predefined Masks

Predefined masks allow end users to edit time interval values using common patterns. A standard mask consists of a single character that identifies the appropriate pattern.

Standard mask	Name	Description	Samples Culture: English (U.S.)
c	Constant (invariant) form	Matches the [d'.']hh':'mm':'ss['.'fffffff] pattern. Does not depend on culture settings.
g	General short format	Matches the [d':']h':'mm':'ss[.FFFFFFF] pattern. Depends on culture settings.
G	General long format	Matches the d':'hh':'mm':'ss.fffffff pattern. Depends on culture settings.

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 time interval values.

Mask specifier	Description
d	A placeholder for the number of whole days in the time interval. If the number of days is a single digit (1-9), then it is displayed as a single digit.
dd-dddddddd	A placeholder for the number of whole days in the time interval padded with leading zeros as needed.
D	A string presentation of days (‘d’ in English (U.S.) locale by default).
DD	A string presentation of days (‘day’ or ‘days’ in English (U.S.) locale by default).
h	A placeholder for the number of whole hours in the time interval. If the number of hours is a single digit (1-9), then it is displayed as a single digit.
hh	A placeholder for the number of whole hours in the time interval padded with a leading zero if needed.
H	A string presentation of hours (‘h’ in English (U.S.) locale by default).
HH	A string presentation of hours (‘hour’ or ‘hours’ in English (U.S.) locale by default).
m	A placeholder for the number of whole minutes in the time interval. If the number of minutes is a single digit (1-9), then it is displayed as a single digit.
mm	A placeholder for the number of whole minutes in the time interval padded with a leading zero if needed.
M	A string presentation of minutes (‘m’ in English (U.S.) locale by default).
MM	A string presentation of minutes (‘minute’ or ‘minutes’ in English (U.S.) locale by default).
s	A placeholder for the number of whole seconds in the time interval. If the number of seconds is a single digit (1-9), then it is displayed as a single digit.
ss	A placeholder for the number of whole seconds in the time interval padded with a leading zero if needed.
S	A string presentation of seconds (‘s’ in English (U.S.) locale by default).
SS	A string presentation of seconds (‘second’ or ‘seconds’ in English (U.S.) locale by default).
n	A placeholder for the number of whole milliseconds in the time interval. If the number of seconds is a single digit (1-9), then it is displayed as a single digit.
nn	A placeholder for the number of whole milliseconds in the time interval padded with a leading zero if needed.
nnn	A placeholder for the number of whole milliseconds in the time interval padded with a leading zero if needed.
N	A string presentation of milliseconds (‘ms’ in English (U.S.) locale by default).
NN	A string presentation of milliseconds (‘milliseconds’ in English (U.S.) locale by default).
f	A placeholder for the tenth of seconds in the time interval.
ff	A placeholder for the hundredths of seconds in the time interval.
fff	A placeholder for the milliseconds in the time interval.
ffff	A placeholder for the ten-thousandths of seconds in the time interval.
fffff	A placeholder for the hundred-thousandths of seconds in the time interval.
ffffff	A placeholder for the millionths of seconds in the time interval.
fffffff	A placeholder for the ten-millionths of seconds in the time interval.
F	A placeholder for the tenth of seconds in the time interval. Nothing is displayed if the digit is zero.
FF	A placeholder for the hundredths of seconds in the time interval. Any fractional trailing zeros are not included.
FFF	A placeholder for the milliseconds in the time interval. Any fractional trailing zeros are not included.
FFFF	A placeholder for the ten-thousandths of seconds in the time interval. Any fractional trailing zeros are not included.
FFFFF	A placeholder for the hundred-thousandths of seconds in the time interval. Any fractional trailing zeros are not included.
FFFFFF	A placeholder for the millionths of seconds in the time interval. Any fractional trailing zeros are not included.
FFFFFFF	A placeholder for the ten-millionths of seconds in the time interval. Any fractional trailing zeros are not included.
Z	A string presentation of fractional part of seconds (‘f’ in English (U.S.) locale by default).
ZZ	A string presentation of fractional part of seconds (‘fractional’ in English (U.S.) locale by default).
[ and ]	Elements in square brackets ([ and ]) are optional.
:	Time separator. The time separator does not depend on the current culture settings.
.	Decimal separator. The NumberFormatInfo.NumberDecimalSeparator property of the current culture determines the actual decimal separator.
“abc“ or ‘abc‘	Quoted string. Inserts the string enclosed with single or double quotes to the edit box. The string cannot be edited in the text editor.
%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. Mask specifiers consisting of two or more characters are interpreted as custom specifiers. To use a custom specifier that 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.
A number after a mask specifier.	Defines the maximum number of characters in the mask part. For example, the hh3 allows users to enter 3 digits in the hours segment.
Any other characters.	The other characters are inserted to the edit box literally.

End-User Capabilities

• End users can press the Up Arrow and Down Arrow keys to increase and decrease the focused part of the time interval value indicated by the caret. For example, if the day part is edited, pressing these keys changes the day.
• Scrolling the mouse wheel increases and decreases the part of the time interval value indicated by the caret (similar to pressing the Up-Arrow and Down-Arrow keys).
• End users can press the Space character to move the caret from the current position to the following part of a time interval value.
• End users can enter a character representing the time interval separator to move the caret from the current position to the following part of a time interval value.
• Pressing the Left Arrow and Right Arrow keys moves the caret from the current position to the previous or following part of a time interval value.

TimeSpan Mask Options

The TimeSpanMaskOptions class provides a set of attached properties useful to customize the masked input of time span values.

Examples

1. Hidden mask parts.

   Xaml

   <dxe:TextEdit 
                MaskType="TimeSpan" 
                Mask="[hH ][mM ]ssS" 
                EditValue="00:12:23" /> 
   

2. Entering large values.

   Xaml

   <dxe:TextEdit 
                MaskType="TimeSpan" 
                TimeSpanMaskOptions.InputMode="NonLimit" 
                EditValue="12:34:56" />