Skip to content

A feature rich staged progress bar with modifiable steps in between its stages.

License

Notifications You must be signed in to change notification settings

loukwn/StageStepBar

Repository files navigation

StageStepBar

License Jetpack Compose As Seen In - jetc.dev Newsletter Issue #106

A staged progressbar that you can use if you want finer control of the steps in between its stages. You can customize:

  • Number of steps between particular stages
  • Look and feel of tracks and thumbs (stages)
  • Direction and Orientation of the bar
  • Animation speed (or even type in Compose)

Showcase

Best way to test how this library is configured is to check out:

  • example module if you are interested in the View library.
  • example-compose module if you are interested in the Compose library.

Installation

Add Jitpack distribution to the end of the repositories in your root build.gradle file.

allprojects {
    repositories {
        //...
        maven { url 'https://jitpack.io' }
    }
}

Add the relevant dependency to the list of dependencies in your module's build.gradle file

dependencies {
    // Add only this one if you want to include the View version
    implementation 'com.github.loukwn.StageStepBar:stagestepbar:<latest-version>'

    // Add only this one if you want to include the Compose version
    implementation 'com.github.loukwn.StageStepBar:stagestepbar-compose:<latest-version>'
}

Usage

Usage as a View

In XML:

<com.loukwn.stagestepbar.StageStepBar
    android:id="@+id/stageStepBar"
    android:layout_width="200dp"
    android:layout_height="100dp"
    app:ssb_stageStepConfig="5,5,5"
    app:ssb_animationDuration="500"
    /*...*/
     />

In Code:

val stageStepBar = findViewById<StageStepBar>(R.id.stageStepBar)
stageStepBar.setStageStepConfig(listOf(6,2,7))

Configuration

All XML attributes are optional (set to their defaults).

XML attribute Default Description
ssb_stageStepConfig "1" This is a list in a string form that describes the steps per stages. For example a value of 6,4,3 means 6 steps from stage 0 to 1, 4 from stage 1 to 2 and 3 steps from stage 2 to 3.

In code: setStageStepConfig(List<Int>)
ssb_currentState null This is a list in a string form that describes the current state. For example a value of 2,4 means go to stage 2, step 4. Both the stage and the step provided here are coerced to the largest possible value (according to stageStepConfig). A null value here means that nothing is filled.

In code: setCurrentState(State?)
ssb_animate true Whether or not the progress change will animate.

In code: setAnimate(Boolean)
ssb_animationDuration 500 The duration of the animation

In code: setAnimationDuration(Long)
ssb_orientation horizontal Whether the bar is horizontal or vertical.

In code: setOrientation(Orientation)
ssb_horizontalDirection auto The direction of the bar if it is horizontal. Possible values: auto (based on locale). ltr, rtl.

In code: setHorizontalDirection(HorizontalDirection)
ssb_verticalDirection btt The direction of the bar if it is vertical. Possible values: ttb (Top to Bottom). btt, (Bottom to Top).

In code: setVerticalDirection(VerticalDirection)
ssb_filledTrackColor #000000 The color of the track when it is filled.

In code: setFilledTrackToNormalShape(@ColorInt Int)
ssb_unfilledTrackColor #A9A9A9 The color of the track when it is not filled.

In code: setUnfilledTrackToNormalShape(@ColorInt Int)
ssb_activeThumbColor - The color of the last filled thumb.

In code: setActiveThumbToNormalShape(@ColorInt Int)
ssb_filledThumbColor #000000 The color of the thumbs when they are filled.

In code: setFilledThumbToNormalShape(@ColorInt Int)
ssb_unfilledThumbColor #6F6F6F The color of the thumbs when they are not filled.

In code: setUnfilledThumbToNormalShape(@ColorInt Int)
ssb_filledTrackDrawable - Sets a custom drawable to the filled track.

In code: setFilledTrackToCustomDrawable(Drawable, Float)
ssb_filledTrackDrawableAlpha 1f Sets the alpha of the custom filled track drawable.

In code: setFilledTrackToCustomDrawable(Drawable, Float)
ssb_unfilledTrackDrawable - Sets a custom drawable to the unfilled track.

In code: setUnfilledTrackToCustomDrawable(Drawable, Float)
ssb_unfilledTrackDrawableAlpha 1f Sets the alpha of the custom unfilled track drawable.

In code: setUnfilledTrackToCustomDrawable(Drawable, Float)
ssb_activeThumbDrawable - Sets a custom drawable to the last filled thumb.

In code: setActiveThumbToCustomDrawable(Drawable, Float)
ssb_activeThumbDrawableAlpha 1f Sets the alpha of the last custom filled thumb drawable.

In code: setActiveThumbToCustomDrawable(Drawable, Float)
ssb_filledThumbDrawable - Sets a custom drawable to the filled thumbs.

In code: setFilledThumbToCustomDrawable(Drawable, Float)
ssb_filledThumbDrawableAlpha 1f Sets the alpha of the custom filled thumbs drawables.

In code: setFilledThumbToCustomDrawable(Drawable, Float)
ssb_unfilledThumbDrawable - Sets a custom drawable to the unfilled thumbs.

In code: setUnfilledThumbToCustomDrawable(Drawable, Float)
ssb_unfilledThumbDrawableAlpha 1f Sets the alpha of the custom unfilled thumbs drawables.

In code: setUnfilledThumbToCustomDrawable(Drawable, Float)
ssb_thumbSize 20dp The size of the thumbs (both filled and unfilled).

In code: setThumbSize(Int) Value is expected to be in pixels.
ssb_crossAxisFilledTrackSize 6dp The height of the filled track if the bar is horizontal or its width if it is vertical.

In code: setCrossAxisFilledTrackSize(Int) Value is expected to be in pixels.
ssb_crossAxisUnfilledTrackSize 6dp The height of the unfilled track if the bar is horizontal or its width if it is vertical.

In code: setCrossAxisUnfilledTrackSize(Int) Value is expected to be in pixels.
ssb_showThumbs true Whether or not to show the thumbs.

In code: setThumbsVisible(Boolean)
ssb_drawTracksBehindThumbs true This option addresses the cases where we might not want to see the track behind the thumb (e.g semi transparent thumb).

In code: setDrawTracksBehindThumbs(Boolean)

Note: Both thumbs and tracks can either have:

  • A default shape but with the color specified by the user. Calling a set*ToNormalShape() function takes you to this state.
  • Their entire look overriden by a custom Drawable. Calling a set*ToCustomDrawable() function takes you to this state.

Usage as a Composable

@Composable
fun Example() {
    StageStepBar(
        modifier = Modifier, //...
        config = StageStepBarConfig(
            stageStepConfig = listOf(12,45,1)
            //...
        )
    )
}

The full configuration model is pretty much the same between the Compose and the View version. However there are differences (mostly due to things that Compose makes easier):

  • Instead of specifying an Int in pixels for the sizes of thumbs and/or tracks, in the Compose version that is passed in Dp.
  • Instead of just specifying a duration value for the animation, in the Compose version one can pass instead an AnimationSpec<Float> effectively taking advantage of other kinds of animations like spring() etc.
  • Instead of passing a Drawable, in Compose one will need to either pass an ImageBitmap (because of what the Canvas in this case expects) or just a @DrawableRes for convenience. There is also an option to pass a ColorFilter so that things like tinting can be done.

These differences aside, the behavior between the two versions should be pretty much identical.

Licence

StageStepBar is available under MIT license. See LICENSE file for more information.