Donut is an Android library which helps you to easily create beautiful doughnut-like charts.

Futured

Last update: Jan 3, 2023

Related tags

Overview

Donut

Donut is an Android library which helps you to easily create beautiful doughnut-like charts.

Installation

module/build.gradle:

dependencies {
    implementation("app.futured.donut:donut:$version")

    // If you want to use Jetpack Compose version then use only this one dependency
    implementation("app.futured.donut:donut-compose:$version")
}

Features

DonutProgressView is a configurable doughnut-like chart view capable of displaying multiple sections with assignable colors. It supports animations and features a gap at the top, which makes it look like a gauge (or tasty bitten-off donut - that's why the name).

The view automatically scales it's sections proportionally to their values once it gets filled up. This allows you to show your users their daily progresses, reached goals, etc.

Usage

Place the view in your layout

<app.futured.donut.DonutProgressView
    android:id="@+id/donut_view"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    app:donut_bgLineColor="@color/cloud"
    app:donut_gapWidth="20"
    app:donut_gapAngle="270"
    app:donut_strokeWidth="16dp"/>

Submit data to the view

val section1 = DonutSection(
    name = "section_1",
    color = Color.parseColor("#FB1D32"),
    amount = 1f
)

val section2 = DonutSection(
    name = "section_2",
    color = Color.parseColor("#FFB98E"),
    amount = 1f
)

donut_view.cap = 5f
donut_view.submitData(listOf(section1, section2))

You'll get something like this:

About the data cap

Once the sum of all section values exceeds view's cap property, the view starts to scale it's sections proportionally to their amounts along it's length. E.g. if we, in the upper example, set cap to donut_view.cap = 1f (section1.amount + section2.amount > 1f), we would get something like this:

Submitting data

The view accepts list of DonutSection objects that define data to be displayed. Each DonutSection object holds section's unique name (string), it's color (color int) and section's value. (Note: the view uses unique name for each section to resolve it's internal state and animations, and throws IllegalStateException if multiple sections with same name are submitted.)

val waterAmount = DonutSection(
    name = "drink_amount_water",
    color = Color.parseColor("#03BFFA"),
    amount = 1.2f
)

You have to submit new list of sections everytime you want to modify displayed data, as DonutSection object is immutable.

donut_view.submitData(listOf(waterAmount))

Granular controls

The view also provides methods for more granular control over displayed data. You can use addAmount, setAmount and removeAmount methods to add, set or remove specified amounts from displayed sections.

Adding amount

donut_view.addAmount(
    sectionName = "drink_amount_water",
    amount = 0.5f,
    color = Color.parseColor("#03BFFA") // Optional, pass color if you want to create new section
)

The addAmount adds specified amount to section with provided name. What if section does not yet exist? This method has one optional color parameter (default value is null) - when called, and there isn't already displayed any section with provided name and color parameter was specified, the new DonutSection with provided name, amount and color will be automatically created internally for you. If you leave the color param null while trying to add value to non-existent section, nothing happens.

Setting amount

donut_view.setAmount(
    sectionName = "drink_amount_water",
    amount = 2.5f
)

The setAmount methods sets specified amount to section with provided name. If provided amount is equal or less than 0, section and corresponding progress line are automatically removed after animation. If view does not contain specified section, nothing happens.

Removing amount

donut_view.removeAmount(
    sectionName = "drink_amount_water",
    amount = 0.1f
)

The removeAmount simply subtracts specified amount from any displayed section. If resulting amount is equal or less than 0, section and corresponding progress line are automatically removed after animation. If view does not contain specified section, nothing happens.

Get and clear data

If you want to get currently displayed data, call getData() method which returns immutable list of all displayed DonutSection objects. To clear displayed data, call clear() method.

Each call to a data method (submit, add, set, remove, clear) results in view automatically resolving and animating to the new state.

Customization

The view allows you to configure various properties to let you create a unique style that fits your needs. They can be changed either via XML attributes, or at runtime via property access.

XML attributes

