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

Overview

Donut

Download Build Status Android Arsenal Android Weekly License Jetpack Compose

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).

Header

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:

View with cap unexceeded

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:

View with cap exceeded

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.

Playground

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

    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 Compose Native XML



    Hope you can help me out ☺

    opened by Stjin 7
  • Question: Any way to find midpoint of a section?

    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

    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 image

    opened by kdani41 4
  • Use the library with minSdkVersion 19

    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

    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

    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.

    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

    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

    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

    Segmented progress bar

    opened by Paget96 2
  • Rendering issues

    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

    image

    opened by build3r 2
  • Dataset Click listener not available.

    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

    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

    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)
Owner
Futured
We are the mobile business builders
Futured
AnyChart Android Chart is an amazing data visualization library for easily creating interactive charts in Android apps. It runs on API 19+ (Android 4.4) and features dozens of built-in chart types.

AnyChart for Android AnyChart Android Charts is an amazing data visualization library for easily creating interactive charts in Android apps. It runs

AnyChart 2k Nov 18, 2022
Android Library to rapidly develop attractive and insightful charts in android applications.

williamchart Williamchart is an Android Library to rapidly implement attractive and insightful charts in android applications. Note: WilliamChart v3 h

Diogo Bernardino 4.9k Nov 29, 2022
Android Library to rapidly develop attractive and insightful charts in android applications.

williamchart Williamchart is an Android Library to rapidly implement attractive and insightful charts in android applications. Note: WilliamChart v3 h

Diogo Bernardino 4.8k Dec 22, 2021
Charts/graphs library for Android compatible with API 8+, several chart types with support for scaling, scrolling and animations

HelloCharts for Android Charting library for Android compatible with API 8+(Android 2.2). Works best when hardware acceleration is available, so API 1

Leszek Wach 7.3k Nov 23, 2022
A powerful 🚀 Android chart view / graph view library, supporting line- bar- pie- radar- bubble- and candlestick charts as well as scaling, panning and animations.

⚡ A powerful & easy to use chart library for Android ⚡ Charts is the iOS version of this library Table of Contents Quick Start Gradle Maven Documentat

Philipp Jahoda 35.8k Nov 28, 2022
An easy-to-use Android charts library with animation.

AndroidCharts A simple Android charts library. Known Uses in Pomotodo Including in Your Project Eclipse Import /AndroidCharts folder. Move /java folde

HackPlan 1.3k Nov 11, 2022
YBKChart is a library of 3D graphics charts for Android. 📊

YBKChart is a library of 3D graphics charts for Android. ?? For more information, see the Wiki. Chart List Pie Chart Download Use gradle. rep

ByungKwan Yun 10 Jun 19, 2022
Library for charts in android with animations

Charts Gradle Setup Step 1. Add the JitPack repository to your build file Add it in your root build.gradle at the end of repositories: allprojects {

Ayush Saini 3 Oct 5, 2021
An android compose library with different Graphs and Charts

plot An android compose library with different Graphs and Charts (currently supports only Line graph, more types will be added soon) Download reposito

Madrapps 101 Nov 23, 2022
Straiberry Charts - An awesome Chart library for android

Straiberry Charts An awesome Chart library for android Straiberry · Report Bug · Request Feature Getting Started Adding dependecies Add it in your roo

StrAIberry 28 Oct 24, 2022
An open source library used to draw charts in Android with Jetpack Compose with a simple and easy to use

android-compose-charts This is an open source library used to draw charts in Android with Jetpack Compose with a simple and easy to use. Just couples

Mahmoud Ibrahim 16 Sep 23, 2022
Simple Jetpack Compose Charts for multi-platform. Including Android, Web, Desktop.

compose-charts Simple Jetpack Compose Charts for multi-platform. Including Android, Web, Desktop. Graph Effects How to use? 1, show Pie Chart in Jetpa

Chen Pan 107 Nov 6, 2022
Simple Compose Charts for multi-platform. Including Android, Web, Desktop.

compose-charts-desktop Simple Compose Charts for multi-platform. Including Android, Web, Desktop. Compose multiplatform for Android: compose-charts. G

Chen Pan 11 Nov 4, 2022
Arc Chart View (Draw Creative Statistic Arc Charts)

ArcChartViewDemo You can use this library to draw Arc charts and show your statistics or anything you want or maybe get some ratings from user. you ca

Iman khoshabi 106 Nov 22, 2022
TChart - Simple and fast charts.

TChart - Simple and fast charts.

null 30 Sep 20, 2022
Android Tableau library supports variety of graphs which developers simply integrate visualization reports on Android application.

Android Tableau Library Android Tableau library supports variety of graphs which developers simply integrate visualization reports on Android applicat

Sung Hyun 53 Jul 6, 2022
BubbleTabBar is bottom navigation bar with customizable bubble like tabs

BubbleTabBar BubbleTabBar is bottom navigation bar with customizable bubble like tabs Download AIX : Download Aix License Licensed under the Apache Li

Zain Ul Hassan 6 Aug 7, 2022