A single-field input control that enables the users to fill time related input fields.
The TimePicker
control enables the users to fill time related input fields using touch, mouse, or keyboard input.
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):
value
property if you want to bind the TimePicker
to a model using the sap.ui.model.type.Time
value
property if the date is provided as a string from the backend or inside the app (for example, as ABAP type DATS field)dateValue
property if the date is already provided as a JavaScript Date object or you want to work with a JavaScript Date object. Use dateValue
as a helper property to easily obtain the hours, minutes and seconds of the chosen time. Although possible to bind it, the recommendation is to not to do it. When binding is needed, use value
property insteadAll 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.
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.
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 |
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 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 |
|
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 |
|
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 |
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. |
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. |
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. |
title | string | Displays the text of the general picker label and is read by screen readers. It is visible only on phone. Visibility: public |
Name | Type | Default Value | Description |
---|---|---|---|
dateValue | object | Holds a reference to a JavaScript Date Object. The |
|
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:
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. |
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 |
showValueStateMessage | boolean | true | Indicates whether the value state message should be shown or not. |
textAlign | sap.ui.core.TextAlign | Initial | Defines the horizontal alignment of the text that is shown inside the input field. |
textDirection | sap.ui.core.TextDirection | Inherit | Defines the text directionality of the input field, e.g. |
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. |
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. |
|
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 |
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). |
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 |
Event | Description |
---|---|
change |
Fires when the input operation has finished and the value has changed. |
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 |
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
|
fireChange |
Fires change event to attached listeners. Expects following event parameters:
|
fireChangeEvent |
Fires the change event for the listeners. |
getAccessibilityInfo |
References:
|
getDateValue |
Holds a reference to a JavaScript Date Object. The |
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 |
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 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 |
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 |
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 Default value is |
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 |
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 |
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 |
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 |
indexOfRule |
Checks for the provided |
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 When called with a value of |
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 When called with a value of Default value is |
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 Default value is |
setSecondsStep |
Sets the seconds step of clocks and inputs. |
setSupport2400 |
Sets 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. |
Adds some rule to the aggregation rules.
Param | Type | DefaultValue | Description |
---|---|---|---|
oRule | sap.m.MaskInputRule |
The rule to add; if empty, nothing is inserted |
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 |
Fires change event to attached listeners.
Expects following event parameters:
string
- the new value of the inputboolean
- indicator for a valid timeParam | Type | DefaultValue | Description |
---|---|---|---|
mArguments | object |
The arguments to pass along with the event |
Fires the change event for the listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValue | string |
value of the input. |
|
oParams | object |
extra event parameters. |
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
.
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.
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.
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.
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
.
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
.
Gets current value of property placeholderSymbol.
Defines a placeholder symbol. Shown at the position where there is no user input yet.
Default value is "_"
.
Gets content of aggregation rules.
A list of validation rules (one rule per mask character).
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
.
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
.
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.
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.
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 |
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 |
Removes all the controls from the aggregation rules.
Additionally, it unregisters them from the hosting UIArea.
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 |
Sets the value of the date.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDate | object |
date object |
Sets the display format.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDisplayFormat | string |
display format to set |
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' |
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 |
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 |
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 |
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 |
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 |
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 |
Sets tooltip of the control.
Param | Type | DefaultValue | Description |
---|---|---|---|
vTooltip | string sap.ui.core.TooltipBase |