Mask Type: TimeOnly

• Aug 01, 2024
• 5 minutes to read

The TimeOnly mask type allows users to enter values of the TimeOnly type.

C#

public TimeOnly TimeOnlyValue { get; set; } = new TimeOnly(18, 45, 21, 113);
// ...
textEdit.EditValue = TimeOnlyValue;

VB.NET

Public Property TimeOnlyValue As TimeOnly = New TimeOnly(18, 45, 21, 113)
' ...
textEdit.EditValue = TimeOnlyValue

Standard Masks

The table below contains standard masks that you can select on the main page of the Mask Settings dialog. Note that patterns depend on the current culture. For example, the same input mask can specify different patterns in the U.S. and France. A culture TimeOnly format is defined by the CultureInfo.DateTimeFormat property. Users can change the regional format in the Windows Settings panel.

Mask	Description	Sample
t	Short “hh:mm AM/PM” time format	7:51 PM
T	Long “hh:mm:ss AM/PM” time format	7:51:13 PM
R or r	Time in the RFC1123 format	16:08:00
O or o	ISO 8601 round-trip format	16:08:41.9338901

Custom Masks

You can combine custom mask placeholders to create custom masks of any complexity. For example, to create the “HH:MM AM(PM)” mask, combine custom mask placeholders as follows: h:mm tt.

DevExpress editors support the following custom specifiers and placeholders:

Specifier or placeholder	Description	Example
F or f (%F or %f, if used alone)	One fraction of a second. You can repeat this specifier up to seven times. Masks that have 4 or more “f” (“F”) specifiers are read-only.	1 to 9 (f or F) 01 to 99 (ff or FF) 0000001 to 9999999 (fffffff or FFFFFFF)
s (%s, if used alone)	Second	1, 2, 3 … 59
ss	Second, with a leading zero for single-digit values	01, 02, 03 … 59
h	Hour in 12-hour format	1, 2, 3 … 12
hh	Hour in 12-hour format, with a leading zero for single-digit values	01, 02, 03 … 12
H	Hour in 24-hour format	0, 1, 2 … 23
HH	Hour in 24-hour format, with a leading zero for single-digit values	00, 01, 02 … 23
m	Minute	0, 1, 2 … 59
mm	Minute, with a leading zero for single-digit values	00, 01, 02 … 59
tt	Time designator	AM or PM
t (%t, if used alone)	First letter of the time designator	A or P
:	Time separator according to the culture (the TimeSeparator property).
\	Tells the editor to treat the following symbol as a regular character, not a time specifier. For instance, the “tt” sequence defines a time designator, and the “\t\t” sequence displays static “tt” text.
' or "	Allows you to add static (read-only) strings	‘Current time:’ HH:mm

Example

HH:mm:ss - the 24-hour time format.

TimeOnly Mask Options

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 TimeOnly settings.

To apply these settings in code, call the MaskSettings.Configure<MaskSettings.TimeOnly> method and set up required options for the method return parameter.

Increment or Decrement Neighboring Part Values 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:

C#

// Fluent API
using DevExpress.XtraEditors.Mask;

textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeOnly>(settings => {
    settings.MaskExpression = "HH:mm";
    settings.SpinWithCarry = true;
});

// Regular API
using DevExpress.XtraEditors.Mask;

var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeOnly>();
settings.MaskExpression = "HH:mm";
settings.SpinWithCarry = true;

//Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;

[TimeOnlyEditMask("HH:mm", SpinWithCarry = true)]
public TimeOnly OrderTime { get; set; }

VB.NET

Imports DevExpress.XtraEditors.Mask

Private textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.TimeOnly)(Sub(settings)
    settings.MaskExpression = "HH:mm"
    settings.SpinWithCarry = True
End Sub)

' Regular API

Private settings = textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.TimeOnly)()
settings.MaskExpression = "HH:mm"
settings.SpinWithCarry = True

' Data Source level (for code-first sources)
Using System.ComponentModel.DataAnnotations

<TimeOnlyEditMask("HH:mm", SpinWithCarry := True)>
public TimeOnly OrderTime {get;set;}

Use Advancing Caret

This option specifies whether the caret moves to the next mask segment when the current segment is filled. This behavior allows users to quickly enter time values (for instance, type “112120P” to enter 11:21:20 PM).

If this setting is disabled, a user stays on the hour segment until they press the right arrow key to move the caret.

C#

// Fluent API
using DevExpress.XtraEditors.Mask;

textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeOnly>(settings => {
    settings.MaskExpression = "T";
    settings.UseAdvancingCaret = true;
});

// Regular API
using DevExpress.XtraEditors.Mask;

var settings = textEdit5.Properties.MaskSettings.Configure<MaskSettings.TimeOnly>();
settings.MaskExpression = "T";
settings.UseAdvancingCaret = true;

// Data Source level (for code-first sources)
using System.ComponentModel.DataAnnotations;

[TimeOnlyEditMask("T", UseAdvancingCaret = true)]
public TimeOnly OrderTime { get; set; }

VB.NET

' Fluent API
Imports DevExpress.XtraEditors.Mask

Private textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.TimeOnly)(Sub(settings)
    settings.MaskExpression = "T"
    settings.UseAdvancingCaret = True
End Sub)

' Regular API

Private settings = textEdit5.Properties.MaskSettings.Configure(Of MaskSettings.TimeOnly)()
settings.MaskExpression = "T"
settings.UseAdvancingCaret = True

' Data Source level (for code-first sources)
Using System.ComponentModel.DataAnnotations

<TimeOnlyEditMask("T", UseAdvancingCaret := True)>
public TimeOnly OrderTime {get;set;}

User Capabilities

• The Up and Down Arrow keys increase and decrease the time value portion under the caret.
• The mouse wheel increases and decreases the time value portion under the caret.
• The Space key moves the caret to the next time value portion.
• The time separator key moves the caret to the next time portion.