Allows the user to change the input values with predefined increments (steps).
The StepInput
consists of an input field and buttons with icons to increase/decrease the value.
The user can change the value of the control by pressing the increase/decrease buttons, by typing a number directly, by using the keyboard up/down and page up/down, or by using the mouse scroll wheel. Decimal values are supported.
The default step is 1 but the app developer can set a different one.
On desktop, the control supports a larger step, when using the keyboard page up/down keys. You can set a multiple of the step with the use of the largerStep
property. The default value is 2 (two times the set step). For example, when using the keyboard page up/down keys the value increases/decreases with a double of the default step. If the set step is 2, the larger step is also 2 and the current value is 1, using the page up key will increase the value to 5 (1 + 2*2).
App developers can set a maximum and minimum value for the StepInput
. The increase/decrease button and the up/down keyboard navigation become disabled when the value reaches the max/min or a new value is entered from the input which is greater/less than the max/min.
When to use
When not to use
Note: The control uses a JavaScript number to keep its value, which has a certain precision limit.
In general, exponential notation is used:
Exponential notation is not supported by the control and using it may lead to unpredictable behavior.
Also, the JavaScript number persists its precision up to 16 digits. If the user enters a number with a greater precision, the value will be rounded.
This restriction comes from JavaScript itself and it cannot be worked around in a feasible way.
Note: Formatting of decimal numbers is browser dependent, regardless of framework number formatting.
Constructor for a new StepInput
.
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.StepInput(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 |
---|---|---|---|
description | string | Determines the description text after the input field, for example units of measurement, currencies. |
|
displayValuePrecision | int | 0 | Determines the number of digits after the decimal point. The value should be between 0 (default) and 20. In case the value is not valid it will be set to the default value. |
editable | boolean | true | Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it. 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 |
fieldWidth | sap.ui.core.CSSSize | 50% | Determines the distribution of space between the input field and the description text . Default value is 50% (leaving the other 50% for the description). Note: This property takes effect only if the |
largerStep | float | 2 | Increases/decreases the value with a larger value than the set step only when using the PageUp/PageDown keys. Default value is 2 times larger than the set step. Visibility: public |
max | float | Sets the maximum possible value of the defined range. Visibility: public |
|
min | float | Sets the minimum possible value of the defined range. Visibility: public |
|
name | string | Defines the name of the control for the purposes of form submission. |
|
placeholder | string | Defines a short hint intended to aid the user with data entry when the control has no value. |
|
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 |
step | float | 1 | Increases/decreases the value of the input.
|
stepMode | sap.m.StepInputStepModeType | AdditionAndSubtraction | Defines the calculation mode for the provided If the user increases/decreases the value by |
textAlign | sap.ui.core.TextAlign | End | Defines the horizontal alignment of the text that is displayed inside the input field. |
validationMode | sap.m.StepInputValidationMode | FocusOut | Defines when the validation of the typed value will happen. By default this happens on focus out. |
value | float | 0 | Determines the value of the |
valueState | sap.ui.core.ValueState | None | Accepts the core enumeration ValueState.type that supports |
valueStateText | string | Defines the text that appears in the value state message pop-up. |
|
width | sap.ui.core.CSSSize | Defines the width of the control. Visibility: public |
Default Aggregation:
Name | Cardinality | Type | Description |
---|---|---|---|
_input | 0..1 | sap.ui.core.Control |
Internal aggregation that contains the |
Name | Cardinality | Type | Description |
---|---|---|---|
ariaDescribedBy | 0..n | sap.ui.core.Control |
Association to controls / IDs which describe this control (see WAI-ARIA attribute aria-describedby). |
ariaLabelledBy | 0..n | sap.ui.core.Control |
Association to controls / IDs that label this control (see WAI-ARIA attribute aria-labelledby). |
Event | Description |
---|---|
change |
Is fired when one of the following happens:
|
Is fired when one of the following happens:
Param | Type | Description |
---|---|---|
oControlEvent | sap.ui.base.Event | |
getSource | sap.ui.base.EventProvider | |
getParameters | object | |
value | string |
The new |
Method | Description |
---|---|
addAriaDescribedBy |
Adds some ariaDescribedBy into the association ariaDescribedBy. |
addAriaLabelledBy |
Adds some ariaLabelledBy into the association ariaLabelledBy. |
attachChange |
Attaches event handler When called, the context of the event handler (its Is fired when one of the following happens:
|
detachChange |
Detaches event handler The passed function and listener object must match the ones used for event registration. |
sap.m.StepInput.extend |
Creates a new subclass of class sap.m.StepInput with name
|
fireChange |
Fires event change to attached listeners. |
getAriaDescribedBy |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy. |
getAriaLabelledBy |
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy. |
getDescription |
Gets current value of property description. Determines the description text after the input field, for example units of measurement, currencies. |
getDisplayValuePrecision |
Gets current value of property displayValuePrecision. Determines the number of digits after the decimal point. The value should be between 0 (default) and 20. In case the value is not valid it will be set to the default value. Default value is |
getEditable |
Gets current value of property editable. Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it. Default value is |
getEnabled |
Gets current value of property enabled. 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. Default value is |
getFieldWidth |
Gets current value of property fieldWidth. Determines the distribution of space between the input field and the description text . Default value is 50% (leaving the other 50% for the description). Note: This property takes effect only if the Default value is |
getIdForLabel |
Returns the DOMNode Id to be used for the "labelFor" attribute of the label. By default, this is the Id of the control itself. |
getLargerStep |
Gets current value of property largerStep. Increases/decreases the value with a larger value than the set step only when using the PageUp/PageDown keys. Default value is 2 times larger than the set step. Default value is |
getMax |
Gets current value of property max. Sets the maximum possible value of the defined range. |
sap.m.StepInput.getMetadata |
Returns a metadata object for class sap.m.StepInput. |
getMin |
Gets current value of property min. Sets the minimum possible value of the defined range. |
getName |
Gets current value of property name. Defines the name of the control for the purposes of form submission. |
getPlaceholder |
Gets current value of property placeholder. Defines a short hint intended to aid the user with data entry when the control has no value. |
getRequired |
Gets current value of property required. 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 Default value is |
getStep |
Gets current value of property step. Increases/decreases the value of the input.
Default value is |
getStepMode |
Gets current value of property stepMode. Defines the calculation mode for the provided If the user increases/decreases the value by Default value is |
getTextAlign |
Gets current value of property textAlign. Defines the horizontal alignment of the text that is displayed inside the input field. Default value is |
getValidationMode |
Gets current value of property validationMode. Defines when the validation of the typed value will happen. By default this happens on focus out. Default value is |
getValue |
Gets current value of property value. Determines the value of the Default value is |
getValueState |
Gets current value of property valueState. Accepts the core enumeration ValueState.type that supports Default value is |
getValueStateText |
Gets current value of property valueStateText. Defines the text that appears in the value state message pop-up. |
getWidth |
Gets current value of property width. Defines the width of the control. |
removeAllAriaDescribedBy |
Removes all the controls in the association named ariaDescribedBy. |
removeAllAriaLabelledBy |
Removes all the controls in the association named ariaLabelledBy. |
removeAriaDescribedBy |
Removes an ariaDescribedBy from the association named ariaDescribedBy. |
removeAriaLabelledBy |
Removes an ariaLabelledBy from the association named ariaLabelledBy. |
setDescription |
Sets a new value for property description. Determines the description text after the input field, for example units of measurement, currencies. When called with a value of |
setDisplayValuePrecision |
Sets a new value for property displayValuePrecision. Determines the number of digits after the decimal point. The value should be between 0 (default) and 20. In case the value is not valid it will be set to the default value. When called with a value of Default value is |
setEditable |
Sets a new value for property editable. Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it. When called with a value of Default value is |
setEnabled |
Sets a new value for property enabled. 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. When called with a value of Default value is |
setFieldWidth |
Sets a new value for property fieldWidth. Determines the distribution of space between the input field and the description text . Default value is 50% (leaving the other 50% for the description). Note: This property takes effect only if the When called with a value of Default value is |
setLargerStep |
Sets a new value for property largerStep. Increases/decreases the value with a larger value than the set step only when using the PageUp/PageDown keys. Default value is 2 times larger than the set step. When called with a value of Default value is |
setName |
Sets a new value for property name. Defines the name of the control for the purposes of form submission. When called with a value of |
setPlaceholder |
Sets a new value for property placeholder. Defines a short hint intended to aid the user with data entry when the control has no value. When called with a value of |
setRequired |
Sets a new value for property required. 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 When called with a value of Default value is |
setStep |
Sets a new value for property step. Increases/decreases the value of the input.
When called with a value of Default value is |
setStepMode |
Sets a new value for property stepMode. Defines the calculation mode for the provided If the user increases/decreases the value by When called with a value of Default value is |
setTextAlign |
Sets a new value for property textAlign. Defines the horizontal alignment of the text that is displayed inside the input field. When called with a value of Default value is |
setValue |
Sets a new value for property value. Determines the value of the When called with a value of Default value is |
setValueState |
Sets a new value for property valueState. Accepts the core enumeration ValueState.type that supports When called with a value of Default value is |
setValueStateText |
Sets a new value for property valueStateText. Defines the text that appears in the value state message pop-up. When called with a value of |
setWidth |
Sets a new value for property width. Defines the width of the control. When called with a value of |
Adds some ariaDescribedBy into the association ariaDescribedBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaDescribedBy | sap.ui.core.ID sap.ui.core.Control |
The ariaDescribedBy to add; if empty, nothing is inserted |
Adds some ariaLabelledBy into the association ariaLabelledBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaLabelledBy | sap.ui.core.ID sap.ui.core.Control |
The ariaLabelledBy to add; if empty, nothing is inserted |
Attaches event handler fnFunction
to the change event of this sap.m.StepInput
.
When called, the context of the event handler (its this
) will be bound to oListener
if specified, otherwise it will be bound to this sap.m.StepInput
itself.
Is fired when one of the following happens:
Param | Type | DefaultValue | Description |
---|---|---|---|
oData | object |
An application-specific payload object that will be passed to the event handler along with the event object when firing the event |
|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called when the event occurs |
|
oListener | object |
Context object to call the event handler with. Defaults to this |
Detaches event handler fnFunction
from the change event of this sap.m.StepInput
.
The passed function and listener object must match the ones used for event registration.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function(sap.ui.base.Event) : void |
The function to be called, when the event occurs |
|
oListener | object |
Context object on which the given function had to be called |
Creates a new subclass of class sap.m.StepInput with name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
might contain the same kind of information as described in sap.ui.core.Control.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 event change to attached listeners.
Param | Type | DefaultValue | Description |
---|---|---|---|
mParameters | object |
Parameters to pass along with the event |
|
value | string |
The new |
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Gets current value of property description.
Determines the description text after the input field, for example units of measurement, currencies.
Gets current value of property displayValuePrecision.
Determines the number of digits after the decimal point.
The value should be between 0 (default) and 20. In case the value is not valid it will be set to the default value.
Default value is 0
.
Gets current value of property editable.
Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.
Default value is true
.
Gets current value of property enabled.
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.
Default value is true
.
Gets current value of property fieldWidth.
Determines the distribution of space between the input field and the description text . Default value is 50% (leaving the other 50% for the description).
Note: This property takes effect only if the description
property is also set.
Default value is '50%'
.
Returns the DOMNode Id to be used for the "labelFor" attribute of the label.
By default, this is the Id of the control itself.
Gets current value of property largerStep.
Increases/decreases the value with a larger value than the set step only when using the PageUp/PageDown keys. Default value is 2 times larger than the set step.
Default value is 2
.
Gets current value of property name.
Defines the name of the control for the purposes of form submission.
Gets current value of property placeholder.
Defines a short hint intended to aid the user with data entry when the control has no value.
Gets current value of property required.
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).
Default value is false
.
Gets current value of property step.
Increases/decreases the value of the input.
step
property should not contain more digits after the decimal point than what is set to the displayValuePrecision
property, as it may lead to an increase/decrease that is not visible for the user. For example, if the value
is set to 1.22 and the displayValuePrecision
is set to one digit after the decimal, the user will see 1.2. In this case, if the value
of the step
property is set to 1.005 and the user selects increase
, the resulting value will increase to 1.2261 but the displayed value will remain as 1.2 as it will be rounded to the first digit after the decimal point.value
and the displayValuePrecision
properties, it is possible the displayed value to be rounded to a higher number, for example to 3.0 when the actual value is 2.99.Default value is 1
.
Gets current value of property stepMode.
Defines the calculation mode for the provided step
and largerStep
.
If the user increases/decreases the value by largerStep
, this calculation will consider it as well. For example, if the current value
is 3, step
is 5, largerStep
is 5 and the user chooses PageUp, the calculation logic will consider the value of 3x5=15 to decide what will be the next value
.
Default value is AdditionAndSubtraction
.
Gets current value of property textAlign.
Defines the horizontal alignment of the text that is displayed inside the input field.
Default value is End
.
Gets current value of property validationMode.
Defines when the validation of the typed value will happen. By default this happens on focus out.
Default value is FocusOut
.
Gets current value of property value.
Determines the value of the StepInput
and can be set initially from the app developer.
Default value is 0
.
Gets current value of property valueState.
Accepts the core enumeration ValueState.type that supports None
, Error
, Warning
and Success
. ValueState is managed internally only when validation is triggered by user interaction.
Default value is None
.
Gets current value of property valueStateText.
Defines the text that appears in the value state message pop-up.
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaDescribedBy | int sap.ui.core.ID sap.ui.core.Control |
The ariaDescribedBy to be removed or its index or ID |
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Param | Type | DefaultValue | Description |
---|---|---|---|
vAriaLabelledBy | int sap.ui.core.ID sap.ui.core.Control |
The ariaLabelledBy to be removed or its index or ID |
Sets a new value for property description.
Determines the description text after the input field, for example units of measurement, currencies.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sDescription | string |
New value for property |
Sets a new value for property displayValuePrecision.
Determines the number of digits after the decimal point.
The value should be between 0 (default) and 20. In case the value is not valid it will be set to the default value.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 0
.
Param | Type | DefaultValue | Description |
---|---|---|---|
iDisplayValuePrecision | int | 0 |
New value for property |
Sets a new value for property editable.
Defines whether the control can be modified by the user or not. Note: A user can tab to the non-editable control, highlight it, and copy the text from it.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is true
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bEditable | boolean | true |
New value for property |
Sets a new value for property enabled.
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.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is true
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bEnabled | boolean | true |
New value for property |
Sets a new value for property fieldWidth.
Determines the distribution of space between the input field and the description text . Default value is 50% (leaving the other 50% for the description).
Note: This property takes effect only if the description
property is also set.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is '50%'
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sFieldWidth | sap.ui.core.CSSSize | '50%' |
New value for property |
Sets a new value for property largerStep.
Increases/decreases the value with a larger value than the set step only when using the PageUp/PageDown keys. Default value is 2 times larger than the set step.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 2
.
Param | Type | DefaultValue | Description |
---|---|---|---|
fLargerStep | float | 2 |
New value for property |
Sets a new value for property name.
Defines the name of the control for the purposes of form submission.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string |
New value for property |
Sets a new value for property placeholder.
Defines a short hint intended to aid the user with data entry when the control has no value.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPlaceholder | string |
New value for property |
Sets a new value for property required.
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).
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is false
.
Param | Type | DefaultValue | Description |
---|---|---|---|
bRequired | boolean | false |
New value for property |
Sets a new value for property step.
Increases/decreases the value of the input.
step
property should not contain more digits after the decimal point than what is set to the displayValuePrecision
property, as it may lead to an increase/decrease that is not visible for the user. For example, if the value
is set to 1.22 and the displayValuePrecision
is set to one digit after the decimal, the user will see 1.2. In this case, if the value
of the step
property is set to 1.005 and the user selects increase
, the resulting value will increase to 1.2261 but the displayed value will remain as 1.2 as it will be rounded to the first digit after the decimal point.value
and the displayValuePrecision
properties, it is possible the displayed value to be rounded to a higher number, for example to 3.0 when the actual value is 2.99.When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 1
.
Param | Type | DefaultValue | Description |
---|---|---|---|
fStep | float | 1 |
New value for property |
Sets a new value for property stepMode.
Defines the calculation mode for the provided step
and largerStep
.
If the user increases/decreases the value by largerStep
, this calculation will consider it as well. For example, if the current value
is 3, step
is 5, largerStep
is 5 and the user chooses PageUp, the calculation logic will consider the value of 3x5=15 to decide what will be the next value
.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is AdditionAndSubtraction
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sStepMode | sap.m.StepInputStepModeType | AdditionAndSubtraction |
New value for property |
Sets a new value for property textAlign.
Defines the horizontal alignment of the text that is displayed inside the input field.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is End
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sTextAlign | sap.ui.core.TextAlign | End |
New value for property |
Sets a new value for property value.
Determines the value of the StepInput
and can be set initially from the app developer.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is 0
.
Param | Type | DefaultValue | Description |
---|---|---|---|
fValue | float | 0 |
New value for property |
Sets a new value for property valueState.
Accepts the core enumeration ValueState.type that supports None
, Error
, Warning
and Success
. ValueState is managed internally only when validation is triggered by user interaction.
When called with a value of null
or undefined
, the default value of the property will be restored.
Default value is None
.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValueState | sap.ui.core.ValueState | None |
New value for property |
Sets a new value for property valueStateText.
Defines the text that appears in the value state message pop-up.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sValueStateText | string |
New value for property |
Sets a new value for property width.
Defines the width of the control.
When called with a value of null
or undefined
, the default value of the property will be restored.
Param | Type | DefaultValue | Description |
---|---|---|---|
sWidth | sap.ui.core.CSSSize |
New value for property |