Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/codeandtheory/YCharts
YCharts is a graph library for Android.
https://github.com/codeandtheory/YCharts
android androidchart androidcharts androidgraph androidlibrary barchart chart charts composechart donutchart graph graphs groupchart jetpack-compose jetpack-compose-charts kotlin linecharts pie-chart
Last synced: about 2 months ago
JSON representation
YCharts is a graph library for Android.
- Host: GitHub
- URL: https://github.com/codeandtheory/YCharts
- Owner: codeandtheory
- License: apache-2.0
- Created: 2022-07-22T07:06:31.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-07T13:12:59.000Z (7 months ago)
- Last Synced: 2024-08-01T19:50:03.227Z (5 months ago)
- Topics: android, androidchart, androidcharts, androidgraph, androidlibrary, barchart, chart, charts, composechart, donutchart, graph, graphs, groupchart, jetpack-compose, jetpack-compose-charts, kotlin, linecharts, pie-chart
- Language: Kotlin
- Homepage:
- Size: 35.7 MB
- Stars: 570
- Watchers: 11
- Forks: 48
- Open Issues: 36
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- awesome-list - codeandtheory/YCharts - YCharts is a graph library for Android. (Kotlin)
README
# YCharts
YCharts is a Jetpack-compose based charts library which enables developers to easily integrate various types of charts/graphs into their existing ui to visually represent statistical data. YCharts supports both cartesian(XY-charts) and polar charts(Radial charts), which include:
A. Cartesian charts:
1. Line chart
2. Bar chart
3. Wave chart
4. Bubble chart
5. Combined chart
B.Radial charts:
1. Pie chart
2. Donut chart
It comprises two main modules:
- `YChartslib` (Chart components for Jetpack Compose)
- `app` (sample app to showcase chart components)
## Adding YCharts to your project:
You can add the library via Maven:
Gradle:
```groovy
implementation 'co.yml:ycharts:2.1.0'
```
## Modules
The following table outlines the modules included in this library:
| Artifact | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `axis` | Includes the horizontal and vertical axis components along with the math engines. |
| `charts` | Includes the all the chart components i.e: Line, Bar, Combined, Pie & Donut etc. also the math engines |
| `chartcontainer` | Provides the base container to draw any chart inside it with scroll tap feature etc out of the box. |
| `piechart` | Includes all the 360' chart components i.e Pie, Donut charts etc. |
## Sample app
Included in this repository is a [sample app](https://github.com/yml-org/YCharts/tree/main/app) with multiple charts with different styling in each section. Studying the source code of the app will give you a deep understanding of how to use YCharts, including customizing and styling the charts. All of the charts i.e line, bar, groupedBar, pie & donut are implemented in the sample app.
## Examples
Let's see how we can use the chart components and style them with available customization options.
### 1. Line Chart:
- Create list of points with x & y co-ordinates using `Point` data class.
```kotlin
val pointsData: List =
listOf(Point(0f, 40f), Point(1f, 90f), Point(2f, 0f), Point(3f, 60f), Point(4f, 10f))
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(100.dp)
.backgroundColor(Color.Blue)
.steps(pointsData.size - 1)
.labelData { i -> i.toString() }
.labelAndAxisLinePadding(15.dp)
.build()
val yAxisData = AxisData.Builder()
.steps(steps)
.backgroundColor(Color.Red)
.labelAndAxisLinePadding(20.dp)
.labelData { i ->
val yScale = 100 / steps
(i * yScale).formatToSinglePrecision()
}.build()
```
- Initialize the Line chart data with axis and other line related styling using `LineChartData` data class.
```kotlin
val lineChartData = LineChartData(
linePlotData = LinePlotData(
lines = listOf(
Line(
dataPoints = pointsData,
LineStyle(),
IntersectionPoint(),
SelectionHighlightPoint(),
ShadowUnderLine(),
SelectionHighlightPopUp()
)
),
),
xAxisData = xAxisData,
yAxisData = yAxisData,
gridLines = GridLines(),
backgroundColor = Color.White
)
```
- Finally use the _**`LineChart`**_ Component to render the line chart with the above input params.
```kotlin
LineChart(
modifier = Modifier
.fillMaxWidth()
.height(300.dp),
lineChartData = lineChartData
)
```
Line chart looks like this!
Line chart with dots looks like this!
### 2. Bar Chart:
- Create list of barChartData using the random generator extension and `BarData` data class.
```kotlin
val barChartData = DataUtils.getBarChartData(barChartListSize, maxRange)
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(30.dp)
.steps(barChartData.size - 1)
.bottomPadding(40.dp)
.axisLabelAngle(20f)
.labelData { index -> barData[index].label }
.build()
val yAxisData = AxisData.Builder()
.steps(yStepSize)
.labelAndAxisLinePadding(20.dp)
.axisOffset(20.dp)
.labelData { index -> (index * (maxRange / yStepSize)).toString() }
.build()
```
- Initialize the Bar chart data with axis and other line related styling using `BarChartData` data class.
```kotlin
val barChartData = BarChartData(
chartData = barChartData,
xAxisData = xAxisData,
yAxisData = yAxisData,
paddingBetweenBars = 20.dp,
barWidth = 25.dp
)
```
- Last, use the _**`BarChart`**_ Component to render the bar chart with the above input params.
```kotlin
BarChart(modifier = Modifier.height(350.dp), barChartData = barChartData)
```
Bar chart looks like this!
Horizontal Bar chart looks like this!
### 3. Grouped Bar Chart:
- Create list of grouped combinations of bar chart data using the random generator extension and `BarPlotData` data class.
```kotlin
val groupBarPlotData = BarPlotData(
groupBarList = DataUtils.getGroupBarChartData(
barChartListSize,
maxRange,
eachGroupBarSize
),
barColorPaletteList = getColorPaletteList(barSize)
)
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(30.dp)
.steps(groupBarData.size - 1)
.bottomPadding(40.dp)
.labelData { index -> groupBarData[index].label }
.build()
val yAxisData = AxisData.Builder()
.steps(yStepSize)
.labelAndAxisLinePadding(20.dp)
.axisOffset(20.dp)
.labelData { index -> (index * (maxRange / yStepSize)).toString() }
.build()
```
- Initialize the group bar chart data with axis and other line related styling using `GroupBarChartData` data class.
```kotlin
val groupBarChartData = GroupBarChartData(
barPlotData = groupBarPlotData,
xAxisData = xAxisData,
yAxisData = yAxisData
)
```
- Use the _**`GroupBarChart`**_ Component to render the bar chart with the above input params.
```kotlin
GroupBarChart(modifier = Modifier.height(300.dp), groupBarChartData = groupBarChartData)
```
Grouped Bar chart looks like this!
Stacked Bar chart looks like this!
### 4. Pie Chart:
- Create list of slices using the `PieChartData` data class.
```kotlin
val pieChartData = PieChartData(
slices = listOf(
PieChartData.Slice("SciFi", 65f, Color(0xFF333333)),
PieChartData.Slice("Comedy", 35f, Color(0xFF666a86)),
PieChartData.Slice("Drama", 10f, Color(0xFF95B8D1)),
PieChartData.Slice("Romance", 40f, Color(0xFFF53844))
)
)
```
- Initialize the pie chart config with `PieChartConfig` data class in order to achieve styling and configurations related to pie chart.
```kotlin
val pieChartConfig = PieChartConfig(
percentVisible = true,
isAnimationEnable = true,
showSliceLabels = false,
animationDuration = 1500
)
```
- Finally, use the _**`PieChart`**_ component to render the chart.
```kotlin
PieChart(
modifier = Modifier
.width(400.dp)
.height(400.dp),
pieChartData,
pieChartConfig
)
```
Pie chart looks like this!
Pie chart with lables like this!
### 5. Donut Chart:
- Similar to pie chart here we need create list of slices using the `PieChartData` data class.
```kotlin
val donutChartData = PieChartData(
slices = listOf(
PieChartData.Slice("HP", 15f, Color(0xFF5F0A87)),
PieChartData.Slice("Dell", 30f, Color(0xFF20BF55)),
PieChartData.Slice("Lenovo", 40f, Color(0xFFEC9F05)),
PieChartData.Slice("Asus", 10f, Color(0xFFF53844))
)
)
```
- Initialize the pie chart config with `PieChartConfig` data class in order to achieve styling and configurations related to pie chart.
```kotlin
val donutChartConfig = PieChartConfig(
percentVisible = true,
percentageFontSize = 42.sp,
strokeWidth = 120f,
percentColor = Color.Black,
activeSliceAlpha = .9f,
isAnimationEnable = true
)
```
- Finally, use the _**`DonutPieChart`**_ component to render the chart.
```kotlin
DonutPieChart(
modifier = Modifier
.fillMaxWidth()
.height(500.dp),
donutChartData,
donutChartConfig
)
```
Donut chart looks like this!
### 6. Combined Chart:
- Similar to line and bar chart we can combine both entities in one chart, just need to initialize the line and bar plot data using the random generator extension and add styling related to individual component.
```kotlin
val linePlotData = LinePlotData(
lines = listOf(
Line(
DataUtils.getLineChartData(listSize, maxRange = 100),
lineStyle = LineStyle(color = Color.Blue),
intersectionPoint = IntersectionPoint(),
selectionHighlightPoint = SelectionHighlightPoint(),
selectionHighlightPopUp = SelectionHighlightPopUp()
),
Line(
DataUtils.getLineChartData(listSize, maxRange),
lineStyle = LineStyle(color = Color.Black),
intersectionPoint = IntersectionPoint(),
selectionHighlightPoint = SelectionHighlightPoint(),
selectionHighlightPopUp = SelectionHighlightPopUp()
)
)
)
val barPlotData = BarPlotData(
groupBarList = DataUtils.getGroupBarChartData(listSize, maxValueRange, barSize),
barStyle = BarStyle(barWidth = 35.dp),
barColorPaletteList = colorPaletteList
)
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(30.dp)
.steps(maxOf(barChartData.size - 1, lineChartData.size - 1))
.bottomPadding(40.dp)
.labelData { index -> index.toString() }
.build()
val yAxisData = AxisData.Builder()
.steps(yStepSize)
.labelAndAxisLinePadding(20.dp)
.axisOffset(20.dp)
.labelData { index -> (index * (maxRange / yStepSize)).toString() }
.build()
```
- Initialize the combined chart config data with `CombinedChartData` data class in order to achieve styling and configurations related to same.
```kotlin
val combinedChartData = CombinedChartData(
combinedPlotDataList = listOf(barPlotData, linePlotData),
xAxisData = xAxisData,
yAxisData = yAxisData
)
```
- Finally, use the _**`CombinedChart`**_ component to render the chart.
```kotlin
CombinedChart(
modifier = Modifier.height(400.dp),
combinedCharthData = combinedChartData
)
```
_Note_ : To show legends infomartion related to bar, `Legends` component can be used.
Combined bar with line chart looks like this!
### 7. Wave Chart:
- Wave charts, also referred to as waveform charts or waveform displays, are specialized visualizations used primarily in the field of signal processing and electronics. These charts illustrate the amplitude (vertical axis) and time (horizontal axis) of a waveform.
```kotlin
val waveChartData = WaveChartData(
wavePlotData = WavePlotData(
lines = listOf(
Wave(
dataPoints = pointsData,
waveStyle = LineStyle(color = Color.Black),
selectionHighlightPoint = SelectionHighlightPoint(),
shadowUnderLine = ShadowUnderLine(),
selectionHighlightPopUp = SelectionHighlightPopUp(),
waveFillColor = WaveFillColor(topColor = Color.Green, bottomColor = Color.Red),
)
)
),
xAxisData = xAxisData,
yAxisData = yAxisData,
gridLines = GridLines()
)
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(30.dp)
.steps(maxOf(barChartData.size - 1, lineChartData.size - 1))
.bottomPadding(40.dp)
.labelData { index -> index.toString() }
.build()
val yAxisData = AxisData.Builder()
.steps(yStepSize)
.labelAndAxisLinePadding(20.dp)
.axisOffset(20.dp)
.labelData { index -> (index * (maxRange / yStepSize)).toString() }
.build()
```
- Initialize the Wave chart config data with `WaveChartData` data class in order to achieve styling and configurations related to same.
```kotlin
val waveChartData = WaveChartData(
wavePlotData = WavePlotData(
lines = listOf(
Wave(
dataPoints = pointsData,
waveStyle = LineStyle(color = Color.Black),
selectionHighlightPoint = SelectionHighlightPoint(),
shadowUnderLine = ShadowUnderLine(),
selectionHighlightPopUp = SelectionHighlightPopUp(),
waveFillColor = WaveFillColor(topColor = Color.Green, bottomColor = Color.Red),
)
)
),
xAxisData = xAxisData,
yAxisData = yAxisData,
gridLines = GridLines()
)
```
- Finally, use the _**`WaveChart`**_ component to render the chart.
```kotlin
WaveChart(
modifier = Modifier
.fillMaxWidth()
.height(300.dp),
waveChartData = data
)
```
_Note_ : To show legends infomartion related to bar, `Legends` component can be used.
Wavechart looks like this!
Sinewavechart looks like this!
### 8. Bubble Chart:
- Bubble charts are a variation of the scatter plot, where the data points are represented as bubbles or circles instead of simple dots. The bubbles' size represents the value of a third variable, in addition to the x-axis and y-axis variables. Bubble charts are effective in visualizing and comparing three different dimensions of data simultaneously.
```kotlin
val bubbleChartData = BubbleChartData(
DataUtils.getBubbleChartDataWithGradientStyle(pointsData),
xAxisData = xAxisData,
yAxisData = yAxisData,
gridLines = GridLines()
)
```
- Initialize X and Y Axis builders using the `AxisData` data class.
```kotlin
val xAxisData = AxisData.Builder()
.axisStepSize(30.dp)
.steps(maxOf(barChartData.size - 1, lineChartData.size - 1))
.bottomPadding(40.dp)
.labelData { index -> index.toString() }
.build()
val yAxisData = AxisData.Builder()
.steps(yStepSize)
.labelAndAxisLinePadding(20.dp)
.axisOffset(20.dp)
.labelData { index -> (index * (maxRange / yStepSize)).toString() }
.build()
```
- Initialize the Bubble chart config data with `BubbleChartData` data class in order to achieve styling and configurations related to same.
```kotlin
val bubbleChartData = BubbleChartData(
DataUtils.getBubbleChartDataWithGradientStyle(pointsData),
xAxisData = xAxisData,
yAxisData = yAxisData,
gridLines = GridLines()
)
```
- Finally, use the _**`BubbleChart`**_ component to render the chart.
```kotlin
BubbleChart(
modifier = Modifier
.fillMaxWidth()
.height(500.dp),
bubbleChartData = data
)
```
_Note_ : To show legends infomartion related to bar, `Legends` component can be used.
Gradient-Bubble chart looks like this!
Bubble chart looks like this!
## Accessibility Support
To interact with your device with touch and spoken feedback, you can turn on the TalkBack screen reader. TalkBack describes the graphs/charts when tapped on the graph container.
Compose views by deafult supports accessibility services, but for views drawn using canvas has no straight forward approach as of now, hence all our graph components supports an accessibility popup out of the box that will be shown over the graph with tapped on the container, with all the values described in an order to support accessibility services. User will be able to scroll the popup and find all the points, bars, slices or combined values in a descriptive manner, where user can tap and talkback would read it out loud.
fig (a)
fig (b)
Here fig(a) represents the line graph with the container being highlighted & fig(b) represents the accessibility sheet with all values laid out in detail so that talkback can describe the graph values.
_Note_: All the descriptions that are visible in the accessibility popup can be customized to the required string.
## KMM Support.
- For the ongoing effort to provide multiplatform solution, Ycharts now being written in Compose Multiplatform, adopting KMM has been a game-changer, we hope to achieve good results in this effort with community contribution.
Currently KMM compatible code can be found at _**`kmm-main`**_ branch
## Changes in version 2.0
- Fix for multiple line graph/chart has been added, now it can be used to plot multiple line graphs/line charts on a single canvas or a single line with multiple colors.
- Background color for Pie chart/Donut chart now can be set via _**`backgroundColor`**_ parameter through PieChartConfig model, this is done to keep the behaviour consistent with current syntax pattern.
- Kotlin-library updates: _**`Kotlin version`**_ has been upgraded to '1.8.10' along with agp, compose-compiler, core-ktx, target sdk, and other compatible library updates.
- Sample App has been updated to showcase more use-cases for each chart type.
## License
```
Copyright 2022 YCharts
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```