Linear Progress Indicator¶
The linear progress indicator is a UI component that visually represents the progress of an event or operation. It can also provide success or failure status using an associated text message and distinctive icons. There are four states that FioriProgressIndicator can be in. Success state, error state, indeterminate state, and default state.
Using the Linear Progress Indicator¶
The linear progress indicator is a composable function. The basic usage is as follows:
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state)
```
This displays a visual representation of the slider UI on the screen. Interaction with the linear progress indicator consists of setting or getting its progress value, setting the message text, or changing its state to success, error, or the default state.
Use the `FioriProgressIndicatorState` object to interact with the linear progress indicator, as follows:
```kotlin
state.messageText = "Hello"
state.errorState = true
state.successState = true
state.progress = .5f
The first line sets the message to "Hello" by setting the state associated with the progress bar. The next two lines enable errorState and successState, respectively. Note that the error and success states are mutually exclusive, meaning that setting state.successState to true sets state.errorState to false. By default, these states are false.
Progress is set by providing a value between 0 and 1 with 0 representing zero percent and 1 representing 100 percent. Here, the value is set to .5 (50%).
The possible state values are shown below. Note that only one state can be true at any given time. Setting any of the states to true automatically sets the previous state to false.
| State Setting | Indeterminate | Default | Success | Error |
|---|---|---|---|---|
| Indeterminate state is set | true | false | false | false |
| Default state is set | false | true | false | false |
successState = true |
false | false | true | false |
errorState = true |
false | false | false | true |
Defining FioriLinearProgressIndicator¶
FioriLinearProgressIndicator is defined as follows:
@Composable
fun FioriLinearProgressIndicator(
modifier: Modifier = Modifier,
messageText : String? = null,
colors : FioriLinearProgressIndicatorColors = FioriLinearProgressIndicatorDefaults.colors(),
dimens : FioriLinearProgressIndicatorDimens = FioriLinearProgressIndicatorDefaults.dimens(),
icons : FioriLinearProgressIndicatorIcons = FioriLinearProgressIndicatorDefaults.icons(),
progressIndicatorState: FioriProgressIndicatorState
)
colors - Color for the progress bar. The default color is picked up from FioriLinearProgressIndicatorDefaults.
To override with custom values, use FioriLinearProgressIndicatorDefaults.colors(color = YOURCOLOR, trackColor = YOURCOLOR, successColor= YOURCOLOR,
and errorColor = YOURCOLOR, labelColor= YOURCOLOR.
To set a customized color for success, for example, use the following:
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
colors = FioriLinearProgressIndicatorDefaults.colors(successColor = Color.Green)
)
dimens : Dimensions for the progress bar. The default dimensions are picked up from FioriLinearProgressIndicatorDefaults. To override the default with custom values, use FioriLinearProgressIndicatorDefaults.dimens(trackWidth = value, trackCornerRadius = value, textWidthPercentageTablet = value, and textWidthPercentagePhone = value.
var indicatorState: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(
messageText = message,
dimens = FioriLinearProgressIndicatorDefaults.dimens(trackWidth = trackWidth, trackMinWidth = minTrackWidth) ,
progressIndicatorState = indicatorState
)
By default, the minimum width of the progress bar is 240 dp and maximum width is 600 dp. To use a dimension below 240 or above 600, you can modify the limit using the following API:
var state : FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
dimens = FioriLinearProgressIndicatorDimens(trackWidth = 199.dp, trackMinWidth = 213.dp, trackMaxWidth = 723)
)
icons : Icons for the progress bar. The default icons are picked up from FioriLinearProgressIndicatorDefaults. To override with custom icons, use FioriLinearProgressIndicatorDefaults.icons(iconSuccess = youricon and/or iconError = youricon.
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
icons = FioriLinearProgressIndicatorDefaults.icons(
iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone),
)
)
progressIndicatorState: Reference to the progressIndicatorState object to dynamically update progress indicator behavior.
Updating Progress Indicator Values¶
FioriProgressIndicator has progress values ranging from 0 to 1. 0 represents zero percent and 1 represents 100 percent.
There are four states that FioriProgressIndicator can be in. Success state, error state, indeterminate state, and default state.
success state: In this state, the FioriLinearProgressIndicator will have a success color for the progress bar and a success message. A success icon is also displayed at the left side of the message. You can customize the color and icon for the success state.
You can customize the success color and icon as shown below.
To change to success state, assign the state value to ProgressIndicatorState:
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
icons = FioriLinearProgressIndicatorDefaults.icons(
iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone),
),
colors = FioriLinearProgressIndicatorDefaults.colors(successColor = Color.Green)
)
state.state = FioriProgressIndicatorState.PROGRESS_STATE.STATE_SUCCESS
error state In this state, the FioriLinearProgressIndicator will be displayed with the error color and error icon.
You can customize the error color and icon as follows:
```kotlin var state: FioriProgressIndicatorState = FioriProgressIndicatorState() FioriLinearProgressIndicator(progressIndicatorState = state, icons = FioriLinearProgressIndicatorDefaults.icons( iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone), ), colors = FioriLinearProgressIndicatorDefaults.colors(errorColor = Color.Cyan) ) state.state = FioriProgressIndicatorState.PROGRESS_STATE.STATE_ERROR
`indeterminate state:` In this state, the `FioriProgressIndicator` track will loop around indicating that there is no specific value for progress at this time.
To put a progress indicator into indeterminate state, use the following:
```kotlin
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
icons = FioriLinearProgressIndicatorDefaults.icons(
iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone),
),
colors = FioriLinearProgressIndicatorDefaults.colors(errorColor = Color.Cyan)
)
state.state = FioriProgressIndicatorState.PROGRESS_STATE.STATE_INDETERMINATE
indeterminate state: If the linear progress indicator is in any of the above states it is in indeterminate state.
Note that the four states are mutually exclusive.
message text: You can modify the message text of the progress bar using the state reference as follows:
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriLinearProgressIndicator(progressIndicatorState = state,
icons = FioriLinearProgressIndicatorDefaults.icons(
iconError = FioriIcon(R.drawable.common_full_open_on_phone),
),
colors = FioriLinearProgressIndicatorDefaults.colors(successColor = Color.Cyan)
)
state.messageText = "Hello"
progress value: The progress value (as a percentage), indicating how far the indicator has progressed with respect to the entire track. To set the progress to 15%, for example, use the following:
```kotlin var state: FioriProgressIndicatorState = FioriProgressIndicatorState() FioriLinearProgressIndicator(progressIndicatorState = state) state.progress = .15f