class sap.m.TimePicker

Control sample: sap.m.TimePicker
Visiblity: public
UX Guidelines: Time Picker
Implements:
Available since: N/A
Module: sap/m/TimePicker
Application Component: CA-UI5-CTR

A single-field input control that enables the users to fill time related input fields.

Overview

The TimePicker control enables the users to fill time related input fields using touch, mouse, or keyboard input.

Usage

Use this control if you want the user to select a time. If you want the user to select a duration (1 hour), use the sap.m.Select control instead.

The user can fill time by:

On app level, there are two options to provide value for the TimePicker - as a string to the value property or as a JavaScript Date object to the dateValue property (only one of these properties should be used at a time):

Formatting

All formatting and parsing of values from and to strings is done using the sap.ui.core.format.DateFormat. If a value is entered by typing it into the input field, it must fit to the used time format and locale.

Supported format options are pattern-based on Unicode LDML Date Format notation. See http://unicode.org/reports/tr35/#Date_Field_Symbol_Table

A time format must be specified, otherwise the default "HH:mm:ss a" will be used. For example, if the valueFormat is "HH-mm-ss a", the displayFormat is "HH:mm:ss a", and the used locale is English, a valid value string is "10-30-15 AM", which leads to an output of "10:30:15 AM".

If no placeholder is set to the TimePicker, the used displayFormat is displayed as a placeholder. If another placeholder is needed, it must be set.

Note: If the string does NOT match the displayFormat (from user input) or the valueFormat (on app level), the sap.ui.core.format.DateFormat makes an attempt to parse it based on the locale settings. For more information, see the respective documentation in the API Reference.

Responsive behavior

The TimePicker is responsive and fully adapts to all device types. For larger screens, such as tablet or desktop, it opens as a popover. For mobile devices, it opens in full screen.

This control can be a drop target.

Constructor

