flutter_charts 0.3.1 flutter_charts: ^0.3.1 copied to clipboard
Charts Library for Flutter, written in Dart with Flutter. Allows to create line chart and bar chart by specifying data as a simple array.
Table of Contents
- New in the current release
- Installing flutter_charts as a library into your app
- Installing the flutter_charts project locally from Github, and running the example app
- Examples with code: LineChart and VerticalBarChart. Code and resulting charts
- Example with 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:
- Illustration of the "iterative auto layout" feature
- Known packages, libraries and apps that use this flutter_charts package
- An overview of this library: data, options, classes
New in the current release #
Current release is 0.3.1
See <CHANGELOG.md> for the list of new features and bug fixes in this release.
In particular, the optional ability to hide labels (on x axis, y axis), hide the legend, and hide the gridline has been added. This feature is controlled by ChartOptions
. See the code in `example1/lib/main.dart`. This is an out of context example of how to create the options that ignore all labels, legend, and gridline. Ignoring only one, or any combination will also work
ChartOptions chartOptions = VerticalBarChartOptions.noLabels();
or to set individual values to false. Default is true so no need to set those that we want to show.
ChartOptions chartOptions =
VerticalBarChartOptions(
chartOptions: const ChartOptions(
legendOptions: LegendOptions(
isLegendContainerShown: false,
),
xContainerOptions: XContainerOptions(
isXContainerShown: false,
),
yContainerOptions: YContainerOptions(
isYContainerShown: false,
isYGridlinesShown: false,
),
)
);
Illustration of this new feature, ability to hide labels, legend, or gridlines #
Code is for the line chart. See the function Widget createRequestedChart()
in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart for changes to create a vertical bar chart instead (essentially in this code substitute "Line" for "VerticalBar". For the configuration, the section of interest is around ExamplesEnum.ex31AnimalsBySeasonNoLabelsShown
// This is how noLabels can be set. See the previous section for a fine control of this option
ChartOptions chartOptions = LineChartOptions.noLabels();
ChartData chartData = 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();
// This section is shown repeatedly in all examples, to stress how charts are created
LineChartTopContainer lineChartContainer = LineChartTopContainer(
chartData: chartData,
chartOptions: chartOptions,
xContainerLabelLayoutStrategy: xContainerLabelLayoutStrategy,
);
LineChart lineChart = LineChart(
painter: LineChartPainter(
lineChartContainer: lineChartContainer,
),
);
The lineChart
widget can be placed on any Flutter app. The example code is in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart
Result line chart:
Result vertical bar chart:
Installing flutter_charts as a library into your app #
If you want to use flutter_charts in your app, please follow https://pub.dev/packages/flutter_charts/install.
Installing the flutter_charts project locally from Github, and running the example app #
The advantage of installing the full flutter_charts project locally from Github is that you can run the packaged example application and also run the integration and widget tests.
Installing the flutter_charts project locally from Github #
To install flutter_charts project locally from Github, follow these steps:
- Install Flutter, and items such as Android emulator. Instructions are on the Flutter website https://docs.flutter.dev/get-started/install.
- Go to https://github.com/mzimmerm/flutter_charts, click on the "Code" button, and follow the instuctions to checkout flutter_charts. A summary of one installation method (download method):
- Click the "Download zip" link https://github.com/mzimmerm/flutter_charts/archive/refs/heads/master.zip
- When prompted, save the file
flutter_charts-master.zip
one level above where you want the project. We will use$HOME/dev
- Unzip the file
flutter_charts-master.zip
- The project will be in the
$HOME/dev/flutter_charts-master/
directory
Running the example app #
There is an example application in flutter_charts: example1/lib/main.dart
. It shows how the Flutter Charts library can be included in a Flutter application.
To run the example application, Android emulator or iOS emulator need to be installed. See the installation link above. To use the project, you can use an IDE or command line. Instructions here are for the command line. Start in the unzipped directory, and follow items below:
-
Important: Make sure an Android or iOS emulator is running, or you have a physical device connected. See the 3.1 section.
-
cd $HOME/dev/flutter_charts-master/
This is where -
Paste any of the lines below to the command line. Each line runs the example app with a different chart example.
flutter run --dart-define=EXAMPLE_TO_RUN=ex10RandomData --dart-define=CHART_TYPE_TO_SHOW=lineChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex10RandomData --dart-define=CHART_TYPE_TO_SHOW=verticalBarChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex11RandomDataWithLabelLayoutStrategy --dart-define=CHART_TYPE_TO_SHOW=lineChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex11RandomDataWithLabelLayoutStrategy --dart-define=CHART_TYPE_TO_SHOW=verticalBarChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex30AnimalsBySeasonWithLabelLayoutStrategy --dart-define=CHART_TYPE_TO_SHOW=lineChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex30AnimalsBySeasonWithLabelLayoutStrategy --dart-define=CHART_TYPE_TO_SHOW=verticalBarChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex31AnimalsBySeasonNoLabelsShown --dart-define=CHART_TYPE_TO_SHOW=lineChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex31AnimalsBySeasonNoLabelsShown --dart-define=CHART_TYPE_TO_SHOW=verticalBarChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex40LanguagesWithYOrdinalUserLabelsAndUserColors --dart-define=CHART_TYPE_TO_SHOW=lineChart example1/lib/main.dart flutter run --dart-define=EXAMPLE_TO_RUN=ex50StocksWithNegativesWithUserColors --dart-define=CHART_TYPE_TO_SHOW=verticalBarChart example1/lib/main.dart
Screenshot from the running example app
Examples with code: LineChart and VerticalBarChart. Code and resulting charts #
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.
See the section 3.2 on how to run the code that created the images below. The code snippets are from the method Widget createRequestedChart()
in example1/lib/main.dart
Example with 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 are default. Flutter Charts support reasonably intelligently generated Y Labels from data, including dealing with negatives.
Code is for line chart. See the function Widget createRequestedChart()
in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart for changes to create a vertical bar chart instead (essentially in this code substitute "Line" for "VerticalBar".
ChartOptions chartOptions = LineChartOptions();
ChartData chartData = RandomChartData();
// This section is shown repeatedly in all examples, to stress how charts are created
LineChartTopContainer lineChartContainer = LineChartTopContainer(
chartData: chartData,
chartOptions: chartOptions,
xContainerLabelLayoutStrategy: xContainerLabelLayoutStrategy,
);
LineChart lineChart = LineChart(
painter: LineChartPainter(
lineChartContainer: lineChartContainer,
),
);
The lineChart
widget can be placed on any Flutter app. The example code is in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart
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 is for line chart. See the function Widget createRequestedChart()
in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart for changes to create a vertical bar chart instead (essentially in this code substitute "Line" for "VerticalBar". Section ExamplesEnum.ex30AnimalsBySeasonWithLabelLayoutStrategy_lineChart.png
ChartOptions chartOptions = LineChartOptions();
LabelLayoutStrategy xContainerLabelLayoutStrategy = DefaultIterativeLabelLayoutStrategy(
options: chartOptions,
);
ChartData chartData = 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();
// This section is shown repeatedly in all examples, to stress how charts are created
LineChartTopContainer lineChartContainer = LineChartTopContainer(
chartData: chartData,
chartOptions: chartOptions,
xContainerLabelLayoutStrategy: xContainerLabelLayoutStrategy,
);
LineChart lineChart = LineChart(
painter: LineChartPainter(
lineChartContainer: lineChartContainer,
),
);
The lineChart
widget can be placed on any Flutter app. The example code is in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart
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.
For code, please refer to the function Widget createRequestedChart()
in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart, section ExamplesEnum.ex40LanguagesWithYOrdinalUserLabelsAndUserColors
VerticalBar Chart - one more example, showing positive/negative stacks: #
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.
For code, please refer to the function Widget createRequestedChart()
in https://github.com/mzimmerm/flutter_charts/blob/master/example1/lib/main.dart, section ExamplesEnum.ex50StocksWithNegativesWithUserColors
(there is a bug here,see Known Bugs)
Illustration of the "iterative auto layout" feature #
This section illustrates how the auto layout behaves when less and less horizontal space is available to display the chart.
Flutter chart library automatically checks for the X label overlap, and follows with rule-based iterative re-layout, to prevent labels running into each other.
To illustrate "stressed" horizontal space for the chart, we are gradually adding a text widget containing and increasing number of '<' signs on the right of the chart.
Autolayout step 1 #
Let's say there are six labels on a chart, and sufficient space to display labels horizontally. The result may look like this:
We can see all x axis labels displayed it full, horizontally oriented.
Autolayout step 2 #
Next, let us make less available space by taking away some space on the right with a wider text label like this '<<<<<<'
We can see the labels were automatically tilted by angle ChartOptions labelTiltRadians
for the labels to fit.
Autolayout step 3 #
Next, let us make even less available space by taking away some space on the right with a wider text label like this '<<<<<<<<<<<'.
We can see that labels are not only tilted, but also automatically skipped (every 2nd) for labels not to overlap.
Autolayout step 4 #
Next, let us make even less available space some more compared to step 3, with even a wider text label like this '<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<'.
We can see even more labels were skipped for labels to prevent overlap, the chart is showing evey 5th label
Autolayout step 5 #
Last, let us take away extreme amount of horizontal space by using '<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<',
Here we can see the "default auto layout" finally gave up, and overlaps labels. Also, the legend is now hidded, as there is not enough horizontal space.
Known packages, libraries and apps that use this flutter_charts package #
- Michael R. Fairhurst's Language reader app - see https://github.com/MichaelRFairhurst/flutter-language-reader-app
An overview of this library: data, options, classes #
Before we show several examples of charts, a few notes.
- The
ChartData
class: 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.xLabels
allow to define X labels. SettingxLabels
is required, but client can set them to empty strings. - Y values:
ChartData.dataRows
allow to define Y values in rows. Assumption: size of each data row inChartData.dataRows
is 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.yLabels
must be set. Any number of such user-provided Y labels is allowed. - Each-dataRow (each series) legends:
ChartData.dataRowsLegends
allow to define a legend for each data row inChartData.dataRows
. Assumption:ChartData.dataRows.size
==ChartData.dataRowsLegends.size
- Each-dataRow (each series) color:
ChartData.dataRowsColors
allow to define a color for each data row inChartData.dataRows
. Assumption:ChartData.dataRows.size
==ChartData.dataRowsColors.size
- X labels:
- The
ChartOptions
class: allows to define options, by using it's defaults, or setting some options to non default values. There are alsoLineChartOptions
andVerticalBarChartOptions
classes. - 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
RandomChartData
is for use in the examples below. To be clear,RandomChartData
Y 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).