Time Span Masks

• Nov 19, 2024
• 10 minutes to read

The Masked Input component supports time span input masks. A time span mask allows users to enter only time intervals. Mask behavior can differ depending on the client computer’s culture settings.

Run Demo: Time Span Masks

For more information on other mask types, refer to the following topic: Masks.

Apply a Mask

Before you apply a time span mask to the DxMaskedInput, make sure that the component’s Value property is set to a TimeSpan object or a compatible String (for instance, “5:16:30:15”). In the latter case, set the MaskMode property to TimeSpan.

To apply a time span mask, assign a predefined or custom pattern to the component’s Mask property:

<DxMaskedInput @bind-Value="time"
               Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties CaretMode="@MaskCaretMode.Advancing"/>
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

The DxTimeSpanMaskProperties component allows you to customize mask-related settings. Refer to the following section for more information: Mask Settings.

Predefined Masks

Predefined time span masks allow you to apply a commonly used pattern. The appearance of a mask pattern depends on the current culture. For instance, the same mask can specify different patterns in the U.S. and France.

Users can change the regional format in the Settings → Time & Language → Region system dialog. To change the mask culture programmatically, use the Culture property.

Built-in Patterns

Use properties of the TimeSpanMask class to apply built-in patterns. Each property is a wrapper for the corresponding standard format string. This technique simplifies the setup process.

<DxMaskedInput @bind-Value="time"
               Mask="@TimeSpanMask.GeneralShortFormat">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Standard Format Strings

Time span masks support standard time span format strings. The table below lists available .NET format strings and corresponding predefined patterns:

Predefined Pattern	.NET Format String	Remarks	Sample (en-US)
ConstantFormat	c	Matches the [-][d'.']hh':'mm':'ss['.'fffffff] pattern.	5.16:30:15.0070000
GeneralShortFormat	g	Matches the [-][d':']h':'mm':'ss[.FFFFFFF] pattern.	5:16:30:15.007
GeneralLongFormat	G	Matches the [-]d':'hh':'mm':'ss.fffffff pattern.	5:16:30:15.0070000

The following code snippet uses a standard format string to apply a mask pattern to the Mask Input component:

<DxMaskedInput @bind-Value="time"
               Mask="G">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Custom Masks

You can combine any of the following custom mask placeholders to create custom masks of any complexity:

Specifier/Placeholder	Description	Example
d	A number of days in the time span, with no leading zeros.	0, 1, 2, …
dd-dddddddd	A number of days in the time span, padded with leading zeros as needed. The number of d characters specifies the minimum number of digits.	00, 01, 02, … (dd) 0000, 0001, 0002, … (dddd)
D	A short caption for days.	d
DD	A long caption for days.	day or days
h	A number of hours in the time span, with no leading zeros.	0, 1, 2, …
hh	A number of hours in the time span, with a leading zero for single-digit values.	00, 01, 02, …
H	A short caption for hours.	h
HH	A long caption for hours.	hour or hours
m	A number of minutes in the time span, with no leading zeros.	0, 1, 2 …
mm	A number of minutes in the time span, with a leading zero for single-digit values.	00, 01, 02 …
M	A short caption for minutes.	m
MM	A long caption for minutes.	minute or minutes
s	A number of seconds in the time span, with no leading zeros.	0, 1, 2 …
ss	A number of seconds in the time span, with a leading zero for single-digit values.	00, 01, 02 …
S	A short caption for seconds.	s
SS	A long caption for seconds.	second or seconds
n	A number of milliseconds in the time span, with no leading zeros.	0, 1, 2 …
nn	A number of milliseconds in the time span, with a leading zero for single-digit values.	00, 01, 02 …
nnn	A number of milliseconds in the time span, padded with leading zeros as needed.	000, 001, 002 …
N	A short caption for milliseconds.	ms
NN	A long caption for milliseconds.	millisecond or milliseconds
f-fffffff	A number of fractions of a second, with trailing zeros as needed.	0010 (ffff)
F-FFFFFFF	A number of fractions of a second, with no trailing zeros.	001 (FFFF)
Z	A short caption for fractions of a second.	f
ZZ	A long caption for fractions of a second.	fractional
[ or ]	Enclose a section in square brackets to mark it as optional. The editor can hide optional zero value sections.	00 hours 12 minutes (hh HH mm MM) 12 minutes ([hh HH ]mm MM)
:	A time separator that does not depend on the current culture.	16:30 (hh:mm)
.	A decimal separator that depends on the current culture.	15.007 (ss[.FFFFFFF])
' or "	Allows you to add static (read-only) strings.	14 days left (d DD 'left')
\	Commands the editor to treat the following symbol as a regular character.	ss (\s\s)

A custom format string should consist of two or more characters, because a single-character string is interpreted as a standard format string. To use a custom format string that consists of one character (for instance, includes only the m custom format specifier), use one of the following techniques:

• Include a space before or after the specifier (“m “ or “ m”).
• Include a percent character before the specifier (“%m”).

The following code snippet demonstrates how you can create a custom mask:

<DxMaskedInput @bind-Value="time" 
               Mask="[-][h HH ]mm MM[ ss SS]">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Mask Settings

Add the DxTimeSpanMaskProperties component to the editor’s markup to customize the mask-related settings.

Allow Negative Value

The AllowNegativeValue property specifies whether the editor’s value can be negative. Set this property to false to prevent users from entering a negative value.

