Table of Contents
- Table of contents :TOC:
- Flutter Charts - How to include the flutter_charts library in your application
- An example of Flutter Chart output
- Known packages, libraries and apps that use this this flutter_charts package
- Flutter Charts - an overview: data, options, classes
- Experimenting with Flutter Charts: Using the included example app
file:example/lib/main.dart - Flutter Charts - examples: LineChart and VerticalBarChart. Code and resulting charts
- Random Data (Y values), Random X Labels, Random Colors, Random Data Rows Legends, Data-Generated Y Labels.
- User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, Data-Generated Y Labels,
- User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, User-Provided Y Labels
- VerticalBar Chart - one more example, showing positive/negative stacks:
- Bugs status
- Future enhancements and work
- TODO Terminology and Selected Classes
- Internal notes
- DONE Add ability to create a Table of Contents to README.org
- Adding images to README.org
- Pub - Publishing workflow on https://pub.dartlang.org
- Notes:
- IF README.md needs change
- pubspec.yaml - Increase version number
cd flutter_charts; flutter packages pub upgradecd flutter_charts; flutter packages pub get- Test included app from IntelliJ
git push- README.md on https://github.com/mzimmerm/flutter_charts - check if looks ok
flutter packages pub publish --dry-runflutter packages pub publish- Check https://pub.dartlang.org/packages/flutter_charts
- Test the package that was just published
- Flutter Charts - How to include the flutter_charts library in your application (See section )
- An example of Flutter Chart output (See section )
- Known packages, libraries and apps that use this this flutter_charts package (See section )
- Flutter Charts - an overview: data, options, classes (See section )
- Experimenting with Flutter Charts: Using the included example app
file:example/lib/main.dart(See section ) - Flutter Charts - examples: LineChart and VerticalBarChart. Code and resulting charts (See section )
- Random Data (Y values), Random X Labels, Random Colors, Random Data Rows Legends, Data-Generated Y Labels. (See section )
- User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, Data-Generated Y Labels, (See section )
- User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, User-Provided Y Labels (See section )
- VerticalBar Chart - one more example, showing positive/negative stacks: (See section )
- User-Provided Data (Y values), User-Provided X Labels, User-Provided Colors, User-Provided Data Rows Legends, User-Provided Y Labels (See section )
- Bugs status (See section )
- Future enhancements and work (See section )
- Terminology and Selected Classes (See section )
- Internal notes (See section )
- Add ability to create a Table of Contents to README.org (See section )
- Adding images to README.org (See section )
- Pub - Publishing workflow on https://pub.dartlang.org (See section )
Flutter Charts is a charting library for Flutter, written in Flutter. Currently, column chart and line chart are supported.
The package is published on pub for inclusion in your application's pubspec.yaml: The Installing tab on https://pub.dartlang.org/packages/flutter_charts contains instructions on how to include the flutter_charts package in your application.
There is one example application in flutter_charts: example/lib/main.dart. It shows how a Flutter Chart can be included in a Flutter application.
You can run the example application using one of the methods (6, 7) in the paragraph below.
This application is also used as a base to show several sample charts in the paragraphs below.
Vertical Bar Chart (Column Chart)
Point and Line Chart (Line Chart)
Output uses semi-random data. You can click the blue + button to rerun chart with a different dataset.
- Michael R. Fairhurst's Language reader app - see https://github.com/MichaelRFairhurst/flutter-language-reader-app
Before we show several examples of charts, a few notes.
- The
ChartDataclass: allows to define data - X labels, Y values, (optional) Y labels, each-dataRow (series) legends, each-dataRow (series) color. The list below provides a summary description of each item- X labels:
ChartData.xLabelsallow to define X labels. SettingxLabelsis required, but client can set them to empty strings. - Y values:
ChartData.dataRowsallow to define Y values in rows. Assumption: size of each data row inChartData.dataRowsis the same, and each data row size ==ChartData.xLabels.size - Y labels (optional): Normally, Y labels are generated from data. The option
ChartOptions.useUserProvidedYLabels(default true), asks flutter_charts to data-generate Y labels. If this option is set to false, thenChartData.yLabelsmust be set. Any number of such user-provided Y labels is allowed. - Each-dataRow (each series) legends:
ChartData.dataRowsLegendsallow to define a legend for each data row inChartData.dataRows. Assumption:ChartData.dataRows.size==ChartData.dataRowsLegends.size - Each-dataRow (each series) color:
ChartData.dataRowsColorsallow to define a color for each data row inChartData.dataRows. Assumption:ChartData.dataRows.size==ChartData.dataRowsColors.size
- X labels:
- The
ChartOptionsclass: allows to define options, by using it's defaults, or setting some options to non default values. There are alsoLineChartOptionsandVerticalBarChartOptionsclasses. - Support for randomly generated data, colors, labels: Flutter Charts also provides randomly generated data, in the class
RandomChartData. This class generates:- Y values data,
- X labels,
- Series colors,
- Series legends
- Currently the only purpose of
RandomChartDatais for use in the examples below. To be clear,RandomChartDataY values, series colors, and series legends are not completely random - they hardcode some demoable label, legends, color values, and data ranges (data random within the range).
There are multiple ways to experiment with Flutter Charts from your computer. We describe running Flutter Charts in development mode on your device (Android, iOS - follow 1, 2 or 3, 4 and 6), or alternatively on a device emulator (device emulator running from an IDE such as IntelliJ with Android Studio installed - follow 1, 2 or 3, 5, 6 or 7).
-
Install Flutter on your computer. See https://flutter.io/ installation section.
-
Clone flutter_charts code from Github to your computer. Needs git client.
cd DIRECTORY_OF_CHOICE git clone https://github.com/mzimmerm/flutter_charts.git # clone will create directory flutter_charts cd flutter_charts -
(Alternative to 2.): Download and unzip flutter_charts code from Github
- Browse to https://github.com/mzimmerm/flutter_charts.git
- On the righ top, click on the "Clone or Download" button, then select save Zip, save and extract to DIRECTORY_OF_CHOICE
- cd flutter_charts
-
Prepare a physical device (must be set to Development Mode) to run applications from your computer. Then connect a android device in development mode to your computer. See https://www.kingoapp.com/root-tutorials/how-to-enable-usb-debugging-mode-on-android.htm
-
(Alternative to 4.): Prepare and start an Android device emulator on your computer.
-
Install Android Studio: see https://developer.android.com/studio/index.html
-
Install an IDE such as IntelliJ with Flutter plugin. See https://flutter.io/intellij-setup/
-
-
Run Flutter Charts demo app from command line (this will work in both method 4. and method 5.)
cd DIRECTORY_OF_CHOICE/flutter_charts flutter run example/lib/main.dart -
(Alternative to 6.) Run Flutter Charts demo app from IDE. This will work only with method 5.
- Start IntelliJ IDE, create a project in the
DIRECTORY_OF_CHOICE/flutter_chartsstart an Android emulator, then click on the Run button in Intellij (which should show thefile:example/lib/main.dartin the run button).
- Start IntelliJ IDE, create a project in the
Flutter Charts code allow to define the following data elements:
| *Data (Y values)* | User-Provided or Random |
| *X Labels* | User-Provided or Random |
| *Options including Colors* | User-Provided or Random |
| *Data Rows Legends* | User-Provided or Random |
| *Y Labels* | User-Provided or Data-Generated |
The examples below show a few alternative code snippets (User-Provided or Random data, labels, option) and the resulting charts.
The chart images were obtained by substituting the code snippet to the file:example/lib/main.dart code.
Random Data (Y values), Random X Labels, Random Colors, Random Data Rows Legends, Data-Generated Y Labels.
This example shows that Data-Generated Y labels is the default.
Flutter Charts support reasonably intelligently generated Y Labels from data, including dealing with negatives.
Code in defineOptionsAndData():
void defineOptionsAndData() {
_lineChartOptions = new LineChartOptions();
_verticalBarChartOptions = new VerticalBarChartOptions();
_chartData = new RandomChartData(useUserProvidedYLabels: _lineChartOptions.useUserProvidedYLabels);
}
Result line chart:
Result vertical bar chart:
User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, Data-Generated Y Labels,
Code in defineOptionsAndData():
void defineOptionsAndData() {
_lineChartOptions = new LineChartOptions();
_verticalBarChartOptions = new VerticalBarChartOptions();
_chartData = new ChartData();
_chartData.dataRowsLegends = [
"Spring",
"Summer",
"Fall",
"Winter"];
_chartData.dataRows = [
[10.0, 20.0, 5.0, 30.0, 5.0, 20.0, ],
[30.0, 60.0, 16.0, 100.0, 12.0, 120.0, ],
[25.0, 40.0, 20.0, 80.0, 12.0, 90.0, ],
[12.0, 30.0, 18.0, 40.0, 10.0, 30.0, ],
];
_chartData.xLabels = ["Wolf", "Deer", "Owl", "Mouse", "Hawk", "Vole"];
_chartData.assignDataRowsDefaultColors();
// Note: ChartOptions.useUserProvidedYLabels default is still used (false);
}
Result line chart:
Result vertical bar chart:
User-Provided Data (Y values), User-Provided X Labels, Random Colors, User-Provided Data Rows Legends, User-Provided Y Labels
This example show how to use the option useUserProvidedYLabels, and scaling of data to the Y labels range.
Code in defineOptionsAndData():
void defineOptionsAndData() {
// This example shows user defined Y Labels.
// When setting Y labels by user, the dataRows value scale
// is irrelevant. User can use for example interval <0, 1>,
// <0, 10>, or any other, even negative ranges. Here we use <0-10>.
// The only thing that matters is the relative values in the data Rows.
// Note that current implementation sets
// the minimum of dataRows range (1.0 in this example)
// on the level of the first Y Label ("Ok" in this example),
// and the maximum of dataRows range (10.0 in this example)
// on the level of the last Y Label ("High" in this example).
// This is not desirable, we need to add a userProvidedYLabelsBoundaryMin/Max.
_lineChartOptions = new LineChartOptions();
_verticalBarChartOptions = new VerticalBarChartOptions();
_chartData = new ChartData();
_chartData.dataRowsLegends = [
"Java",
"Dart",
"Python",
"Newspeak"];
_chartData.dataRows = [
[9.0, 4.0, 3.0, 9.0, ],
[7.0, 6.0, 7.0, 6.0, ],
[4.0, 9.0, 6.0, 8.0, ],
[3.0, 9.0, 10.0, 1.0, ],
];
_chartData.xLabels = ["Fast", "Readable", "Novel", "Use"];
_chartData.dataRowsColors = [
Colors.blue,
Colors.yellow,
Colors.green,
Colors.amber,
];
_lineChartOptions.useUserProvidedYLabels = true; // use the labels below on Y axis
_chartData.yLabels = [
"Ok",
"Higher",
"High",
];
}
Result line chart:
(Disclaimer: Not actually measured)
Result vertical bar chart: Here the Y values should be numeric (if any) as manual labeling "Ok", "Higher", High" does not make sense for stacked type charts.
(Disclaimer: Not actually measured)
User-Provided Data (Y values), User-Provided X Labels, User-Provided Colors, User-Provided Data Rows Legends, User-Provided Y Labels
This example has again user defined Y Labels, with a bar chart, using the smart auto-layout of user defined Y Labels. The chart shows negative and positive values similar to %down/%up stock charts.
Code in defineOptionsAndData():
void defineOptionsAndData() {
// This example shows user defined Y Labels with
// a bar chart, showing negative and positive values
// similar to %down/%up stock charts.
_lineChartOptions = new LineChartOptions();
_verticalBarChartOptions = new VerticalBarChartOptions();
_chartData = new ChartData();
_chartData.dataRowsLegends = [
"-2%_0%",
"<-2%",
"0%_+2%",
">+2%"];
// each column absolute values should add to same number todo - 100 would make more sense, to represent 100% of stocks in each category
_chartData.dataRows = [
[-9.0, -8.0, -8.0, -5.0, -8.0, ],
[-1.0, -2.0, -4.0, -1.0, -1.0, ],
[7.0, 8.0, 7.0, 11.0, 9.0, ],
[3.0, 2.0, 1.0, 3.0, 3.0, ],
];
_chartData.xLabels = ["Energy", "Health", "Finance", "Chips", "Oil"];
_chartData.dataRowsColors = [
Colors.grey,
Colors.red,
Colors.greenAccent,
Colors.black,
];
_lineChartOptions.useUserProvidedYLabels = false; // use labels below
//_chartData.yLabels = [
// "Ok",
// "Higher",
// "High",
//];
}
Result vertical bar chart:
(there is a bug here,see Known Bugs)
- Chart area needs clipping in the application
- Take a look at the stock charts example. There is a bug reverting series on the negative values - both negative dataRows, and dataRowsColors must be reverted for the chart stacks to show in intended order (black, green grey red from top). But even then, dataRowsLegends are incorrect.
- mzimmerm#5 - Coloring support: Make line chart dot colors settable
- [ ]
Bug fixes:
- Clip chart to not paint outside area provided by Flutter app.
- Clip labels and legends not to run into the neighbor, if too long.
On the boundary of bug and enhancement:
- For ChartOptions.useUserProvidedYLabels = true. See example with User defined YLabels: Current implementation sets the minimum of dataRows range (1.0 in the example) on the level of the first Y Label ("Ok" in this example), and the maximum of dataRows range (10.0 in this example) on the level of the last Y Label ("High" in this example). This is not desirable, we need to add a userProvidedYLabelsBoundaryMin/Max.
Enhancements:
- Create document / image showing layout and spacing - show option variables on image
- Simple:
- Add options to hide the grid (keep axes)
- Add options to hide axes (if axes not shown, labels should not show?)
- Decrease option for default spacing around the Y axis.
- First, probably need to provide tooltips
- Next, a few more chart types: Spline line chart (stacked line chart), Grouped VerticalBar chart,
- Next, re-implement the layout more generically and clearly. Space saving changes such as tilting labels.
- Next, add ability to invert X and Y axis (values on horizontal axis)
- (Presenter)Leaf : The finest visual element presented in each "column of view" in chart - that is, all widgets representing series of data displayed above each X label. For example, for Line chart, the leaf would be one line and dot representing one Y value at one X label. For the bar chart, the leaf would be one bar representing one (stacked) Y value at one X label.
- Classes: Presenter, LineAndHotspotPresenter, VerticalBarPresenter, PresenterCreator
- Painter : Class which paints to chart to canvas. Terminology and class structure taken from Flutter's Painter and Painting classes.
- Classes: todo
-
Install toc-org package
-
Add to init.el
(if (require 'toc-org nil t) (add-hook 'org-mode-hook 'toc-org-enable) (warn "toc-org not found")) -
Every time README.org is saved, first heading with a :TOC: tag will be updated with the current table of contents.
-
So nothing special need be done after the above is configured.
- https://pub.dartlang.org does not allow storing images.
- Add / move new images to
flutter_charts/doc/readme_images - org file, change image links to look like ~
Pub - Publishing workflow on https://pub.dartlang.org
-
Pub requires the following file in project to show the correct tabs on pub
-
Tab README.md - Needs the file
-
Tab CHANGELOG.md - Needs the file
-
Tab Example - this tab appears if the project file
file:flutter_charts/example/lib/main.dartexists -
Tab Installing - shows automatically
-
-
README.org: make sure image links point to
flutter_charts/doc/readme_images -
README.org: Conversion steps to README.md
To convert README.org to README.md, we need to do a few extra steps for README.md image links to be readable on https://pub.dartlang.org.
-
Note: Org file which has :TOC: in heading, generates TOC on every save.
-
README.org: Export org to md:
C-c C-e m min the org file to create the generated md file -
README.md: Delete generated TOC
-
README.md: Generate md-native TOC:
- Cursor on top
M-x: markdown-toc/generate-toc
-
README.md: Fix image links in the README.md - links must look like this:
- + -
README.md: This is achieved with:
replace-string https://github.com/mzimmerm/flutter_charts/raw/master/doc/readme_images/ https://github.com/mzimmerm/flutter_charts/raw/master/https://github.com/mzimmerm/flutter_charts/raw/master/doc/readme_images/
-
README.md on https://github.com/mzimmerm/flutter_charts - check if looks ok
cd flutter_charts_sample_app; flutter packages pub upgrade; flutter packages pub get; flutter run