Circular Progress Indicator¶

The circular 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 FioriCircularProgressIndicator can be in: success state, error state, indeterminate state, and default state.

Using the Circular Progress Indicator¶

The circular progress indicator is a composable function. The basic usage is as follows:

 var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
 FioriCircularProgressIndicator(progressIndicatorState = state)
 ```

This displays a visual representation of the circular indicator UI on the screen. Interaction with the circular 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 circular 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 `FioriCircularProgressIndicator`¶

FioriCircularProgressIndicator is defined as follows:

@Composable
fun  FioriCircularProgressIndicator(
    modifier: Modifier = Modifier,
    messageText  : String? = null,
    colors : FioriCircularProgressIndicatorColors = FioriCircularProgressIndicatorDefaults.colors(),
    dimens : FioriCircularProgressIndicatorDimens = FioriCircularProgressIndicatorDefaults.dimens(),
    icons : FioriCircualrProgressIndicatorIcons = FioriCircularProgressIndicatorDefaults.icons(),
    progressIndicatorState: FioriProgressIndicatorState
)

colors - Color for the progress bar. The default color is picked up from FioriCircularProgressIndicatorDefaults. To override with custom values, use FioriCircularProgressIndicatorDefaults.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()
    FioriCircularProgressIndicator(progressIndicatorState = state,
    colors = FioriCircularProgressIndicatorDefaults.colors(successColor = Color.Green)
)

dimens : Dimensions for the progress bar. The default dimensions are picked up from FioriCircularProgressIndicatorDefaults. To override the default with custom values, use FioriCircularProgressIndicatorDefaults.dimens(trackWidth = value, trackCornerRadius = value, textWidthPercentageTablet = value, and textWidthPercentagePhone = value.

var indicatorState: FioriProgressIndicatorState = FioriProgressIndicatorState()

FioriCircularProgressIndicator(
    messageText = message,
    dimens = FioriCircularProgressIndicatorDefaults.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()

FioriCircularProgressIndicator(progressIndicatorState = state,
        dimens = FioriCircularProgressIndicatorDimens(trackWidth = 199.dp, trackMinWidth = 213.dp, trackMaxWidth = 723)
)

icons : Icons for the progress bar. The default icons are picked up from FioriCircularProgressIndicatorDefaults. To override with custom icons, use FioriCircularProgressIndicatorDefaults.icons(iconSuccess = youricon and/or iconError = youricon.

 var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
    FioriCircularProgressIndicator(progressIndicatorState = state,
    icons = FioriCiercularProgressIndicatorDefaults.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 FioriCircularProgressIndicator 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.

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()
FioriCircularProgressIndicator(progressIndicatorState = state,
    icons = FioriCircularProgressIndicatorDefaults.icons(
        iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone),
    ),
    colors = FioriCircularProgressIndicatorDefaults.colors(successColor = Color.Green)
    )
state.state = FioriProgressIndicatorState.PROGRESS_STATE.STATE_SUCCESS

error state In this state, the FioriCircularProgressIndicator will be displayed with the error color and error icon.

Error State

You can customize the error color and icon as follows:

```kotlin var state: FioriProgressIndicatorState = FioriProgressIndicatorState() FioriCircularProgressIndicator(progressIndicatorState = state, icons = FioriCircularProgressIndicatorDefaults.icons( iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone), ), colors = FioriCircularProgressIndicatorDefaults.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.

![Success State](images/circularprogress-indeterminate.png)

To put a progress indicator into indeterminate state, use the following:

  ```kotlin
var state: FioriProgressIndicatorState = FioriProgressIndicatorState()
FioriCircularProgressIndicator(progressIndicatorState = state,
    icons = FioriCircularProgressIndicatorDefaults.icons(
        iconSuccess = FioriIcon(R.drawable.common_full_open_on_phone),
    ),
    colors = FioriCircularProgressIndicatorDefaults.colors(errorColor = Color.Cyan)
    )
state.state = FioriProgressIndicatorState.PROGRESS_STATE.STATE_INDETERMINATE

indeterminate state: If the circular progress indicator is in any of the above states, it is in the 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()
 FioriCircularProgressIndicator(progressIndicatorState = state,
    icons = FioriCircularProgressIndicatorDefaults.icons(
        iconError = FioriIcon(R.drawable.common_full_open_on_phone),
    ),
    colors = FioriCircularProgressIndicatorDefaults.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() FioriCircularProgressIndicator(progressIndicatorState = state) state.progress = .15f

Last update: June 15, 2023

Circular Progress Indicator¶

Using the Circular Progress Indicator¶

Defining FioriCircularProgressIndicator¶

Updating Progress Indicator Values¶

Defining `FioriCircularProgressIndicator`¶