Name	Default value	Description
`donut_cap`	`1.0f`	View's cap property
`donut_strokeWidth`	`12dp`	Width of background and section lines in dp
`donut_strokeCap`	`round`	The paint cap used for all lines. Can be either 'round' or 'butt'
`donut_bgLineColor`	`#e7e8e9`	Color of background line
`donut_gapWidth`	`45°`	Width of the line gap in degrees
`donut_gapAngle`	`90°`	Position of the line gap around the view in degrees
`donut_direction`	`clockwise`	Progress lines direction (`clockwise` or `anticlockwise`)
`donut_animateChanges`	`true`	Animation enabled flag, if `true`, the view will animate it's state changes (enabled by default)
`donut_animationInterpolator`	`DecelerateInterpolator`	Interpolator to be used in state change animations
`donut_animationDuration`	`1000 ms`	Duration of state change animations in ms

In addition to these XML attributes, the view features masterProgress property (0f to 1f) that can be changed programatically. It controls percentual progress of all lines, including the background line, which allows you to get creative with startup animations, etc.

Jetpack Compose version

This library is implemented as a standalone module also for Jetpack Compose. It has (almost) the same features as the original implementation, but it supports a wider variety of animations.

@Composable
fun Sample() {
    DonutProgress(
        model = DonutModel(
            cap = 8f,
            masterProgress = 1f,
            gapWidthDegrees = 270f,
            gapAngleDegrees = 90f,
            strokeWidth = 40f,
            backgroundLineColor = Color.LightGray,
            sections = listOf(
                DonutSection(amount = 1f, color = Color.Cyan),
                DonutSection(amount = 1f, color = Color.Red),
                DonutSection(amount = 1f, color = Color.Green),
                DonutSection(amount = 0f, color = Color.Blue)
            )
        ),
        config = DonutConfig(
            gapAngleAnimationSpec = spring()
            // ...
        )
    )
}

Sample app

The quickest way to explore different styles is to try the sample app, which contains an interactive playground with buttons and sliders to fiddle with.

Contributors

Current maintainer and main contributor for the original version is Matej Semančík and for Jetpack Compose version is Martin Sumera

Licence

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

Comments

Colors in compose version not being rendered correctly
Hi,

I am facing an issue and after hours of playground testing I can't tell if I am missing something or if the behaviour between the compose and non-compose version is indeed different. I can't tell if this is a bug or not.

Please refer to the following gist: https://gist.github.com/Stjin/807c430a25adebef76fae8a039cbc2b5

I have created an application with 2 activities

1 compose activity

1 native/xml activity

I implemented both the compose as well as the non-compose version of the donut library and recreated 2 identical setups. However the end results is differently rendered. It looks like the compose version reverses the colors?

Compose XML

Hope you can help me out ☺
opened by Stjin 7
Question: Any way to find midpoint of a section?

First off all, thank you for this fantastic library and all the time and effort that you have put into it!

I've been looking into the possibility of adding optional drawables to each section, and specifically I've been trying for a while now to figure out a good way to find the midpoint coordinates of each painted section for the placement of the drawables but have been unable to find a reliable way to do so.

You wouldn't happen to have any pointers on how best to go about doing so?

opened by hrafnthor 4
Ques: GapWidth between sections

Thanks for this amazing library. Is it possible to control gap width between each section?

Currently the gap is for the overall chart I believe. Is there any way I can add that gap in between sections?

Something like this

opened by kdani41 4
Use the library with minSdkVersion 19

I want to use this library, but my app has minSdkVersion 19. I force it using below code. What's the thing will be broken? or are there an alternative way to use this library in app that has minSdkVersion 19? <uses-sdk android:minSdkVersion="19" tools:overrideLibrary="app.futured.donut" />

opened by eldon97 4
Animations
library module

Allow to configure:

enable / disable animation flag

animation duration

animation interpolator

Moved defaults to companion object.

sample module

Added animation controls:

enable switch

duration seeker

interpolator chooser
opened by matejsemancik 3
fix: Remove reversing of the sections in compose version