Constructor for a new TimePicker.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.TimePicker(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
localeId string

Defines the locale used to parse string values representing time.

Determines the locale, used to interpret the string, supplied by the value property.

Example: AM in the string "09:04 AM" is locale (language) dependent. The format comes from the browser language settings if not set explicitly. Used in combination with 12 hour displayFormat containing 'a', which stands for day period string.

Visibility: public
mask string

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

Visibility: public
maskMode sap.m.TimePickerMaskMode On

Defines whether the mask is enabled. When disabled, there are no restrictions and validation for the user and no placeholders are displayed.

Note: A disabled mask does not reset any validation rules that are already set. You can update the mask property and add new rules while it is disabled. When maskMode is set to On again, the rules and the updated mask will be applied.

Since: 1.54.

Visibility: public
minutesStep int 1

Sets the minutes step. If step is less than 1, it will be automatically converted back to 1. The minutes clock is populated only by multiples of the step.

Since: 1.40.

Visibility: public
placeholderSymbol string _

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Visibility: public
secondsStep int 1

Sets the seconds step. If step is less than 1, it will be automatically converted back to 1. The seconds clock is populated only by multiples of the step.

Since: 1.40.

Visibility: public
support2400 boolean false

Allows to set a value of 24:00, used to indicate the end of the day. Works only with HH or H formats. Don't use it together with am/pm.

Since: 1.54.

Visibility: public
title string

Displays the text of the general picker label and is read by screen readers. It is visible only on phone.

Visibility: public

Borrowed Properties

Name Type Default Value Description
dateValue object

Holds a reference to a JavaScript Date Object. The value (string) property will be set according to it. Alternatively, if the value and valueFormat pair properties are supplied instead, the dateValue will be instantiated according to the parsed value. Use dateValue as a helper property to easily obtain the day, month, year, hours, minutes and seconds of the chosen date and time. Although possible to bind it, the recommendation is not to do it. When binding is needed, use value property instead.

Visibility: public
displayFormat string

Determines the format, displayed in the input field.

Visibility: public
initialFocusedDateValue object

Holds a reference to a JavaScript Date Object to define the initially focused date/time when the picker popup is opened.

Notes:

  • Setting this property does not change the value property.
  • Depending on the context this property is used in (sap.m.TimePicker, sap.m.DatePicker or sap.m.DateTimePicker), it takes into account only the time part, only the date part or both parts of the JavaScript Date Object.


Since: 1.54.

Visibility: public
valueFormat string

Determines the format of the value property.

Visibility: public
editable boolean true

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Since: 1.12.0.

Visibility: public
enabled boolean true

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Visibility: public
name string

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

Visibility: public
placeholder string

Defines a short hint intended to aid the user with data entry when the control has no value.

Visibility: public
required boolean false

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
value string

Defines the value of the control.

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

Since: 1.26.0.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_numPicker 0..1 sap.m.Popover

Internal aggregation that contains the inner numeric _picker pop-up.

_picker 0..1 sap.m.ResponsivePopover

Internal aggregation that contains the inner clock _picker pop-up.

rules 0..n sap.m.MaskInputRule

A list of validation rules (one rule per mask character).

Borrowed Aggregations

Name Cardinality Type Description
formattedValueStateText 0..1 sap.m.FormattedText

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Events Overview

Event Description
change

Fires when the input operation has finished and the value has changed.

change

Fires when the input operation has finished and the value has changed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The new value of the input Note: If there is no data binding, the value is expected and updated in Gregorian calendar type. (Otherwise, the type of the binding is used.)

valid boolean

Indicator for a valid time


Methods Overview

Method Description
addRule

Adds some rule to the aggregation rules.

destroyRules

Destroys all the rules in the aggregation rules.

sap.m.TimePicker.extend

Creates a new subclass of class sap.m.TimePicker with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.DateTimeField.extend.

fireChange

Fires change event to attached listeners.

Expects following event parameters:

  • value parameter of type string - the new value of the input
  • valid parameter of type boolean - indicator for a valid time

fireChangeEvent

Fires the change event for the listeners.

getAccessibilityInfo

References:

  • sap.ui.core.Control#getAccessibilityInfo

getDateValue

Holds a reference to a JavaScript Date Object. The value (string) property will be set according to it. Alternatively, if the value and valueFormat pair properties are supplied instead, the dateValue will be instantiated according to the parsed value.

getDisplayFormat

Determines the format, displayed in the input field and the picker clocks/numeric inputs.

The default value is the browser's medium time format locale setting sap.ui.core.LocaleData#getTimePattern. If data binding with type sap.ui.model.type.Time or sap.ui.model.odata.type.Time is used for the value property, the displayFormat property is ignored as the information is provided from the binding itself.

getLocaleId

Gets current value of property localeId.

Defines the locale used to parse string values representing time.

Determines the locale, used to interpret the string, supplied by the value property.

Example: AM in the string "09:04 AM" is locale (language) dependent. The format comes from the browser language settings if not set explicitly. Used in combination with 12 hour displayFormat containing 'a', which stands for day period string.

getMask

Gets current value of property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

getMaskMode

Gets current value of property maskMode.

Defines whether the mask is enabled. When disabled, there are no restrictions and validation for the user and no placeholders are displayed.

Note: A disabled mask does not reset any validation rules that are already set. You can update the mask property and add new rules while it is disabled. When maskMode is set to On again, the rules and the updated mask will be applied.

Default value is On.

sap.m.TimePicker.getMetadata

Returns a metadata object for class sap.m.TimePicker.

getMinutesStep

Gets current value of property minutesStep.

Sets the minutes step. If step is less than 1, it will be automatically converted back to 1. The minutes clock is populated only by multiples of the step.

Default value is 1.

getPlaceholderSymbol

Gets current value of property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Default value is "_".

getRules

Gets content of aggregation rules.

A list of validation rules (one rule per mask character).

getSecondsStep

Gets current value of property secondsStep.

Sets the seconds step. If step is less than 1, it will be automatically converted back to 1. The seconds clock is populated only by multiples of the step.

Default value is 1.

getSupport2400

Gets current value of property support2400.

Allows to set a value of 24:00, used to indicate the end of the day. Works only with HH or H formats. Don't use it together with am/pm.

Default value is false.

getTitle

Gets current value of property title.

Displays the text of the general picker label and is read by screen readers. It is visible only on phone.

getValueFormat

Determines the format of the value property.

The default value is the browser's medium time format locale setting sap.ui.core.LocaleData#getTimePattern. If data binding with type sap.ui.model.type.Time or sap.ui.model.odata.type.Time is used for the value property, the valueFormat property is ignored as the information is provided from the binding itself.

indexOfRule

Checks for the provided sap.m.MaskInputRule in the aggregation rules. and returns its index if found or -1 otherwise.

init

Initializes the control.

insertRule

Inserts a rule into the aggregation rules.

onAfterClose

Called after the clock picker closes.

onAfterOpen

Called after the clock picker appears.

onBeforeClose

Called before the clock picker closes.

onBeforeOpen

Called before the clock picker appears.

removeAllRules

Removes all the controls from the aggregation rules.

Additionally, it unregisters them from the hosting UIArea.

removeRule

Removes a rule from the aggregation rules.

setDateValue

Sets the value of the date.

setDisplayFormat

Sets the display format.

setLocaleId

Sets the locale of the control.

Used for parsing and formatting the time values in languages different than English. Necessary for translation and auto-complete of the day periods, such as AM and PM.

setMask

Sets a new value for property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

When called with a value of null or undefined, the default value of the property will be restored.

setMaskMode

Sets a new value for property maskMode.

Defines whether the mask is enabled. When disabled, there are no restrictions and validation for the user and no placeholders are displayed.

Note: A disabled mask does not reset any validation rules that are already set. You can update the mask property and add new rules while it is disabled. When maskMode is set to On again, the rules and the updated mask will be applied.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is On.

setMinutesStep

Sets the minutes step of clocks and inputs.

setPlaceholderSymbol

Sets a new value for property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "_".

setSecondsStep

Sets the seconds step of clocks and inputs.

setSupport2400

Sets support2400 of the control.

Allows the control to use 24-hour format. Recommended usage is to not use it with am/pm format.

setTooltip

Sets tooltip of the control.

addRule

Adds some rule to the aggregation rules.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule to add; if empty, nothing is inserted

destroyRules

Destroys all the rules in the aggregation rules.

sap.m.TimePicker.extend

Creates a new subclass of class sap.m.TimePicker with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.DateTimeField.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireChange

Fires change event to attached listeners.

Expects following event parameters:

Param Type DefaultValue Description
mArguments object

The arguments to pass along with the event

fireChangeEvent

Fires the change event for the listeners.

Param Type DefaultValue Description
sValue string

value of the input.

oParams object

extra event parameters.

getAccessibilityInfo

References:

getDateValue

Holds a reference to a JavaScript Date Object. The value (string) property will be set according to it. Alternatively, if the value and valueFormat pair properties are supplied instead, the dateValue will be instantiated according to the parsed value.

getDisplayFormat

Determines the format, displayed in the input field and the picker clocks/numeric inputs.

The default value is the browser's medium time format locale setting sap.ui.core.LocaleData#getTimePattern. If data binding with type sap.ui.model.type.Time or sap.ui.model.odata.type.Time is used for the value property, the displayFormat property is ignored as the information is provided from the binding itself.

getLocaleId

Gets current value of property localeId.

Defines the locale used to parse string values representing time.

Determines the locale, used to interpret the string, supplied by the value property.

Example: AM in the string "09:04 AM" is locale (language) dependent. The format comes from the browser language settings if not set explicitly. Used in combination with 12 hour displayFormat containing 'a', which stands for day period string.

getMask

Gets current value of property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

getMaskMode

Gets current value of property maskMode.

Defines whether the mask is enabled. When disabled, there are no restrictions and validation for the user and no placeholders are displayed.

Note: A disabled mask does not reset any validation rules that are already set. You can update the mask property and add new rules while it is disabled. When maskMode is set to On again, the rules and the updated mask will be applied.

Default value is On.

sap.m.TimePicker.getMetadata

Returns a metadata object for class sap.m.TimePicker.

getMinutesStep

Gets current value of property minutesStep.

Sets the minutes step. If step is less than 1, it will be automatically converted back to 1. The minutes clock is populated only by multiples of the step.

Default value is 1.

getPlaceholderSymbol

Gets current value of property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

Default value is "_".

getRules

Gets content of aggregation rules.

A list of validation rules (one rule per mask character).

getSecondsStep

Gets current value of property secondsStep.

Sets the seconds step. If step is less than 1, it will be automatically converted back to 1. The seconds clock is populated only by multiples of the step.

Default value is 1.

getSupport2400

Gets current value of property support2400.

Allows to set a value of 24:00, used to indicate the end of the day. Works only with HH or H formats. Don't use it together with am/pm.

Default value is false.

getTitle

Gets current value of property title.

Displays the text of the general picker label and is read by screen readers. It is visible only on phone.

getValueFormat

Determines the format of the value property.

The default value is the browser's medium time format locale setting sap.ui.core.LocaleData#getTimePattern. If data binding with type sap.ui.model.type.Time or sap.ui.model.odata.type.Time is used for the value property, the valueFormat property is ignored as the information is provided from the binding itself.

indexOfRule

Checks for the provided sap.m.MaskInputRule in the aggregation rules. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule whose index is looked for

init

Initializes the control.

insertRule

Inserts a rule into the aggregation rules.

Param Type DefaultValue Description
oRule sap.m.MaskInputRule

The rule to insert; if empty, nothing is inserted

iIndex int

The 0-based index the rule should be inserted at; for a negative value of iIndex, the rule is inserted at position 0; for a value greater than the current size of the aggregation, the rule is inserted at the last position

onAfterClose

Called after the clock picker closes.

onAfterOpen

Called after the clock picker appears.

onBeforeClose

Called before the clock picker closes.

onBeforeOpen

Called before the clock picker appears.

removeAllRules

Removes all the controls from the aggregation rules.

Additionally, it unregisters them from the hosting UIArea.

removeRule

Removes a rule from the aggregation rules.

Param Type DefaultValue Description
vRule int string sap.m.MaskInputRule

The rule to remove or its index or id

setDateValue

Sets the value of the date.

Param Type DefaultValue Description
oDate object

date object

setDisplayFormat

Sets the display format.

Param Type DefaultValue Description
sDisplayFormat string

display format to set

setLocaleId

Sets the locale of the control.

Used for parsing and formatting the time values in languages different than English. Necessary for translation and auto-complete of the day periods, such as AM and PM.

Param Type DefaultValue Description
sLocaleId string

A locale identifier like 'en_US'

setMask

Sets a new value for property mask.

Mask defined by its characters type (respectively, by its length). You should consider the following important facts: 1. The mask characters normally correspond to an existing rule (one rule per unique char). Characters which don't, are considered immutable characters (for example, the mask '2099', where '9' corresponds to a rule for digits, has the characters '2' and '0' as immutable). 2. Adding a rule corresponding to the placeholderSymbol is not recommended and would lead to an unpredictable behavior. 3. You can use the special escape character '^' called "Caret" prepending a rule character to make it immutable. Use the double escape '^^' if you want to make use of the escape character as an immutable one.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sMask string

New value for property mask

setMaskMode

Sets a new value for property maskMode.

Defines whether the mask is enabled. When disabled, there are no restrictions and validation for the user and no placeholders are displayed.

Note: A disabled mask does not reset any validation rules that are already set. You can update the mask property and add new rules while it is disabled. When maskMode is set to On again, the rules and the updated mask will be applied.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is On.

Param Type DefaultValue Description
sMaskMode sap.m.TimePickerMaskMode On

New value for property maskMode

setMinutesStep

Sets the minutes step of clocks and inputs.

Param Type DefaultValue Description
step int

The step used to generate values for the minutes clock/input

setPlaceholderSymbol

Sets a new value for property placeholderSymbol.

Defines a placeholder symbol. Shown at the position where there is no user input yet.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "_".

Param Type DefaultValue Description
sPlaceholderSymbol string "_"

New value for property placeholderSymbol

setSecondsStep

Sets the seconds step of clocks and inputs.

Param Type DefaultValue Description
step int

The step used to generate values for the seconds clock/input

setSupport2400

Sets support2400 of the control.

Allows the control to use 24-hour format. Recommended usage is to not use it with am/pm format.

Param Type DefaultValue Description
bSupport2400 boolean

setTooltip

Sets tooltip of the control.

Param Type DefaultValue Description
vTooltip string sap.ui.core.TooltipBase