Step Progress Indicator

The step progress indicator provides a way to visually represent sequences of steps and their statuses. Users can interact with it to find details on each step and change state statuses. The step progress indicator is customizable for any kind of user-defined step data. Custom UI content can be incorporated into the step progress representation.

Basic Usage of Step Progress Indicator

/**
* Define any kind of data as shown below by defining `Process`:
*/

private data class Process( val title:String,
    val description:String,
    val importance: String
)

/**
* Initialize `list` as a 'StepList' type:
*/

private val list = StepList()

/**
* Add step node data
*/

 list.addNodeData(
        StepsNodeData(
            "Step 1", stepStates = StepProgressNode.StepStates.DEFAULT,
            data = Process(
                "Step 1",
                "Step 1: Content will display here",
                "high"
            )
        )
    )
    list.addNodeData(
        StepsNodeData(
            "Step 2  Let's make this line a little bigger so it won't fit in one line", stepStates = StepProgressNode.StepStates.ACTIVE,
            data = Process(
                "Step 2",
                "Step 2: Content will display here",
                "high"
            )
        )
    )
    list.addNodeData(
        StepsNodeData(
            "Step 3", stepStates = StepProgressNode.StepStates.ERROR,
            data = Process(
                "Step 3",
                "Step 3: Content will display here",
                "high"
            )
        )
    )
    list.addNodeData(
        StepsNodeData(
            "Step 4", stepStates = StepProgressNode.StepStates.ERROR_ACTIVE,
            data = Process(
                "Step 4",
                "Step 4: Content will display here",
                "high"
            )
        )
    )
    list.addNodeData(
        StepsNodeData(
            "Step 5", stepStates = StepProgressNode.StepStates.COMPLETE,
            data = Process(
                "Step 5",
                "Step 5: Content will display here",
                "high"
            )
        )
    )

/**
* Call the composable
*/

StepperProgress(stepList = data)

This will display the progress indicator, as shown below.

Adding Custom UI Attached to the Step Progress

To add the user content to the step progress indicator, do the following:

StepperProgress(stepList = list){
    Text("Here is the user content")
}

Adding the content this way will give you more control over interacting with the data changes dynamically. For example, to observe a change in the data, a user can enclose an ObserveDataChange block as shown below:

StepperProgress(stepList = list){
    Text("Here is the user content")
    data.ObserveDataChange {
        val dataItem = (list.getCurrentData().data as Process)
        Text(
            modifier = Modifier.testTag("TITLE"),
            text = dataItem.title,
            color = MaterialTheme.fioriHorizonAttributes.SapFioriColorLightGrayInactiveIcon,
            style = MaterialTheme.fioriHorizonAttributes.textAppearanceTitleLarge
        )
        Text(" ")
        Text(dataItem.description)
        Text(" ")
    }
}

The ObserveDataChange causes the containing block to be recomposed whenever the data changes are signaled using the updatData call.

Detailed Usage of Step Progress Indicator

@Composable
public fun StepperProgress(
    stepList: StepList,
    modifier: Modifier = Modifier,
    colors: StepProgressColors = StepProgressDefaults.colors(),
    fonts: StepProgressFonts = StepProgressDefaults.fonts(),
    direction: StepProgressNode.NodeDirection = StepProgressNode.NodeDirection.HORIZONTAL,
    onNodeClick: (index: Int) -> Unit = fun (index: Int){  
        stepList.currentDataItem = index
        stepList.updateList()},
    leftHeaderText: CharSequence? = null,
    rightButtonText: CharSequence? = null,
    onRightButtonClick: (() -> Unit)? = null,
    details: @Composable() (() -> Unit)? = null
): Unit

Composable for Step Progress UI element.

Parameters

• stepList - This parameter represents the type of StepList representing the StepProgress.
• modifier - Modifier specification, if not default.
• colors - StepProgressColors (with default values). Users can specify custom colors and the use of these colors can also be customized.
• fonts - StepProgressFonts values (with default values). Users can specify custom fonts and the use of these fonts can also be customized.
• direction - Orientation of the Step Progress Indicator: Vertical or Horizontal StepProgress.NodeDirection
• onNodeClick - Event handler for node click.
• leftHeaderText - Text for the left side of the header. This is used only for StepProgress.
• rightButtonText - The right button text for the ButtonText on the header.
• onRightButtonClick - Event handler to modify the right button click.
• details - Composable content to be displayed along with the step progress indicator.

Step Node Data

Each step in step progress is managed by a StepsNodeData object. The constructor takes the following arguments:

• stepName: a 'CharSequence' that provides a text name for the step.
• stepStates: value of the step states of the type StepProgressNode.StepStates.
• stepType: value of the step type StepProgressNode.StepType.
• data: any data reference can be used here. By default it is null.

/**
* In this example the `Process` is `Any` type that can go to the data reference.
**/
StepsNodeData(
    "Step 1", stepStates = StepProgressNode.StepStates.DEFAULT,
        data = Process(
            "Step 1",
            "Step 1: Content will display here",
            "high"
        )
)

Step List

The step list manages the list of step node data for the step progress indicator. This is passed as one of the arguments. This also manages recomposition using the ObserveDataChange construct.

A step list can be initialized with a simple constructor, as shown below:

val list = StepList()

Adding Step Node to StepList

The following code illustrates how to add a node to the step list.

/**
* Create an empty step data
**/
 val list = StepList()
 /**
 * Add a datum to the list
 */
 list.addNodeData(
        StepsNodeData(
            "Step 9", stepStates = StepProgressNode.StepStates.DEFAULT,
            data = Process(
                "Step 9",
                "Step 9: Content will display here",
                "high"
            )
        )
    )

ObserveDataChange Block

If a dataList value of type StepList is used to create StepProgress, the ObserveDataChange enclosure of the data can be used to monitor and cause recomposition of its compose elements. The recomposition process is as per the Google specification.

Here is an example of how to use this:

list.ObserveDataChange {
    val dataItem = (list.getCurrentData().data as Process)
    Text(
        modifier = Modifier.testTag("TITLE"),
        text = dataItem.title,
        color = MaterialTheme.fioriHorizonAttributes.SapFioriColorLightGrayInactiveIcon,
        style = MaterialTheme.fioriHorizonAttributes.textAppearanceTitleLarge
    )
    Text(" ")
    Text(dataItem.description)
    Text(" ")
}

Updating Data

When any modification is done to the data, a call to updateList will ensure that the block under the ObserveDataChange is recomposed.

Scrolling to Specific Data Item

The function scrollToDataItem(index : Int) scrolls to the data item provided by the index. In the following example, the step progress indicator scrolls to the 17th element in the list.

list.scrollToDataItem(17)

isDataVisible

isDataVisible(index: Int):Boolean This returns true if the data item index is visible in the view port.

list.isDataVisible(7)

---

Last update: February 29, 2024