Note

You can assign a negative value to the editor even if the AllowNegativeValue is set to false. In this case, the editor converts this value to a positive value only after a user modifies it. Until that time, the editor value remains negative.

The following code snippet prevents users from entering a negative value:

<DxMaskedInput @bind-Value="@time" 
            Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties AllowNegativeValue="false" />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Default Focus Section

A time span mask can include several sections (for instance, hours and minutes). The DefaultFocusSection property allows you to define which section receives focus after you call the FocusAsync() method.

If a user selects all content and starts to enter digits, the editor directs user input into the default focus section. Refer to the following section for more information: Reset All Sections on Select All Input.

The following code snippet sets the Minutes section as the default focus section:

<DxMaskedInput @bind-Value="@time" 
               Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties DefaultFocusSection="@TimeSpanSection.Minutes" />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Navigation Modes

Time span masks support the following navigation modes:

Regular (default)

Input focus stays within one section until a user moves focus to another section.

Advancing caret

After a user completes input into a mask section, the caret moves to the next editable section. To enable this mode, set the CaretMode property to MaskCaretMode.Advancing.

<DxMaskedInput @bind-Value="@time" 
            Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Cascading Updates to Section Values

Time span masks can include several sections (for instance, hours and minutes). Users can enter a required value directly to a mask section or continuously increase or decrease this section’s value. Refer to the following section for more information: User Capabilities.

After the current section’s value passes the maximum or minimum threshold, the editor increases or decreases the value of the next mask section.

Set the UpdateNextSectionOnCycleChange property to false to disable this behavior:

<DxMaskedInput @bind-Value="@Value"
               Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties UpdateNextSectionOnCycleChange="false" />
</DxMaskedInput>

@code {
    TimeSpan Value { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Out of Bounds Value Process Modes

The OutOfBoundsValueProcessMode property specifies whether users can enter a number that exceeds the section’s maximum threshold (for instance, 65 minutes). The property accepts one of the following TimeSpanOutOfBoundsValueProcessMode values:

AcceptForBiggestUnits (default)

Users can enter any number to the mask section that corresponds to the biggest unit of measurement. Into other mask sections, users can enter only valid numbers.

Deny

Users can enter only valid numbers to mask sections (0-23 hours, 0-59 minutes, 0-59 seconds).

UpdateNextSection

Users can enter any number to any mask section. If the entered value is out of bounds, the editor increases its next section value.

The following code snippet prevents users from entering invalid numbers:

<DxMaskedInput @bind-Value="@time" 
            Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties OutOfBoundsValueProcessMode="@TimeSpanOutOfBoundsValueProcessMode.Deny" />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Reset All Sections on Select All Input

A user can select all sections, though a time span mask allows users to modify one section at a time. The SelectAllInputMode property specifies whether the editor should clear all section values after a user selects all sections and enters a new value. The property accepts one of the following TimeSpanSelectAllInputMode values:

ResetDefaultFocusSection (default)

The editor sets the new value to the default focus section and does not change values of other sections.

ResetAllSections

The editor clears all sections of the previous value and sets the new value to the default focus section. Note that the editor hides an optional zero value section if it is the first or last visible section.

<DxMaskedInput @bind-Value="@time" 
               Mask="[dd DD ]hh HH[ mm MM][ ss SS]">
    <DxTimeSpanMaskProperties DefaultFocusSection="@TimeSpanSection.Hours"
                              SelectAllInputMode="@TimeSpanSelectAllInputMode.ResetAllSections" />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

Hide All Optional Zero Value Sections

Enclose mask sections in square brackets to mark them as optional. The editor hides an optional zero value section if it is the first or last visible section. Set the HideAllZeroValueOptionalSections property to true to hide all zero value optional sections:

<DxMaskedInput @bind-Value="@time" 
               Mask="[dd DD ]hh HH[ mm MM][ ss SS][nnn NN]">
    <DxTimeSpanMaskProperties HideAllZeroValueOptionalSections=true />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 0, 15, 0);
}

This setting can affect the editor’s value readability. In the following code snippet, the editor hides the minutes section. As a result, the editor value is short but unclear.

<DxMaskedInput @bind-Value="@time" 
               Mask="[dd.]hh[:mm][:ss][:fff]">
    <DxTimeSpanMaskProperties HideAllZeroValueOptionalSections=true />
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 0, 15, 0);
}

User Capabilities

• The Up/Down arrow keys increase/decrease the value of the mask section under the caret.
• The mouse wheel increases and decreases the value of the mask section under the caret.
• The Space key moves the caret to the next mask section.

User Scenarios

Stopwatch

<DxMaskedInput @bind-Value="@time" 
               Mask="[d.]hh:mm:ss[.fff]">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

The mask in this example - [d.]hh:mm:ss[.fff] - allows you to display the elapsed time of a lengthy process.

User-Friendly Timer

<DxMaskedInput @bind-Value="@time" 
               Mask="dd DD hh HH mm MM">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

The mask in this example - dd DD hh HH mm MM - displays labels that indicate each section’s units.

Count Down the Days

<DxMaskedInput @bind-Value="@time" 
               Mask="dd DD 'left'">
</DxMaskedInput>

@code {
    TimeSpan time { get; set; } = new TimeSpan(5, 16, 30, 15, 7);
}

The mask in this example - dd DD 'left' - counts down the days.