@matejsemancik this is fix for the following issue https://github.com/futuredapp/donut/issues/83 since colors are separated from the data and data are reversed, there is a bug that was causing the colors were not assigned to the correct values. It is clearly a bug, but it is going to reverse colors for everybody who is going to update the library. Do you think that we should proceed with this change and add a comment to the changelog or fix the issue somehow differently?

opened by SumeraMartin 2

AS 4.0 stable release cannot build this project.

It shows

Unsupported method: AndroidArtifact.getBuildConfigFields().
The version of Gradle you connect to does not support that method.
To resolve the problem you can change/upgrade the target version of Gradle you connect to.
Alternatively, you can ignore this exception and read other information from the model.

opened by SwiftyWang 2

Donut Depency causes the App not to build
Hello! I'm a newbie when it comes to Android Studio and how it fully works, sorry if this is my fault! Any feedback or help would be appreciated if so.

When trying to install the dependency like explained on the README, I get around 7 failures. What I did was add the "Implementation" line inside the "dependencies" area (build.grade (Module)) and do a simple build to test if things would run without problems. I only added that line, nothing more.

FAILURE: Build completed with 7 failures. 1: Task failed with an exception. ----------- * What went wrong: Execution failed for task ':app:checkDebugAarMetadata'. > Could not resolve all files for configuration ':app:debugRuntimeClasspath'. > Could not find app.futured.donut:donut:unspecified. Searched in the following locations: - https://dl.google.com/dl/android/maven2/app/futured/donut/donut/unspecified/donut-unspecified.pom - https://repo.maven.apache.org/maven2/app/futured/donut/donut/unspecified/donut-unspecified.pom Required by: project :app

For simplification purposes, I'll only post this one failure since the others are very similar to this one.

Thank you for the time.
opened by Young-Owl 1
Not Support Compose androidx.compose

my app use androidx.compose version 1.0.4 it can not use donut library because donut library require androidx.ui

please update change androidx.ui to androidx.compose

Thanks for this amazing library.

opened by yotheone0909 1
Segmented progress bar

Would be pretty awesome if we can set the number of segments of the bar.

https://hiinteractive.outsystemscloud.com/HiComponentsGifs/img/HiComponentsGifs.HiArcGraph.gif
Type: Enhancement

opened by Paget96 2
Rendering issues

Hi I want to create segmented donut stepper, I was able to configure it according to my needs but the The donut rendering has un-needed artifacts in transparent sections. See the screen shot below

opened by build3r 2
Dataset Click listener not available.

I am currently using v2.2.2 of this library and there is no click listener to detect which dataset was clicked. do I have to use a new version or what?
Type: Enhancement

opened by Afaqrehman98 2
Gradient support for each progress line

Is it possible to add gradients to each line? e.g. first section should start with a color and end with another color, and section 2 takes a set of other colors, etc.
Type: Enhancement

opened by sak6464 2
Create PUBLISHING.md

After the library migrates to mavenCentral, we might need to create some sort of publishing guide, as the library properties are needed to be changed in gradle.properties file before each release.
Type: Enhancement

opened by matejsemancik 0

Releases(2.2.2)

2.2.2(Apr 17, 2022)
Bugfixes:

Fix for a bug that was causing colors not being correctly assigned to their corresponding values.

Source code(tar.gz)
Source code(zip)
2.2.1(Mar 3, 2022)
Compose version

Bump Compose to 1.1.1

Bump Kotlin to 1.6.10

Source code(tar.gz)
Source code(zip)
2.2.0(Oct 26, 2021)
Bump Compose from beta to stable 1.0.4 and Kotlin to 1.5.31

Source code(tar.gz)
Source code(zip)
2.1.0(Dec 14, 2020)
Allow zero-amount donut sections

Lower library minSdk from 21 to 19

Add direction feature

Add stroke cap feature

Source code(tar.gz)
Source code(zip)
2.0.0(May 20, 2020)
Added Jetpack Compose version of the library

Small refactor of data structures from the library module

Source code(tar.gz)
Source code(zip)
1.0.0(Dec 20, 2019)

First release of Donut library.
Source code(tar.gz)
Source code(zip)