Circular Progress Image for Jetpack Compose

This android project is a highly customizable circular progress image component for Jetpack Compose. It clips a given image into a sector shape that dynamically changes based on progress, allowing for beautiful and interactive circular progress indicators.

Preview

Features

Custom Shape Clipping: Clips any Painter into a dynamic sector shape.
Full Angle Control: Customize the startAngle and maxSweepAngle to create full circles, semi-circles, or any arc shape you need.
Color Theming: Easily apply tint colors to both the progress and background images.
Stateful Animation: Comes with a state holder (rememberCircularProgressState) for effortless animation control.
Stateless Control: Provides a simple, stateless composable for direct progress manipulation.
Robust & Edge-Case Ready: Smoothly handles all progress values from 0% to 100% without visual glitches.

Setup / Installation

1. Add JitPack Repository

First, add the JitPack repository to your project. This allows Gradle to find and download the library. Choose the file that corresponds to your project's setup style.

Kotlin DSL (settings.gradle.kts) - Recommended for new projects

// settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") } // Add this line
    }
}

Groovy DSL (settings.gradle) - For older projects

// settings.gradle

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' } // Add this line
    }
}

2. Add the Library Dependency

Next, add the library dependency to your module's build.gradle.kts (or build.gradle) file.

Using Version Catalog (Recommended)

Add the library alias to your gradle/libs.versions.toml file.

[versions]
# Use a descriptive name for the version key
circularProgressImage = "1.0.2" # Replace with the latest version

[libraries]
# Use a descriptive name for the library alias
circularProgressImage = { group = "com.github.PARAOOO", name = "CircularProgressImage", version.ref = "circularProgressImage" }

Add the dependency in your module's build.gradle.kts. Gradle automatically handles the alias.
```
dependencies {
    implementation(libs.circularProgressImage)
}
```

Kotlin DSL (build.gradle.kts)

dependencies {
    // Replace "1.0.2" with the latest version from JitPack
    implementation("com.github.PARAOOO:CircularProgressImage:1.0.2")
}

Groovy DSL (build.gradle)

dependencies {
    // Replace "1.0.2" with the latest version from JitPack
    implementation 'com.github.PARAOOO:CircularProgressImage:1.0.2'
}

Usage

Here are some examples demonstrating the capabilities of the library.

Example 1: Static Progress with a Slider

A simple example showing a static progress value controlled by an external Slider.

var progress by remember { mutableFloatStateOf(0.75f) }

CircularProgressImage(
    painter = painterResource(id = R.drawable.your_image),
    progress = progress,
    modifier = Modifier.size(160.dp),
    color = Color.Green,
    backgroundColor = Color.LightGray.copy(alpha = 0.5f)
)

Slider(value = progress, onValueChange = { progress = it })

Example 2: Controlled Animation with Buttons

Use rememberCircularProgressState and AnimatedCircularProgressImage to control animations programmatically.

val progressState = rememberCircularProgressState(initialProgress = 0f)

AnimatedCircularProgressImage(
    state = progressState,
    painter = painterResource(id = R.drawable.your_image),
    modifier = Modifier.size(160.dp),
    color = Color.Blue,
    backgroundColor = Color(0xFFBBDEFB)
)

Row {
    Button(onClick = { progressState.moveTo(0.25f) }) { Text("25%") }
    Button(onClick = { progressState.moveTo(0.75f) }) { Text("75%") }
    Button(onClick = { progressState.moveTo(1.0f) }) { Text("100%") }
}

For more detailed examples, including interactive drag controls and infinite animations, please check out the app module in this repository.

API Reference

This library provides two main composables: a stateless CircularProgressImage for direct control, and a stateful AnimatedCircularProgressImage for easy animations.