From a9ac43720fb30793acba3fdf83cd24f7f0dd3f86 Mon Sep 17 00:00:00 2001 From: stockiNail Date: Fri, 14 Jun 2024 14:14:54 +0200 Subject: [PATCH] version 6.6 preparation --- docs/axes/Category.md | 2 +- docusaurus.config.js | 2 +- package.json | 2 +- sidebars.js | 4 +- versioned_docs/version-6.0/axes/Category.md | 2 +- versioned_docs/version-6.0/axes/Linear.md | 2 +- .../version-6.0/axes/Logarithmic.md | 2 +- versioned_docs/version-6.0/axes/Radial.md | 2 +- versioned_docs/version-6.0/axes/Time.md | 2 +- versioned_docs/version-6.0/axes/TimeSeries.md | 2 +- .../version-6.0/charts/geo/BubbleMap.md | 4 +- .../version-6.0/charts/geo/Choropleth.md | 4 +- versioned_docs/version-6.1/axes/Category.md | 2 +- versioned_docs/version-6.1/axes/Linear.md | 2 +- .../version-6.1/axes/Logarithmic.md | 2 +- versioned_docs/version-6.1/axes/Radial.md | 2 +- versioned_docs/version-6.1/axes/Time.md | 2 +- versioned_docs/version-6.1/axes/TimeSeries.md | 2 +- .../version-6.1/charts/geo/BubbleMap.md | 4 +- .../version-6.1/charts/geo/Choropleth.md | 4 +- versioned_docs/version-6.2/axes/Category.md | 2 +- versioned_docs/version-6.2/axes/Linear.md | 2 +- .../version-6.2/axes/Logarithmic.md | 2 +- versioned_docs/version-6.2/axes/Radial.md | 2 +- versioned_docs/version-6.2/axes/Time.md | 2 +- versioned_docs/version-6.2/axes/TimeSeries.md | 2 +- .../version-6.2/charts/geo/BubbleMap.md | 4 +- .../version-6.2/charts/geo/Choropleth.md | 4 +- versioned_docs/version-6.3/axes/Category.md | 2 +- versioned_docs/version-6.3/axes/Linear.md | 2 +- .../version-6.3/axes/Logarithmic.md | 2 +- versioned_docs/version-6.3/axes/Radial.md | 2 +- versioned_docs/version-6.3/axes/Time.md | 2 +- versioned_docs/version-6.3/axes/TimeSeries.md | 2 +- .../version-6.3/charts/geo/BubbleMap.md | 4 +- .../version-6.3/charts/geo/Choropleth.md | 4 +- versioned_docs/version-6.4/axes/Category.md | 2 +- versioned_docs/version-6.4/axes/Linear.md | 2 +- .../version-6.4/axes/Logarithmic.md | 2 +- versioned_docs/version-6.4/axes/Radial.md | 2 +- versioned_docs/version-6.4/axes/Time.md | 2 +- versioned_docs/version-6.4/axes/TimeSeries.md | 2 +- .../version-6.4/charts/geo/BubbleMap.md | 4 +- .../version-6.4/charts/geo/Choropleth.md | 4 +- versioned_docs/version-6.5/Controllers.md | 484 +++++ versioned_docs/version-6.5/DateAdapters.md | 81 + versioned_docs/version-6.5/Home.md | 18 + versioned_docs/version-6.5/Overview.md | 127 ++ versioned_docs/version-6.5/Regressions.md | 399 ++++ versioned_docs/version-6.5/Requirements.md | 235 +++ versioned_docs/version-6.5/axes/AngleLines.md | 73 + versioned_docs/version-6.5/axes/Axes.md | 314 +++ versioned_docs/version-6.5/axes/Cartesians.md | 22 + versioned_docs/version-6.5/axes/Category.md | 213 +++ versioned_docs/version-6.5/axes/Grid.md | 124 ++ versioned_docs/version-6.5/axes/Linear.md | 265 +++ .../version-6.5/axes/Logarithmic.md | 241 +++ .../version-6.5/axes/PointLabels.md | 112 ++ versioned_docs/version-6.5/axes/Radial.md | 224 +++ versioned_docs/version-6.5/axes/ScaleTitle.md | 40 + versioned_docs/version-6.5/axes/Time.md | 328 ++++ versioned_docs/version-6.5/axes/TimeSeries.md | 332 ++++ versioned_docs/version-6.5/charts/Api.md | 545 ++++++ versioned_docs/version-6.5/charts/Area.md | 330 ++++ versioned_docs/version-6.5/charts/Bar.md | 313 +++ versioned_docs/version-6.5/charts/Bubble.md | 232 +++ versioned_docs/version-6.5/charts/Charts.md | 97 + versioned_docs/version-6.5/charts/Doughnut.md | 254 +++ versioned_docs/version-6.5/charts/Gauge.md | 319 ++++ .../version-6.5/charts/HorizontalBar.md | 306 +++ versioned_docs/version-6.5/charts/Line.md | 436 +++++ versioned_docs/version-6.5/charts/Matrix.md | 217 +++ versioned_docs/version-6.5/charts/Meter.md | 260 +++ versioned_docs/version-6.5/charts/Pie.md | 254 +++ .../version-6.5/charts/PolarArea.md | 216 +++ versioned_docs/version-6.5/charts/Radar.md | 331 ++++ versioned_docs/version-6.5/charts/Sankey.md | 213 +++ versioned_docs/version-6.5/charts/Scatter.md | 314 +++ .../version-6.5/charts/StackedArea.md | 319 ++++ .../version-6.5/charts/StackedBar.md | 333 ++++ .../version-6.5/charts/StackedLine.md | 403 ++++ .../version-6.5/charts/TimeSeries.md | 199 ++ versioned_docs/version-6.5/charts/TreeMap.md | 468 +++++ .../version-6.5/charts/VerticalLine.md | 413 ++++ .../version-6.5/charts/geo/BubbleMap.md | 333 ++++ .../version-6.5/charts/geo/Choropleth.md | 375 ++++ .../version-6.5/charts/geo/Introduction.md | 152 ++ versioned_docs/version-6.5/coloring/Colors.md | 178 ++ .../version-6.5/coloring/Gradients.md | 99 + .../version-6.5/coloring/Patterns.md | 183 ++ .../coloring/tables/GWTMaterialColors.md | 277 +++ .../coloring/tables/GoogleChartColors.md | 51 + .../coloring/tables/HTMLColorsNames.md | 168 ++ .../version-6.5/configuration/Animation.md | 282 +++ .../version-6.5/configuration/Commons.md | 203 ++ .../version-6.5/configuration/Datasets.md | 36 + .../version-6.5/configuration/Elements.md | 317 ++++ .../configuration/FillerAndDecimation.md | 70 + .../version-6.5/configuration/Interaction.md | 463 +++++ .../version-6.5/configuration/Layout.md | 64 + .../version-6.5/configuration/Legend.md | 277 +++ .../configuration/ScriptableOptions.md | 313 +++ .../version-6.5/configuration/Subtitle.md | 68 + .../version-6.5/configuration/Title.md | 68 + .../version-6.5/configuration/Tooltip.md | 553 ++++++ .../version-6.5/defaults/Defaults.md | 119 ++ .../version-6.5/defaults/DefaultsCharts.md | 672 +++++++ .../version-6.5/defaults/DefaultsScales.md | 327 ++++ .../version-6.5/extensions/Annotation.md | 1677 +++++++++++++++++ .../version-6.5/extensions/DataLabels.md | 693 +++++++ .../version-6.5/extensions/Extensions.md | 21 + .../version-6.5/extensions/Gradient.md | 124 ++ .../version-6.5/extensions/Labels.md | 378 ++++ versioned_docs/version-6.5/extensions/Zoom.md | 556 ++++++ .../version-6.5/getting-started/Building.md | 63 + .../getting-started/GettingStarted.md | 118 ++ .../getting-started/Integration.md | 98 + .../version-6.5/intl/DateTimeFormat.md | 143 ++ versioned_docs/version-6.5/intl/Locale.md | 103 + .../version-6.5/intl/NumberFormat.md | 133 ++ .../version-6.5/plugins/BackgroundColor.md | 138 ++ .../version-6.5/plugins/ColorSchemes.md | 133 ++ .../version-6.5/plugins/Crosshair.md | 194 ++ .../plugins/DatasetsItemsSelector.md | 252 +++ .../version-6.5/plugins/HTMLLegend.md | 196 ++ versioned_docs/version-6.5/plugins/Import.md | 101 + versioned_docs/version-6.5/plugins/Plugins.md | 684 +++++++ versioned_docs/version-6.5/plugins/Pointer.md | 122 ++ .../plugins/tables/ColorSchemeBrewer.md | 279 +++ .../plugins/tables/ColorSchemeGwtMaterial.md | 28 + .../plugins/tables/ColorSchemeOffice.md | 146 ++ .../plugins/tables/ColorSchemeTableau.md | 94 + .../utilities/AnnotationBuilder.md | 34 + .../version-6.5/utilities/Javascript.md | 206 ++ versioned_docs/version-6.5/utilities/Toast.md | 733 +++++++ versioned_sidebars/version-6.5-sidebars.json | 201 ++ versions.json | 1 + 137 files changed, 23756 insertions(+), 55 deletions(-) create mode 100644 versioned_docs/version-6.5/Controllers.md create mode 100644 versioned_docs/version-6.5/DateAdapters.md create mode 100644 versioned_docs/version-6.5/Home.md create mode 100644 versioned_docs/version-6.5/Overview.md create mode 100644 versioned_docs/version-6.5/Regressions.md create mode 100644 versioned_docs/version-6.5/Requirements.md create mode 100644 versioned_docs/version-6.5/axes/AngleLines.md create mode 100644 versioned_docs/version-6.5/axes/Axes.md create mode 100644 versioned_docs/version-6.5/axes/Cartesians.md create mode 100644 versioned_docs/version-6.5/axes/Category.md create mode 100644 versioned_docs/version-6.5/axes/Grid.md create mode 100644 versioned_docs/version-6.5/axes/Linear.md create mode 100644 versioned_docs/version-6.5/axes/Logarithmic.md create mode 100644 versioned_docs/version-6.5/axes/PointLabels.md create mode 100644 versioned_docs/version-6.5/axes/Radial.md create mode 100644 versioned_docs/version-6.5/axes/ScaleTitle.md create mode 100644 versioned_docs/version-6.5/axes/Time.md create mode 100644 versioned_docs/version-6.5/axes/TimeSeries.md create mode 100644 versioned_docs/version-6.5/charts/Api.md create mode 100644 versioned_docs/version-6.5/charts/Area.md create mode 100644 versioned_docs/version-6.5/charts/Bar.md create mode 100644 versioned_docs/version-6.5/charts/Bubble.md create mode 100644 versioned_docs/version-6.5/charts/Charts.md create mode 100644 versioned_docs/version-6.5/charts/Doughnut.md create mode 100644 versioned_docs/version-6.5/charts/Gauge.md create mode 100644 versioned_docs/version-6.5/charts/HorizontalBar.md create mode 100644 versioned_docs/version-6.5/charts/Line.md create mode 100644 versioned_docs/version-6.5/charts/Matrix.md create mode 100644 versioned_docs/version-6.5/charts/Meter.md create mode 100644 versioned_docs/version-6.5/charts/Pie.md create mode 100644 versioned_docs/version-6.5/charts/PolarArea.md create mode 100644 versioned_docs/version-6.5/charts/Radar.md create mode 100644 versioned_docs/version-6.5/charts/Sankey.md create mode 100644 versioned_docs/version-6.5/charts/Scatter.md create mode 100644 versioned_docs/version-6.5/charts/StackedArea.md create mode 100644 versioned_docs/version-6.5/charts/StackedBar.md create mode 100644 versioned_docs/version-6.5/charts/StackedLine.md create mode 100644 versioned_docs/version-6.5/charts/TimeSeries.md create mode 100644 versioned_docs/version-6.5/charts/TreeMap.md create mode 100644 versioned_docs/version-6.5/charts/VerticalLine.md create mode 100644 versioned_docs/version-6.5/charts/geo/BubbleMap.md create mode 100644 versioned_docs/version-6.5/charts/geo/Choropleth.md create mode 100644 versioned_docs/version-6.5/charts/geo/Introduction.md create mode 100644 versioned_docs/version-6.5/coloring/Colors.md create mode 100644 versioned_docs/version-6.5/coloring/Gradients.md create mode 100644 versioned_docs/version-6.5/coloring/Patterns.md create mode 100644 versioned_docs/version-6.5/coloring/tables/GWTMaterialColors.md create mode 100644 versioned_docs/version-6.5/coloring/tables/GoogleChartColors.md create mode 100644 versioned_docs/version-6.5/coloring/tables/HTMLColorsNames.md create mode 100644 versioned_docs/version-6.5/configuration/Animation.md create mode 100644 versioned_docs/version-6.5/configuration/Commons.md create mode 100644 versioned_docs/version-6.5/configuration/Datasets.md create mode 100644 versioned_docs/version-6.5/configuration/Elements.md create mode 100644 versioned_docs/version-6.5/configuration/FillerAndDecimation.md create mode 100644 versioned_docs/version-6.5/configuration/Interaction.md create mode 100644 versioned_docs/version-6.5/configuration/Layout.md create mode 100644 versioned_docs/version-6.5/configuration/Legend.md create mode 100644 versioned_docs/version-6.5/configuration/ScriptableOptions.md create mode 100644 versioned_docs/version-6.5/configuration/Subtitle.md create mode 100644 versioned_docs/version-6.5/configuration/Title.md create mode 100644 versioned_docs/version-6.5/configuration/Tooltip.md create mode 100644 versioned_docs/version-6.5/defaults/Defaults.md create mode 100644 versioned_docs/version-6.5/defaults/DefaultsCharts.md create mode 100644 versioned_docs/version-6.5/defaults/DefaultsScales.md create mode 100644 versioned_docs/version-6.5/extensions/Annotation.md create mode 100644 versioned_docs/version-6.5/extensions/DataLabels.md create mode 100644 versioned_docs/version-6.5/extensions/Extensions.md create mode 100644 versioned_docs/version-6.5/extensions/Gradient.md create mode 100644 versioned_docs/version-6.5/extensions/Labels.md create mode 100644 versioned_docs/version-6.5/extensions/Zoom.md create mode 100644 versioned_docs/version-6.5/getting-started/Building.md create mode 100644 versioned_docs/version-6.5/getting-started/GettingStarted.md create mode 100644 versioned_docs/version-6.5/getting-started/Integration.md create mode 100644 versioned_docs/version-6.5/intl/DateTimeFormat.md create mode 100644 versioned_docs/version-6.5/intl/Locale.md create mode 100644 versioned_docs/version-6.5/intl/NumberFormat.md create mode 100644 versioned_docs/version-6.5/plugins/BackgroundColor.md create mode 100644 versioned_docs/version-6.5/plugins/ColorSchemes.md create mode 100644 versioned_docs/version-6.5/plugins/Crosshair.md create mode 100644 versioned_docs/version-6.5/plugins/DatasetsItemsSelector.md create mode 100644 versioned_docs/version-6.5/plugins/HTMLLegend.md create mode 100644 versioned_docs/version-6.5/plugins/Import.md create mode 100644 versioned_docs/version-6.5/plugins/Plugins.md create mode 100644 versioned_docs/version-6.5/plugins/Pointer.md create mode 100644 versioned_docs/version-6.5/plugins/tables/ColorSchemeBrewer.md create mode 100644 versioned_docs/version-6.5/plugins/tables/ColorSchemeGwtMaterial.md create mode 100644 versioned_docs/version-6.5/plugins/tables/ColorSchemeOffice.md create mode 100644 versioned_docs/version-6.5/plugins/tables/ColorSchemeTableau.md create mode 100644 versioned_docs/version-6.5/utilities/AnnotationBuilder.md create mode 100644 versioned_docs/version-6.5/utilities/Javascript.md create mode 100644 versioned_docs/version-6.5/utilities/Toast.md create mode 100644 versioned_sidebars/version-6.5-sidebars.json diff --git a/docs/axes/Category.md b/docs/axes/Category.md index 76cb3f421..6372ec2ed 100644 --- a/docs/axes/Category.md +++ b/docs/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/docusaurus.config.js b/docusaurus.config.js index 4a8a91db4..ef565fb0a 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -91,7 +91,7 @@ module.exports = { lastVersion: 'current', versions: { current: { - label: '6.5', + label: '6.6', }, }, }, diff --git a/package.json b/package.json index 88e3231ee..f416f2d4c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "charba", - "version": "6.5.0", + "version": "6.6.0", "private": true, "scripts": { "docusaurus": "docusaurus", diff --git a/sidebars.js b/sidebars.js index fb0587a39..1bc2f5232 100644 --- a/sidebars.js +++ b/sidebars.js @@ -96,12 +96,12 @@ module.exports = { }, { "type": "link", - "href": "https://github.com/pepstock-org/Charba/releases/tag/6.5", + "href": "https://github.com/pepstock-org/Charba/releases/tag/6.6", "label": "Release note" }, { "type": "link", - "href": "https://pepstock-org.github.io/Charba/6.5/index.html", + "href": "https://pepstock-org.github.io/Charba/6.6/index.html", "label": "Javadoc API" } ], diff --git a/versioned_docs/version-6.0/axes/Category.md b/versioned_docs/version-6.0/axes/Category.md index eb61fa5fc..5067c7c83 100644 --- a/versioned_docs/version-6.0/axes/Category.md +++ b/versioned_docs/version-6.0/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.0/axes/Linear.md b/versioned_docs/version-6.0/axes/Linear.md index 882e8769e..17285b56c 100644 --- a/versioned_docs/version-6.0/axes/Linear.md +++ b/versioned_docs/version-6.0/axes/Linear.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.0/axes/Logarithmic.md b/versioned_docs/version-6.0/axes/Logarithmic.md index 13003c65b..0725dadf6 100644 --- a/versioned_docs/version-6.0/axes/Logarithmic.md +++ b/versioned_docs/version-6.0/axes/Logarithmic.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.0/axes/Radial.md b/versioned_docs/version-6.0/axes/Radial.md index f605ab8ad..3becd01a7 100644 --- a/versioned_docs/version-6.0/axes/Radial.md +++ b/versioned_docs/version-6.0/axes/Radial.md @@ -25,7 +25,7 @@ Here is an example how to create a radial axis: RadialAxis axis = new RadialAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.0/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): diff --git a/versioned_docs/version-6.0/axes/Time.md b/versioned_docs/version-6.0/axes/Time.md index 22407acee..30bb06025 100644 --- a/versioned_docs/version-6.0/axes/Time.md +++ b/versioned_docs/version-6.0/axes/Time.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.0/axes/TimeSeries.md b/versioned_docs/version-6.0/axes/TimeSeries.md index 9393fe497..283bc62eb 100644 --- a/versioned_docs/version-6.0/axes/TimeSeries.md +++ b/versioned_docs/version-6.0/axes/TimeSeries.md @@ -39,7 +39,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.0/charts/geo/BubbleMap.md b/versioned_docs/version-6.0/charts/geo/BubbleMap.md index d501f21d1..561b01f4e 100644 --- a/versioned_docs/version-6.0/charts/geo/BubbleMap.md +++ b/versioned_docs/version-6.0/charts/geo/BubbleMap.md @@ -206,7 +206,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -251,7 +251,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined SizeAxis axis = new SizeAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.0/charts/geo/Choropleth.md b/versioned_docs/version-6.0/charts/geo/Choropleth.md index 629ed0895..92eb19506 100644 --- a/versioned_docs/version-6.0/charts/geo/Choropleth.md +++ b/versioned_docs/version-6.0/charts/geo/Choropleth.md @@ -213,7 +213,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -262,7 +262,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ColorAxis axis = new ColorAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.1/axes/Category.md b/versioned_docs/version-6.1/axes/Category.md index 4513213e4..ee4c7f5cf 100644 --- a/versioned_docs/version-6.1/axes/Category.md +++ b/versioned_docs/version-6.1/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.1/axes/Linear.md b/versioned_docs/version-6.1/axes/Linear.md index aa33b4ee6..5e268d716 100644 --- a/versioned_docs/version-6.1/axes/Linear.md +++ b/versioned_docs/version-6.1/axes/Linear.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.1/axes/Logarithmic.md b/versioned_docs/version-6.1/axes/Logarithmic.md index 611cc1dbf..e49859d77 100644 --- a/versioned_docs/version-6.1/axes/Logarithmic.md +++ b/versioned_docs/version-6.1/axes/Logarithmic.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.1/axes/Radial.md b/versioned_docs/version-6.1/axes/Radial.md index 12e90ce10..708f5fec4 100644 --- a/versioned_docs/version-6.1/axes/Radial.md +++ b/versioned_docs/version-6.1/axes/Radial.md @@ -25,7 +25,7 @@ Here is an example how to create a radial axis: RadialAxis axis = new RadialAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.1/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): diff --git a/versioned_docs/version-6.1/axes/Time.md b/versioned_docs/version-6.1/axes/Time.md index a61536118..48a610916 100644 --- a/versioned_docs/version-6.1/axes/Time.md +++ b/versioned_docs/version-6.1/axes/Time.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.1/axes/TimeSeries.md b/versioned_docs/version-6.1/axes/TimeSeries.md index b69e6447e..19b2f99b5 100644 --- a/versioned_docs/version-6.1/axes/TimeSeries.md +++ b/versioned_docs/version-6.1/axes/TimeSeries.md @@ -39,7 +39,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.1/charts/geo/BubbleMap.md b/versioned_docs/version-6.1/charts/geo/BubbleMap.md index 6e367db2b..eaede763a 100644 --- a/versioned_docs/version-6.1/charts/geo/BubbleMap.md +++ b/versioned_docs/version-6.1/charts/geo/BubbleMap.md @@ -206,7 +206,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -251,7 +251,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined SizeAxis axis = new SizeAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.1/charts/geo/Choropleth.md b/versioned_docs/version-6.1/charts/geo/Choropleth.md index 6ab6456bf..240dba7c6 100644 --- a/versioned_docs/version-6.1/charts/geo/Choropleth.md +++ b/versioned_docs/version-6.1/charts/geo/Choropleth.md @@ -213,7 +213,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -262,7 +262,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ColorAxis axis = new ColorAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.2/axes/Category.md b/versioned_docs/version-6.2/axes/Category.md index 6370b9e7b..d63825429 100644 --- a/versioned_docs/version-6.2/axes/Category.md +++ b/versioned_docs/version-6.2/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.2/axes/Linear.md b/versioned_docs/version-6.2/axes/Linear.md index 3e84b67e6..0c4aa7697 100644 --- a/versioned_docs/version-6.2/axes/Linear.md +++ b/versioned_docs/version-6.2/axes/Linear.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.2/axes/Logarithmic.md b/versioned_docs/version-6.2/axes/Logarithmic.md index 772f42e93..cecf1aa46 100644 --- a/versioned_docs/version-6.2/axes/Logarithmic.md +++ b/versioned_docs/version-6.2/axes/Logarithmic.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.2/axes/Radial.md b/versioned_docs/version-6.2/axes/Radial.md index 10855ddaf..005ee4299 100644 --- a/versioned_docs/version-6.2/axes/Radial.md +++ b/versioned_docs/version-6.2/axes/Radial.md @@ -25,7 +25,7 @@ Here is an example how to create a radial axis: RadialAxis axis = new RadialAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.2/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): diff --git a/versioned_docs/version-6.2/axes/Time.md b/versioned_docs/version-6.2/axes/Time.md index 4fae87896..8efde9c93 100644 --- a/versioned_docs/version-6.2/axes/Time.md +++ b/versioned_docs/version-6.2/axes/Time.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.2/axes/TimeSeries.md b/versioned_docs/version-6.2/axes/TimeSeries.md index 6fe07531a..a75632534 100644 --- a/versioned_docs/version-6.2/axes/TimeSeries.md +++ b/versioned_docs/version-6.2/axes/TimeSeries.md @@ -39,7 +39,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.2/charts/geo/BubbleMap.md b/versioned_docs/version-6.2/charts/geo/BubbleMap.md index 0ee8cb0f1..25336804e 100644 --- a/versioned_docs/version-6.2/charts/geo/BubbleMap.md +++ b/versioned_docs/version-6.2/charts/geo/BubbleMap.md @@ -206,7 +206,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -251,7 +251,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined SizeAxis axis = new SizeAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.2/charts/geo/Choropleth.md b/versioned_docs/version-6.2/charts/geo/Choropleth.md index aaaf44a2c..6d9611ba6 100644 --- a/versioned_docs/version-6.2/charts/geo/Choropleth.md +++ b/versioned_docs/version-6.2/charts/geo/Choropleth.md @@ -213,7 +213,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -262,7 +262,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ColorAxis axis = new ColorAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.3/axes/Category.md b/versioned_docs/version-6.3/axes/Category.md index dd623d08c..702d19c43 100644 --- a/versioned_docs/version-6.3/axes/Category.md +++ b/versioned_docs/version-6.3/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.3/axes/Linear.md b/versioned_docs/version-6.3/axes/Linear.md index 2066bd64a..3c930d496 100644 --- a/versioned_docs/version-6.3/axes/Linear.md +++ b/versioned_docs/version-6.3/axes/Linear.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.3/axes/Logarithmic.md b/versioned_docs/version-6.3/axes/Logarithmic.md index a79f6eef0..9cd260698 100644 --- a/versioned_docs/version-6.3/axes/Logarithmic.md +++ b/versioned_docs/version-6.3/axes/Logarithmic.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.3/axes/Radial.md b/versioned_docs/version-6.3/axes/Radial.md index 0d36be693..c27e56bfa 100644 --- a/versioned_docs/version-6.3/axes/Radial.md +++ b/versioned_docs/version-6.3/axes/Radial.md @@ -25,7 +25,7 @@ Here is an example how to create a radial axis: RadialAxis axis = new RadialAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.3/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): diff --git a/versioned_docs/version-6.3/axes/Time.md b/versioned_docs/version-6.3/axes/Time.md index f0df6ce84..e475a6c3d 100644 --- a/versioned_docs/version-6.3/axes/Time.md +++ b/versioned_docs/version-6.3/axes/Time.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.3/axes/TimeSeries.md b/versioned_docs/version-6.3/axes/TimeSeries.md index 7510bf60b..39458ecd9 100644 --- a/versioned_docs/version-6.3/axes/TimeSeries.md +++ b/versioned_docs/version-6.3/axes/TimeSeries.md @@ -39,7 +39,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.3/charts/geo/BubbleMap.md b/versioned_docs/version-6.3/charts/geo/BubbleMap.md index 0caa45eb3..420ad2610 100644 --- a/versioned_docs/version-6.3/charts/geo/BubbleMap.md +++ b/versioned_docs/version-6.3/charts/geo/BubbleMap.md @@ -206,7 +206,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -251,7 +251,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined SizeAxis axis = new SizeAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.3/charts/geo/Choropleth.md b/versioned_docs/version-6.3/charts/geo/Choropleth.md index 85c551f92..164009fa6 100644 --- a/versioned_docs/version-6.3/charts/geo/Choropleth.md +++ b/versioned_docs/version-6.3/charts/geo/Choropleth.md @@ -213,7 +213,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -262,7 +262,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ColorAxis axis = new ColorAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.4/axes/Category.md b/versioned_docs/version-6.4/axes/Category.md index 9eca308ce..399d523a7 100644 --- a/versioned_docs/version-6.4/axes/Category.md +++ b/versioned_docs/version-6.4/axes/Category.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.4/axes/Linear.md b/versioned_docs/version-6.4/axes/Linear.md index a767de0dc..5842bca93 100644 --- a/versioned_docs/version-6.4/axes/Linear.md +++ b/versioned_docs/version-6.4/axes/Linear.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.4/axes/Logarithmic.md b/versioned_docs/version-6.4/axes/Logarithmic.md index cc9138498..469267ec3 100644 --- a/versioned_docs/version-6.4/axes/Logarithmic.md +++ b/versioned_docs/version-6.4/axes/Logarithmic.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Options diff --git a/versioned_docs/version-6.4/axes/Radial.md b/versioned_docs/version-6.4/axes/Radial.md index 9b52d56f2..065949ac2 100644 --- a/versioned_docs/version-6.4/axes/Radial.md +++ b/versioned_docs/version-6.4/axes/Radial.md @@ -25,7 +25,7 @@ Here is an example how to create a radial axis: RadialAxis axis = new RadialAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.4/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): diff --git a/versioned_docs/version-6.4/axes/Time.md b/versioned_docs/version-6.4/axes/Time.md index 490509d1a..c94b136e6 100644 --- a/versioned_docs/version-6.4/axes/Time.md +++ b/versioned_docs/version-6.4/axes/Time.md @@ -35,7 +35,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.4/axes/TimeSeries.md b/versioned_docs/version-6.4/axes/TimeSeries.md index fa82c3b1c..6b23856f2 100644 --- a/versioned_docs/version-6.4/axes/TimeSeries.md +++ b/versioned_docs/version-6.4/axes/TimeSeries.md @@ -39,7 +39,7 @@ ScaleId myAxis = ScaleId.create("my-axis"); CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); // adds axes to chart configuration -chart.getOptions().setAxes(axis1, ...); +chart.getOptions().getScales().setAxes((axis1, ...); ``` ## Datasets diff --git a/versioned_docs/version-6.4/charts/geo/BubbleMap.md b/versioned_docs/version-6.4/charts/geo/BubbleMap.md index fbb4fed05..a09b210a1 100644 --- a/versioned_docs/version-6.4/charts/geo/BubbleMap.md +++ b/versioned_docs/version-6.4/charts/geo/BubbleMap.md @@ -206,7 +206,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -251,7 +251,7 @@ BubbleMapChart chart = new BubbleMapChart(); // scale id and axis kind are already defined SizeAxis axis = new SizeAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.4/charts/geo/Choropleth.md b/versioned_docs/version-6.4/charts/geo/Choropleth.md index 0be81beee..c909c96f6 100644 --- a/versioned_docs/version-6.4/charts/geo/Choropleth.md +++ b/versioned_docs/version-6.4/charts/geo/Choropleth.md @@ -213,7 +213,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ProjectionAxis axis = new ProjectionAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options @@ -262,7 +262,7 @@ ChoroplethChart chart = new ChoroplethChart(); // scale id and axis kind are already defined ColorAxis axis = new ColorAxis(chart); // adds axes to chart configuration -chart.getOptions().setAxes(axis); +chart.getOptions().getScales().setAxes((axis); ``` #### Options diff --git a/versioned_docs/version-6.5/Controllers.md b/versioned_docs/version-6.5/Controllers.md new file mode 100644 index 000000000..8bf455ce6 --- /dev/null +++ b/versioned_docs/version-6.5/Controllers.md @@ -0,0 +1,484 @@ +--- +id: Controllers +title: Controllers +hide_title: true +sidebar_label: Controllers +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Controllers + +Controllers are able to extend existing chart types or creating new one implementing a specific interface. Leveraging on [Chart.JS](http://www.chartjs.org/) implementation, **Charba** provides the features to extend a controller. + + + +:::caution +[Chart.JS controller](https://www.chartjs.org/docs/latest/developers/charts.html) provides as set of hooks to create an own controller but you should implement all internal structure which is not fully documented and depends on each implementation.
+For this reason, **Charba** provides the interfaces to create controllers **ONLY** extending existing chart types. +::: + +## Creating a controller + +To create own chart type, you need to perform some specific and mandatory steps: + + 1. create a [controller type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/controllers/ControllerType.html) + 2. implement the [controller](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html) interface where all hooks are defined + 3. extend the [dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Dataset.html) class of the original chart type + 4. extend the [chart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) class of the original chart type + +### Creating a controller type + +Controllers must define a unique id in order to be configurable. + +This id should follow the name convention (otherwise an [illegal argument](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/IllegalArgumentException.html) exception will be thrown): + + * can not start with a dot or an underscore + * can not contain any non-URL-safe characters + +The [controller type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/controllers/ControllerType.html) is an entity which must be implemented for every controller you want to implement. A controller type implements [Type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Type.html) interface like all other chart types available out-of-the-box. + +Here are the way how to create a controller type: + +```java +// creates a chart extending the existing chart LINE +ControllerType myLine = new ControllerType("myline", ChartType.LINE, new ControllerProvider(){ + + @Override + public Controller provide(ControllerType controllerType){ + // creates an instance of my controller + return myController; + } + +}); +``` + +The controller type constructor is getting a [controller provider](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/controllers/ControllerProvider.html) instance as argument in order to provide the controller during the registration. + +The controller is usually automatically registered in [Chart.JS](http://www.chartjs.org/) when used. Anyway the controller type object is providing the method to **register** the controller programmatically in [Chart.JS](http://www.chartjs.org/): + +```java +// registers the controller in CHART.JS +myControllerType.register(); +``` + +You can also be notified when and if the registration of the controller ended correctly. This is done by the implementation of [ControllerRegistrationHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/controllers/ControllerRegistrationHandler.html) interface to set during the controller type creation. + +```java +// creates a chart extending the existing chart LINE +ControllerType myLine = new ControllerType("myline", ChartType.LINE, myControllerProvider, + + new ControllerRegistrationHandler { + /** + * Invoked before the controller will be register to CHART.JS. + * + * @param controllerType the controller type which is registering + */ + @Override + public void onBeforeRegister(ControllerType controllerType) { + // invoked before registration + } + + /** + * Invoked after the controller is registered to CHART.JS. + * + * @param controllerType the controller type which is registering + * @param registered true if the controller has been registered otherwise false + */ + @Override + public void onAfterRegister(ControllerType controllerType, boolean registered) { + // invoked after registration + // with the status, if was registered or not. + } + } +}); +``` + +### Hooks + +A controller must implement the [Controller](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html) interface which is containing all hooks which will be invoked during the whole chart life cycle. + +The interface provides **before** and **after** hooks for each phases exposes by [Chart.JS controller](https://www.chartjs.org/docs/4.4.1/developers/charts.html): + +#### Initialization + +Every controller is initialized every time new chart instance is creating. + +The following hooks (the following ones are the methods definitions in the [Controller](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html)) can be used to initialize the chart: + +```java +/** + * Called before it initializes the controller. + * + * @param context context of controller + * @param chart chart instance + */ +default void onBeforeInitialize(ControllerContext context, IsChart chart) { + // do nothing +} + +/** + * Called after it initializes the controller. + * + * @param context context of controller + * @param chart chart instance + */ +default void onAfterInitialize(ControllerContext context, IsChart chart) { + // do nothing +} +``` + +The initialization process is documented in the flowchart below. + +```mermaid +flowchart TD + A((Begin init)) --> B(Notify onBeforeInitialize) + B --> C[Initialize new Chart] + C --> D(Notify onAfterInitialize) + D --> E((End init)) + style A fill:#FFF2CC,stroke:#D6B656 + style B fill:#D5E8D4,stroke:#82B366 + style C fill:#FFFFFF,stroke:#000000 + style D fill:#D5E8D4,stroke:#82B366 + style E fill:#FFF2CC,stroke:#D6B656 + click B href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onBeforeInitialize(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onBeforeInitialize" _blank + click D href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onAfterInitialize(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onAfterInitialize" _blank +``` + +#### Rendering + +Every controller can be rendered after [initialization](#initialization) and every time that the chart instance will be updated or rendered. + +They are 4 main phases: + + * Linking of scale ensures that the data set represented by a controller is linked to a scale. + +```java +/** + * Called before it ensures that the data set represented by a controller is linked to a scale. + * + * @param context context of controller + * @param chart chart instance + */ +default void onBeforeLinkScales(ControllerContext context, IsChart chart) { + // do nothing +} + +/** + * Called after it ensures that the data set represented by a controller is linked to a scale. + * + * @param context context of controller + * @param chart chart instance + */ +default void onAfterLinkScales(ControllerContext context, IsChart chart) { + // do nothing +} +``` + + * Parsing the data into the controller meta data. + +```java +/** + * Called before it invokes to parse the data into the controller meta data. + * + * @param context context of controller + * @param chart chart instance + * @param start start index of metadata + * @param count count of metadata + */ +default void onBeforeParse(ControllerContext context, IsChart chart, int start, int count) { + // do nothing +} + +/** + * Called after it invokes to parse the data into the controller meta data. + * + * @param context context of controller + * @param chart chart instance + * @param start start index of metadata + * @param count count of metadata + */ +default void onAfterParse(ControllerContext context, IsChart chart, int start, int count) { + // do nothing +} +``` + + * Updating the elements in response to new data. + +```java +/** + * Called before it updates the elements in response to new data. + * + * @param context context of controller + * @param chart chart instance + * @param mode update mode + */ +default void onBeforeUpdate(ControllerContext context, IsChart chart, TransitionMode mode) { + // do nothing +} + +/** + * Called after it updates the elements in response to new data. + * + * @param context context of controller + * @param chart chart instance + * @param mode update mode + */ +default void onAfterUpdate(ControllerContext context, IsChart chart, TransitionMode mode) { + // do nothing +} +``` + + * Drawing the representation of the data set. + +```java +/** + * Called before it draws the representation of the data set. + * + * @param context context of controller + * @param chart chart instance + */ +default void onBeforeDraw(ControllerContext context, IsChart chart) { + // do nothing +} + +/** + * Called after it draws the representation of the data set. + * + * @param context context of controller + * @param chart chart instance + */ +default void onAfterDraw(ControllerContext context, IsChart chart) { + // do nothing +} +``` + +The rendering process is documented in the flowchart below. + +```mermaid +flowchart TD + A((Begin render)) --> B{Has
scales?} + B --> |yes| C(Notify onBeforeLinkScales) + B --> |no| G{Has
datasets?} + C --> D[Links scale] + D --> E(Notify onAfterLinkScales) + E --> F{Scales
remaining?} + F --> |yes| B + F --> |no| G + G --> |yes|H(Notify onBeforeParse) + G --> |no| O(Notify onBeforeUpdate) + H --> I[Parse metadata] + I --> L(Notify onAfterParse) + L --> M{Datasets
remaining?} + M --> |yes| H + M --> |no| O + O --> P[Update chart] + P --> Q(Notify onAfterUpdate) + Q --> R(Notify onBeforeDraw) + R --> S[Render chart] + S --> T(Notify onAfterDraw) + T --> U{Frames
remaining?} + U --> |yes| R + U --> |no| V((End render)) + style A fill:#FFF2CC,stroke:#D6B656 + style B fill:#FFFFFF,stroke:#000000 + style C fill:#D5E8D4,stroke:#82B366 + style D fill:#FFFFFF,stroke:#000000 + style E fill:#D5E8D4,stroke:#82B366 + style F fill:#FFFFFF,stroke:#000000 + style G fill:#FFFFFF,stroke:#000000 + style H fill:#D5E8D4,stroke:#82B366 + style I fill:#FFFFFF,stroke:#000000 + style L fill:#D5E8D4,stroke:#82B366 + style M fill:#FFFFFF,stroke:#000000 + style P fill:#FFFFFF,stroke:#000000 + style Q fill:#D5E8D4,stroke:#82B366 + style O fill:#D5E8D4,stroke:#82B366 + style R fill:#D5E8D4,stroke:#82B366 + style S fill:#FFFFFF,stroke:#000000 + style T fill:#D5E8D4,stroke:#82B366 + style U fill:#FFFFFF,stroke:#000000 + style V fill:#FFF2CC,stroke:#D6B656 + click C href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onBeforeLinkScales(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onBeforeLinkScales" _blank + click E href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onAfterLinkScales(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onAfterLinkScales" _blank + click H href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onBeforeParse(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart,int,int)" "onBeforeParse" _blank + click O href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onBeforeUpdate(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart,org.pepstock.charba.client.options.TransitionMode)" "onBeforeUpdate" _blank + click L href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onAfterParse(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart,int,int)" "onAfterParse" _blank + click Q href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onAfterUpdate(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart,org.pepstock.charba.client.options.TransitionMode)" "onAfterUpdate" _blank + click R href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onBeforeDraw(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onBeforeDraw" _blank + click T href "https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Controller.html#onAfterDraw(org.pepstock.charba.client.controllers.ControllerContext,org.pepstock.charba.client.IsChart)" "onAfterDraw" _blank +``` + +### Implementing a controller + +The easy way to implement a controller is to extends the [AbstractController](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/controllers/AbstractController.html) class and pass the controller type by the constructor. + +```java +// new controller +public class MyHorizontalBarController extends AbstractController { + + // controller type + public static final ControllerType TYPE = new ControllerType("myHorizontalBar", + ChartType.BAR, + controllerType) -> new MyHorizontalBarController()); + + // constructor + public MyHorizontalBarController() { + super(TYPE); + } + +} +``` + +### Extending existing dataset + +To use new controller in **Charba**, you need to implement a dataset object extending the dataset class of your original chart type of the controller. + +This is mandatory because [Chart.JS](http://www.chartjs.org/) needs to manage the different types of datasets. + +See the following example: + +```java +// extends the horizontal bar dataset +public final class MyHorizontalBarDataset extends HorizontalBarDataset { + + // extends the constructor of the horizontal bar dataset + public MyHorizontalBarDataset(){ + super(MyHorizontalBarController.TYPE, Dataset.DEFAULT_HIDDEN); + } + +} +``` + +### Extending existing chart + +To use new controller in **Charba**, you need to implement a chart object extending the chart class of your original chart type of the controller. + +See the following example: + +```java +// extends the horizontal bar chart +public class MyHorizontalBarChart extends HorizontalBarChart{ + + // extends the constructor of the horizontal bar chart + public MyHorizontalBarChart(){ + super(MyHorizontalBarController.TYPE); + } + + @Override + public MyHorizontalBarDataset newDataset(){ + return new MyHorizontalBarDataset(); + } + + @Override + public MyHorizontalBarDataset newDataset(boolean hidden){ + return new MyHorizontalBarDataset(); + } + +} +``` + +:::caution +You can not set new properties for the controller options in the global or chart type default, only at chart instance. +::: + + +## A simple example + +The usage of a controller is to extend an existing chart and change the behavior of it. + +The controller is implementing the behavior but you should extend the current chart (for instance line) extending line chart. + + + +Here is an example. + +```java +// ----------------------------------------- +// Creates the chart class of "myLine" chart +// ----------------------------------------- +// extends the line chart +public class MyLineChart extends LineChart { + + // ----------------------------------------- + // Creates the "myLine" controller type + // ----------------------------------------- + public static final ControllerType TYPE = new ControllerType("myLine", ChartType.LINE, + new ControllerProvider(){ + + @Override + public Controller provide(ControllerType controllerType){ + // ----------------------------------------- + // Creates the "myLine" controller + // ----------------------------------------- + return new AbstractController(){ + + @Override + public ControllerType getType(){ + return MyLineChart.TYPE; + } + + @Override + public void draw(ControllerContext jsThis, IsChart chart){ + super.draw(jsThis, chart); + + DatasetItem item = chart.getDatasetItem(jsThis.getIndex()); + + List elements = item.getElements(); + for (ChartElement elem : elements){ + if (elem instanceof PointElement) { + PointElement pointElement = (PointElement) elem; + Context2dItem ctx = chart.getCanvas().getContext2d(); + ctx.save(); + ctx.setStrokeColor(pointElement.getOptions().getBorderColorAsString()); + ctx.setLineWidth(1D); + ctx.strokeRect(elem.getX() - 10, elem.getY() - 10, 20, 20); + ctx.restore(); + } + } + } + }; + } + } + ); + + public MyLineChart(){ + super(TYPE); + } + + @Override + public MyLineDataset newDataset(){ + return newDataset(false); + } + + @Override + public MyLineDataset newDataset(boolean hidden){ + return new MyLineDataset(); + } +} +// ----------------------------------------- +// Creates the dataset class of "myLine" chart +// ----------------------------------------- +public final class MyLineDataset extends LineDataset { + + public MyLineDataset(){ + super(MyLineChart.TYPE, Dataset.DEFAULT_HIDDEN); + } + +} +// ----------------------------------------- +// Registers "myLine" controller +// ----------------------------------------- +MyLineChart.TYPE.register(); +// ----------------------------------------- +// Creates "myLine" chart +// ----------------------------------------- +// creates the chart +MyLineChart chart = new MyLineChart(); +// creates the dataset +MyLineDataset dataset = chart.newDataset(); +dataset.setLabel("dataset 1"); +... +chart.getData().setDatasets(dataset); +// add to DOM by Elemental 2 +DomGlobal.document.body.appendChild(chart.getChartElement().as()); +``` diff --git a/versioned_docs/version-6.5/DateAdapters.md b/versioned_docs/version-6.5/DateAdapters.md new file mode 100644 index 000000000..e40b777f5 --- /dev/null +++ b/versioned_docs/version-6.5/DateAdapters.md @@ -0,0 +1,81 @@ +--- +id: DateAdapters +title: Date adapters +hide_title: true +sidebar_label: Date adapters +--- +## Date adapters + +The [Chart.JS](http://www.chartjs.org/) time and time series scale requires both a date library and corresponding adapter to be present. + +[Chart.JS](http://www.chartjs.org/) is providing the integration with 3 date libraries, but **Charba** is implementing the integration with **[Luxon](https://moment.github.io/luxon/)** date library. +The adoption of [Luxon](https://moment.github.io/luxon/) is justified because is completely based on [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API. + +See **Charba** [enabling documentation](./getting-started/GettingStarted#embedded-resources) to have more details how to embed or not [Luxon](https://moment.github.io/luxon/) date library. + +## Luxon + +[Luxon](https://moment.github.io/luxon/) is a powerful, modern, and friendly wrapper for java-script dates and times. + +[Luxon](https://moment.github.io/luxon/) uses the native [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API to provide easy-to-use internationalization. + +These are the defaults that the library implements that you can change in the cartesian time axis. + +| Name | Default | Example +| :- | :- | :- +| millisecond | h:mm:ss.SSS a | 7:26:39.413 PM +| second | h:mm:ss a | 7:26:39 PM +| minute | h:mm a | 7:26 PM +| hour | ha | 7PM +| day | MMM d | Feb 19 +| week | W yyyy | 8 2020 +| month | MMM yyyy | Feb 2020 +| quarter | 'Q'q - yyyy | Q1 - 2020 +| year | yyyy | 2020 + +To see all available formats, have a look [here](https://moment.github.io/luxon/#/formatting?id=table-of-tokens) in the **Luxon** documentation. + +[Luxon](https://moment.github.io/luxon/) can be configured in order to update some behavior during parsing, formatting and date management. + +The [Luxon options](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/adapters/DateAdapterOptions.html) can be used as following: + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the locale to date adapter options +axis.getAdapters().getDate().setLocale(CLocale.US); + +CLocale locale = axis.getAdapters().getDate().getLocale(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | `null` | Using locale specifying the language to use generating or interpreting strings. +| zone | [TimeZone](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/TimeZone.html) | `null` | Implementation recognizes the time zone names of the IANA time zone database. +| outputCalendar | [Calendar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/Calendar.html) | `null` | The calendar type to use. +| numberingSystem | [NumberingSystem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/NumberingSystem.html) | `null` | The numbering system to use. + +For more details, have a look how to configure [time axes adapters](./axes/CartesianTimeAxes#adapters) and the [INTL locale](./intl/Locale) documentation. + +## Using the date adapter + +**Charba** enables the possibility to get a [date adapter](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/adapters/DateAdapter.html) instance from [Chart.JS](http://www.chartjs.org/) which can provides some capabilities, like formatting, parsing and date operations. + +Here is an example how to use a [date adapter](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/adapters/DateAdapter.html) to format ticks by callback: + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets tick callback +axis.getTicks().setCallback(new TimeTickCallback(){ + + private DateAdapter adapter = new DateAdapter(); + + @Override + public String onCallback(Axis axis, Date value, String label, int index, List values){ + return adapter.format(value, "yyyy"); + } +}); +``` diff --git a/versioned_docs/version-6.5/Home.md b/versioned_docs/version-6.5/Home.md new file mode 100644 index 000000000..049ed8d92 --- /dev/null +++ b/versioned_docs/version-6.5/Home.md @@ -0,0 +1,18 @@ +--- +id: Home +title: Charba - J2CL and GWT Charts library based on CHART.JS +hide_title: true +sidebar_label: Home +slug: / +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + + + + + + + + + +
diff --git a/versioned_docs/version-6.5/Overview.md b/versioned_docs/version-6.5/Overview.md new file mode 100644 index 000000000..915b064ac --- /dev/null +++ b/versioned_docs/version-6.5/Overview.md @@ -0,0 +1,127 @@ +--- +id: Overview +title: Overview +hide_title: true +sidebar_label: Overview +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Why Charba + +[GWT Web toolkit](http://www.gwtproject.org/) doesn't have any out of the box charting library. + +There are some open source charting libraries for GWT available to be used but with some constraints or unclear items: + + * internet connection needed + * open source license not completely clear, sometimes with some obligations like to add specific labels + * old packages not longer maintained + +[Google Charts](https://developers.google.com/chart/interactive/docs/reference) tools are powerful, simple to use, and free. Unfortunately if you see the terms of service in the [support](https://developers.google.com/chart/interactive/faq) section, you can read that you can NOT use it in offline mode. + +``` +Can I use charts offline? + +Your users' computers must have access to https://www.gstatic.com/charts/loader.js +in order to use the interactive features of Google Charts. This is because the +visualization libraries that your page requires are loaded dynamically before you +use them. +The code for loading the appropriate library is part of the included script, and +is called when you invoke the google.charts.load() method. Our terms of service do +not allow you to download the google.charts.load or google.visualization code to +use offline. + +Can I download and host the chart code locally, or on an intranet? + +Sorry; our terms of service do not allow you to download and save or host the +google.charts.load or google.visualization code. +However, if you don't need the interactivity of Google Charts, you can screenshot +the charts and use them as you wish. +``` + +Other open-source libraries which provide charts for [GWT Web toolkit](http://www.gwtproject.org/) have got sentences like the following one (even if they are available under open-source license): + +``` + If you like this software and intend to use it we'd appreciate you letting us + know, and possibly adding a link or reference back to our site. +``` + +For all these reasons, **Charba** has been developed. + +We spent time to evaluate some open-source charts javascript libraries and finally we landed on [Chart.JS](http://www.chartjs.org/). + +Why? + +Because it's simple, clean and user-friendly. Perfect words to describe the [Chart.JS](http://www.chartjs.org/) library. + +The [Chart.JS](http://www.chartjs.org/) library is an HTML5 based JavaScript library for creating animated, interactive and customizable charts and graphs. With [Chart.JS](http://www.chartjs.org/), you can easily get to visualize your mixed chart types without hassle, creating responsive web pages by default. + +Even if **Charba** was born only as GWT library, as of version **3**, **Charba** has been changed in order to be used not only in GWT but also with other DOM frameworks, base on [J2CL - JavaToClosure](https://github.com/google/j2cl), like [Google Elemental2](https://github.com/google/elemental2) or [Elemento](https://github.com/hal/elemento). + +As of version **3**, **Charba** has got an own DOM tree manager which allows to be independent from any other DOM tree manager (i.e. GWT, Elemental2 or Elemento) and it is providing a set of hooks in order to be use over those frameworks as well. + + + +## Features + +**Charba** has implemented almost all [Chart.JS](http://www.chartjs.org/) features, as following: + + * Default global options and scale, chart and scale options + * All [charts types](http://www.chartjs.org/docs/latest/charts/) + * Line + * Bar (and horizontal Bar) + * Radar + * Polar area + * Doughnut + * Pie + * Bubble + * Scatter + * Area + * All [options](http://www.chartjs.org/docs/latest/configuration/) items + * Animation + * Layout + * Legend + * Title + * Tooltip + * Element + * Events + * All [axes](http://www.chartjs.org/docs/latest/axes/) elements (with all configuration items for labelling and styling) + * Cartesian (linear, logarithmic, category, time, timeseries) + * Radial (linear) + * Charts [API](http://www.chartjs.org/docs/latest/developers/api.html) + * All [plugins](http://www.chartjs.org/docs/latest/developers/plugins.html) capabilities + * Date adapters capabilities + * [Controller](https://www.chartjs.org/docs/latest/developers/charts.html) capabilities to extend existing chart by own chart types. + * Some [Chart.JS](http://www.chartjs.org/) plugins, provided as **Charba** extensions: + * [Annotation](https://github.com/chartjs/chartjs-plugin-annotation) which draws lines and boxes on the chart area. + * [DataLabels](https://github.com/chartjs/chartjs-plugin-datalabels) which is a highly customizable plugin that displays labels on data for any type of charts. + * [Gradient](https://github.com/kurkle/chartjs-plugin-gradient) which is a light weight plugin to apply gradients to the datasets by data values. + * [Labels](https://github.com/emn178/chartjs-plugin-labels) which is a light weight plugin to display labels on pie, doughnut and polar area chart. Original PieceLabel. + * [Zoom](https://github.com/chartjs/chartjs-plugin-zoom) which enables zooming and panning on chart. + * Some [Chart.JS](http://www.chartjs.org/) controllers, provided as **Charba** extensions: + * [Chart.js Geo](https://github.com/sgratzl/chartjs-chart-geo) which enables charting maps with legends, adding new chart types, choropleth and bubbleMap. + * [Chart.js Treemap](https://github.com/kurkle/chartjs-chart-treemap) which enables treemap charts. + * [Chart.js Matrix](https://github.com/kurkle/chartjs-chart-matrix) which enables matrix charts. + * [Chart.js Sankey](https://github.com/kurkle/chartjs-chart-sankey) which enables a type of flow diagram in which the width of the arrows is proportional to the flow rate. + +## Out-of-the-box + +**Charba** has implemented some out-of-the-box features, leveraging on [Chart.JS](http://www.chartjs.org/) features, mentioned above: + + * Charts (by controllers) + * Meter + * Gauge + * Tiles builder to create patterns + * Plugins + * Chart background color + * Chart cursor pointer to change cursor hovering chart elements + * Chart dataset items selector (for drill down and zooming) + * Color schemes which enables to pick the color combination for charts from the predefined or custom schemes + * HTML legend to create own legend changing styles and multiple lines + * Crosshair to show a crosshair and relative axes values on the chart. + * Callbacks + * Tick callback to define the amount of decimals digits of the axis number values when all datasets are hidden + * Legend callback to avoid to hide all datasets + * Datalabels listeners callback to change cursor hovering the labels + * Datalabels listeners callback to select the labels, leveraging on [DatasetSelectionEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/DatasetSelectionEventHandler.html) + * Datalabels formatter callback to return the percentage as value to show in the chart + diff --git a/versioned_docs/version-6.5/Regressions.md b/versioned_docs/version-6.5/Regressions.md new file mode 100644 index 000000000..2972a2a10 --- /dev/null +++ b/versioned_docs/version-6.5/Regressions.md @@ -0,0 +1,399 @@ +--- +id: Regressions +title: Regressions +hide_title: true +sidebar_label: Regressions +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Regressions + +(quoted from [Regression analysis](https://en.wikipedia.org/wiki/Regression_analysis) definition in Wikipedia) + +Regression analysis is a set of statistical processes for estimating the relationships between a dependent variable (often called the 'outcome' or 'response' variable) and one or more independent variables (often called 'predictors', 'covariates', 'explanatory variables' or 'features'). + +The most common form of regression analysis is linear regression, in which one finds the line (or a more complex linear combination) that most closely fits the data according to a specific mathematical criterion. + +Regression analysis is primarily used for two conceptually distinct purposes. + + 1. regression analysis is widely used for prediction and forecasting, where its use has substantial overlap with the field of machine learning. + 2. in some situations regression analysis can be used to infer causal relationships between the independent and dependent variables. Importantly, regressions by themselves only reveal relationships between a dependent variable and a collection of independent variables in a fixed dataset. To use regressions for prediction or to infer causal relationships, respectively, a researcher must carefully justify why existing relationships have predictive power for a new context or why a relationship between two variables has a causal interpretation. The latter is especially important when researchers hope to estimate causal relationships using observational data. + + + +
+
+ +**Charba** provides out of the box the feature to enable regressions leveraging on [ML regression library](https://github.com/mljs/ml). + +**Charba** provides the following regressions models: + + * Simple linear regression. + * Power regression. + * Exponential regression. + * Polynomial regression. + * Robust polynomial regression. + * TheilSen regression. + +The regressions feature is *native javascript* implementation and **Charba** provides the wrapper in order to be able to use it. + +:::info +The regression utility can be used even if the [**Charba.enable**](./getting-started/GettingStarted#embedded-resources) or [**DeferredCharba.enable**](./getting-started/GettingStarted#deferred-resources) are not called because it doesn't depend on CHART.JS. +::: + + +### Prediction + +All regression instances can predict Y values by a single or a list of X values: + +```java +// creates samples +List x = Arrays.asList(0.5D, 1D, 1.5D, 2D, 2.5D); +List y = Arrays.asList(0D, 1D, 2D, 3D, 4D); +// creates regression +LinearRegression regression = RegressionBuilder.create(x, y).buildLinearRegression(); +// predicts the Y value with x = 3 +Console.log(regression.predict(3)); // emit "5" +``` + +### Formula + +All regression instances can show the formula which represents the regression model: + +```java +// creates samples +List x = Arrays.asList(0.5D, 1D, 1.5D, 2D, 2.5D); +List y = Arrays.asList(0D, 1D, 2D, 3D, 4D); +// creates regression +LinearRegression regression = RegressionBuilder.create(x, y).buildLinearRegression(); +// shows formula +Console.log(regression.toFormula()); // emit "f(x) = 2 * x - 1" +// shows formula, with precision +Console.log(regression.toFormula(3)); // emit "f(x) = 2.00 * x - 1.00" +``` + +### Score + +The [regression score](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionScore.html) provides the estimation and inference in the regressions. It can provide some methods which differ in computational simplicity of algorithms, presence of a closed-form solution, robustness with respect to heavy-tailed distributions, and theoretical assumptions needed to validate desirable statistical properties such as consistency and asymptotic efficiency. + +The [regression score](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionScore.html) provides: + + * **R (R)**, which is the proportion of variation in the outcome that is explained by the predictor variables. In multiple regression models, R corresponds to the correlation between the observed outcome values and the predicted values by the model. The higher the _R_, the better the model + * **R-squared (R2)**, which is the proportion of variation in the outcome that is explained by the predictor variables. In multiple regression models, _R2_ corresponds to the squared correlation between the observed outcome values and the predicted values by the model. The Higher the R-squared, the better the model + * **Pearson's chi-squared (Chi2)**, which is the sum of differences between observed and expected outcome frequencies (that is, counts of observations), each squared and divided by the expectation + * **Root Mean Squared Error (RMSD)**, which measures the average error performed by the model in predicting the outcome for an observation. Mathematically, the RMSE is the square root of the mean squared error (MSE), which is the average squared difference between the observed actual outcome values and the values predicted by the model + +```java +// creates samples +List x = Arrays.asList(0.5D, 1D, 1.5D, 2D, 2.5D); +List y = Arrays.asList(0D, 1D, 2D, 3D, 4D); +// creates regression +LinearRegression regression = RegressionBuilder.create(x, y).buildLinearRegression(); +// calculates the score +RegressionScore score = regression.score(x, y); +// shows R +Console.log(score.getR()); // emit 1 +// shows R2 +Console.log(score.getR2()); // emit 1 +// shows Chi2 +Console.log(score.getChi2()); // emit 0 +// shows Rmsd +Console.log(score.getRmsd()); // emit 0 +``` + +### Using regressions on charts + +The provided regression instances can be used separately from charts or can be used in order to add to the chart a specific dataset with the predicted data. + +To create a specific [regression dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionDataset.html), which is an extended [line dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/LineDataset.html), **Charba** provides a specific builder in order to create the dataset which is created implementing a regression. + +```java +// creates chart +LineChart chart = new LineChart(); +// creates data set for chart +LineDataset dataset = chart.newDataset(); +// data points list instance +List dataPoints = new LinkedList<>(); +// loads data points +... +// sets the data points to chart dataset +dataset.setDataPoints(dataPoints); + +// creates a regression dataset +// using a list of samples by data points +// and creating a linear regression +// and loads the samples as data of dataset +RegressionDataset trend = RegressionDatasetBuilder.create() + .setSamplesByDataPoints(dataPoints) + .buildLinearRegression(); +// sets label +trend.setLabel("Linear trend"); +// sets dataset options +... +// adds datasets to chart +chart.getData().setDatasets(dataset, trend); +``` + + + +
+
+ +A regression [regression dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionDataset.html) can also be used to add a forecast line to show in the chart. + +```java +// creates chart +LineChart chart = new LineChart(); +// creates data set for chart +LineDataset dataset = chart.newDataset(); +// data points list instance +List dataPoints = new LinkedList<>(); +// loads data points +... +// sets the data points to chart dataset +dataset.setDataPoints(dataPoints); + +// creates a regression dataset +// using a list of samples by data points +// and creating a linear regression +// and loads the samples as data of dataset +RegressionDataset trend = RegressionDatasetBuilder.create() + .setSamplesByDataPoints(dataPoints) + .buildLinearRegression(); +// sets label +trend.setLabel("Linear trend"); +// sets dataset options +... +// creates the forecast dataset +// cloning an existing regression dataset set +// and leveraging on already calculated regression +RegressionDataset forecast = RegressionDatasetBuilder.build(trend); +// predicts the values adding a list of dates +// which are representing the X values +forecast.addXDates(forecastDates); +// sets label +forecast.setLabel("Linear forecast"); +// sets dataset options +... +// adds datasets to chart +chart.getData().setDatasets(dataset, trend, forecast); +``` + + + +
+
+ +## Simple linear + +(quoted from [Simple linear regression](https://en.wikipedia.org/wiki/Simple_linear_regression) definition in Wikipedia) + +Simple linear regression is a linear regression model with a single explanatory variable. That is, it concerns two-dimensional sample points with one independent variable and one dependent variable (conventionally, the x and y coordinates in a Cartesian coordinate system) and finds a linear function (a non-vertical straight line) that, as accurately as possible, predicts the dependent variable values as a function of the independent variable. The adjective simple refers to the fact that the outcome variable is related to a single predictor. + +It is common to make the additional stipulation that the ordinary least squares (OLS) method should be used: the accuracy of each predicted value is measured by its squared residual (vertical distance between the point of the data set and the fitted line), and the goal is to make the sum of these squared deviations as small as possible. + +The simple linear regression model can be represented using the below equation: +
+y = a0 + a1x +
+
+ + + +
+
+ +#### Creating a linear regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create a [simple linear regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/LinearRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(0.5D, 1D, 1.5D, 2D, 2.5D); +List y = Arrays.asList(0D, 1D, 2D, 3D, 4D); +// creates regression +LinearRegression regression = RegressionBuilder.create(x, y).buildLinearRegression(); +// coefficients +Console.log(regression.getSlope()); // emit 2 +Console.log(regression.getIntercept()); // emit -1 +Console.log(regression.getCoefficients().toString()); // emit [-1, 2] +// predicts the Y value with x = 3 +Console.log(regression.predict(3)); // emit 5 +// computes the X value with Y = 3.5 +Console.log(regression.computeX(3.5)); // emit 2.25 +``` + +## Power + +Power regression is a generalized linear model form of regression analysis used to model count data and contingency tables. It assumes the logarithm of its expected value can be modeled by a linear combination of unknown parameters. + +Power regression is a non-linear regression technique that looks like this: +
+y = A * xB +
+
+ + + +
+
+ +#### Creating a power regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create a [power regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/PowerRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(1D, 2D, 3D, 4D, 5D, 6D, 7D, 8D, 9D, 10D, 11D, 12D); +List y = Arrays.asList(159.9, 320.9, 326.8, 329.9, 360.6, 361.6, 361.7, 367.6, 374.1, 375.2, 376.7, 400.2); +// creates regression +PowerRegression regression = RegressionBuilder.create(x, y).buildPowerRegression(); +// coefficients +// coefficients +Console.log(regression.getA()); // emit 212.63671484070557 +Console.log(regression.getB()); // emit 0.2736903998810649 +// predicts the Y value with x = 2 +Console.log(regression.predict(2)); // emit 257.0557209615831 +``` + +## Exponential + +Exponential regression is a generalized linear model form of regression analysis used to model count data and contingency tables. It assumes the logarithm of its expected value can be modeled by a linear combination of unknown parameters. + +Exponential regression is a non-linear regression technique that looks like this: +
+y = A * eB * x +
+
+ + + +
+
+ +#### Creating an exponential regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create an [exponential regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/ExponentialRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(0D, 1D, 2D, 3D, 4D); +List y = Arrays.asList(1.5D, 2.5D, 3.5D, 5D, 7.5D); +// creates regression +ExponentialRegression regression = RegressionBuilder.create(x, y).buildExponentialRegression(); +// coefficients +Console.log(regression.getA()); // emit 0.391202 +Console.log(regression.getB()); // emit 1.579909 +// predicts the Y value with x = 2 +Console.log(regression.predict(2)); // emit 3.454825 +``` + +## Polynomial + +(quoted from [Polynomial regression](https://en.wikipedia.org/wiki/Polynomial_regression) definition in Wikipedia) + +Polynomial regression is a form of regression analysis in which the relationship between the independent variable x and the dependent variable y is modelled as an nth degree polynomial in x. + +Polynomial regression fits a nonlinear relationship between the value of x and the corresponding conditional mean of y. Although polynomial regression fits a nonlinear model to the data, as a statistical estimation problem it is linear, in the sense that the regression function is linear in the unknown parameters that are estimated from the data. For this reason, polynomial regression is considered to be a special case of multiple linear regression. + +The polynomial regression model can be represented using the below equation: +
+y = b0 + b1x1 + b2x12 + + * b2x13 +...... bnx1n +
+
+ + + +
+
+ +#### Creating a polynomial regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create a [polynomial regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/PolynomialRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(50D, 50D, 50D, 70D, 70D, 70D, 80D, 80D, 80D, 90D, 90D, 90D, 100D, 100D, 100D); +List y = Arrays.asList(3.3, 2.8, 2.9, 2.3, 2.6, 2.1, 2.5, 2.9, 2.4, 3.0, 3.1, 2.8, 3.3, 3.5, 3.0); +// setup the maximum degree of the polynomial +int degree = 5; +// creates regression +PolynomialRegression regression = RegressionBuilder.create(x, y).buildPolynomialRegression(degree); +// prints the coefficients in increasing order of power (from 0 to degree). +Console.log(regression.getCoefficients().toString()); +// predicts the Y value with x = 80 +Console.log(regression.predict(80)); // emit 2.6 +``` + +## Robust polynomial + +(quoted from [Robust polynomial regression](https://en.wikipedia.org/wiki/Robust_regression) definition in Wikipedia) + +Robust regression is a form of regression analysis designed to overcome some limitations of traditional parametric and non-parametric methods. Regression analysis seeks to find the relationship between one or more independent variables and a dependent variable. Certain widely used methods of regression, such as ordinary least squares, have favourable properties if their underlying assumptions are true, but can give misleading results if those assumptions are not true; thus ordinary least squares is said to be not robust to violations of its assumptions. + +Robust regression methods are designed to be not overly affected by violations of assumptions by the underlying data-generating process. + +In particular, least squares estimates for regression models are highly sensitive to outliers. +While there is no precise definition of an outlier, outliers are observations that do not follow the pattern of the other observations. +This is not normally a problem if the outlier is simply an extreme observation drawn from the tail of a normal distribution, but if the outlier results from non-normal measurement error or some other violation of standard ordinary least squares assumptions, then it compromises the validity of the regression results if a non-robust regression technique is used. + +The robust polynomial regression model can be represented using the below equation: +
+y = b0 + b1x1 + b2x12 + + * b2x13 +...... bnx1n +
+
+ +#### Creating a robust polynomial regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create a [robust polynomial regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RobustPolynomialRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(50D, 50D, 70D, 70D, 80D, 80D, 90D, 90D, 100D, 100D); +List y = Arrays.asList(2.8, 2.9, 2.3, 2.1, 2.5, 2.4, 3.0, 2.8, 3.3, 3.0); +// setup the maximum degree of the polynomial +int degree = 2; +// creates regression +RobustPolynomialRegression regression = RegressionBuilder.create(x, y).buildRobustPolynomialRegression(degree); +// prints the coefficients in increasing order of power (from 0 to degree). +Console.log(regression.getCoefficients().toString()); // emit [0.6666666666666661,0.023333333333333338] +// predicts the Y value with x = 80 +Console.log(regression.predict(80)); // emit 2.533333333333333 +``` + +## TheilSen + +(quoted from [TheilSen regression](https://en.wikipedia.org/wiki/Theil%E2%80%93Sen_estimator) definition in Wikipedia) + +In TheilSen Regression, the estimation of the model is done by calculating the slopes and intercepts of a subpopulation of all possible combinations of subsample points. The final slope and intercept is then defined as the spatial median of these slopes and intercepts. + +This regression can be computed efficiently, and is insensitive to outliers. It can be significantly more accurate than non-robust simple linear regression (least squares) for skewed and heteroskedastic data, and competes well against least squares even for normally distributed data in terms of statistical power. +It has been called "the most popular nonparametric technique for estimating a linear trend". + +The TheilSen regression model can be represented using the below equation: +
+y = a0 + a1x +
+
+ +#### Creating a TheilSen regression + +**Charba** provides a [builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/RegressionBuilder.html) to create a [TheilSen regression](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ml/TheilSenRegression.html), passing the samples, in order to enable the use to predict values. + +```java +// creates samples +List x = Arrays.asList(0.5D, 1D, 1.5D, 2D, 2.5D); +List y = Arrays.asList(0D, 1D, 2D, 3D, 4D); +// creates regression +TheilSenRegression regression = RegressionBuilder.create(x, y).buildTheilSenRegression(); +// coefficients +Console.log(regression.getSlope()); // emit 2 +Console.log(regression.getIntercept()); // emit -1 +Console.log(regression.getCoefficients().toString()); // emit [-1, 2] +// predicts the Y value with x = 3 +Console.log(regression.predict(3)); // emit 5 +// computes the X value with Y = 3.5 +Console.log(regression.computeX(3.5)); // emit 2.25 +``` diff --git a/versioned_docs/version-6.5/Requirements.md b/versioned_docs/version-6.5/Requirements.md new file mode 100644 index 000000000..b1f353b25 --- /dev/null +++ b/versioned_docs/version-6.5/Requirements.md @@ -0,0 +1,235 @@ +--- +id: Requirements +title: Requirements +hide_title: true +sidebar_label: Requirements +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Requirements + +**Charba** is built on JDK 11 (as of version 5). + +**Charba** is leveraging on [JSINTEROP](http://www.gwtproject.org/doc/latest/DevGuideCodingBasicsJsInterop.html) method to integrate javascript objects and needs the [jsinterop-annotations](https://github.com/google/jsinterop-annotations). + +**Charba** has got also a dependency with [GWT Web toolkit](http://www.gwtproject.org/), when the GWT distribution (which is containing chart widgets and code splitting capabilities) is used. + +**Charba** has got embedded [Chart.JS](http://www.chartjs.org/), currently the minified distribution. + +Even if [Chart.JS](http://www.chartjs.org/) leaves the users to select a date adapter, **Charba** embeds only [Luxon](https://moment.github.io/luxon/) as specific date time library, needed to use time or time series axes, because **Charba** (and [Chart.JS](http://www.chartjs.org/)) introduces the internationalization and only [Luxon](https://moment.github.io/luxon/) can use the browser's [INTL](./intl/Locale) platform. + +**Charba** has got embedded [Luxon](https://moment.github.io/luxon/) and the specific [Chart.JS adapter](https://github.com/chartjs/chartjs-adapter-luxon/). + +Furthermore **Charba** has embedded a set of [Chart.JS](http://www.chartjs.org/) plugins and controllers in order to enrich own features: + + * [DataLabels](https://github.com/chartjs/chartjs-plugin-datalabels) plugin + * [Labels](https://github.com/emn178/chartjs-plugin-labels) plugin (former PieceLabels). Due to the project is unmaintained, the plugin has been [imported](https://github.com/pepstock-org/Charba/blob/master/src/org/pepstock/charba/client/resources/js/chartjs-plugin-labels.js) in **Charba** project and maintained in [Charba](https://github.com/pepstock-org/Charba/blob/6.5/src/org/pepstock/charba/client/resources/js/chartjs-plugin-labels.js) project + * [Zoom](https://github.com/chartjs/chartjs-plugin-zoom) plugin + * [Hammer.JS](https://github.com/hammerjs/hammer.js) javaScript library for detecting touch gestures, as dependency of [Zoom](https://github.com/chartjs/chartjs-plugin-zoom) plugin + * [Annotation](https://github.com/chartjs/chartjs-plugin-annotation) plugin + * [Gradient](https://github.com/kurkle/chartjs-plugin-gradient) plugin + * [Chart.js Geo](https://github.com/sgratzl/chartjs-chart-geo) controller + * [Chart.js Treemap](https://github.com/kurkle/chartjs-chart-treemap) controller + * [Chart.js Matrix](https://github.com/kurkle/chartjs-chart-matrix) controller + * [Chart.js Sankey](https://github.com/kurkle/chartjs-chart-sankey) controller + +**Charba** has got embedded [ML.js](https://github.com/mljs/ml) to enable some [regressions](Regressions) models as part of machine learning tools. + +To enable the minifying of javascript objects, not provided out-of-the-box, **Charba** needs also [Google Closure Compiler](https://developers.google.com/closure/compiler/), invoked only in [Ant build.xml](https://github.com/pepstock-org/Charba/blob/6.5/build.xml). + +See here the license matrix. + +| Component | Version | License +| :- | :- | :- +| JSInterop Annotations | [2.0.0](https://github.com/google/jsinterop-annotations/releases/tag/2.0.0) | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) +| GWT Web Toolkit | [2.9.0](http://www.gwtproject.org/release-notes.html#Release_Notes_2_9_0) | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) +| Google Closure Compiler | v20231112 | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) +| Chart.JS | [4.4.1](https://github.com/chartjs/Chart.js/releases/tag/v4.4.1) | [MIT](https://raw.githubusercontent.com/chartjs/Chart.js/v4.4.1/LICENSE.md) +| Chart.JS Luxon adapter | [1.3.1](https://github.com/chartjs/chartjs-adapter-luxon/releases/tag/v1.3.1) | [MIT](https://raw.githubusercontent.com/chartjs/chartjs-adapter-luxon/master/LICENSE.md) +| Luxon | [3.4.4](https://github.com/moment/luxon/releases/tag/3.4.4) | [MIT](https://raw.githubusercontent.com/moment/luxon/master/license.md) +| DataLabels | [2.2.0](https://github.com/chartjs/chartjs-plugin-datalabels/releases/tag/v2.2.0) | [MIT](https://raw.githubusercontent.com/chartjs/chartjs-plugin-datalabels/master/LICENSE.md) +| Zoom | [2.0.1](https://github.com/chartjs/chartjs-plugin-zoom/releases/tag/v2.0.1) | [MIT](https://github.com/chartjs/chartjs-plugin-zoom/blob/master/LICENSE.md) +| HammerJS | [2.0.8](https://github.com/hammerjs/hammer.js/releases/tag/v2.0.8) | [MIT](https://github.com/hammerjs/hammer.js/blob/master/LICENSE.md) +| Annotation | [3.0.1](https://github.com/chartjs/chartjs-plugin-annotation/releases/tag/v3.0.1) | [MIT](https://github.com/chartjs/chartjs-plugin-annotation/blob/master/LICENSE.md) +| Gradient | [0.6.1](https://github.com/kurkle/chartjs-plugin-gradient/releases/tag/v0.6.1) | [MIT](https://github.com/kurkle/chartjs-plugin-gradient/blob/master/LICENSE) +| Chart Geo | [4.2.8](https://github.com/sgratzl/chartjs-chart-geo/releases/tag/v4.2.8) | [MIT](https://github.com/sgratzl/chartjs-chart-geo/blob/main/LICENSE) +| Chart Treemap | [2.3.0](https://github.com/kurkle/chartjs-chart-treemap/releases/tag/v2.3.0) | [MIT](https://github.com/kurkle/chartjs-chart-treemap/blob/next/LICENSE) +| Chart Matrix | [2.0.1](https://github.com/kurkle/chartjs-chart-matrix/releases/tag/v2.0.1) | [MIT](https://github.com/kurkle/chartjs-chart-matrix/blob/next/LICENSE) +| Chart Sankey | [0.12.0](https://github.com/kurkle/chartjs-chart-sankey/releases/tag/v0.11.0) | [MIT](https://github.com/kurkle/chartjs-chart-sankey/blob/master/LICENSE) +| ML.js | [6.0.0](https://github.com/mljs/ml/releases/tag/v6.0.0) | [MIT](https://github.com/mljs/ml/blob/master/LICENSE) + +## Browser support + +All modern and up-to-date browsers are supported, including, but not limited to: + + * Chrome + * Edge + * Firefox + * Safari + +As of version 3, [Chart.JS](http://www.chartjs.org/) has dropped **Internet Explorer 11** support, and then **Charba** has dropped as well, as of **version 4**. + +For more information about browser support, see the details **[here](https://caniuse.com/es6-class)**, where the filter is which browser can support ES6 classes. + +## Components matrix + +The following matrixes are showing the dependencies with version of components which are released in all **Charba** versions. + + + +### Java + +| Charba | Version
date | JDK | JsInterop
Base | JsInterop
Annotations | GWT Web
toolkit**(1)** | Google
Closure
Compiler | Google
Closure
Stylesheets**(2)** +| :- | - | - | - | - | - | - | - +| 6.5 | Feb 10, 2024 | 11 | - | 2.0.0 | 2.9.0 | v20231112 | - +| 6.4 | May 31, 2023 | 11 | - | 2.0.0 | 2.9.0 | v20230502 | - +| 6.3 | Apr 2, 2023 | 11 | - | 2.0.0 | 2.9.0 | v20230228 | - +| 6.2 | Mar 3, 2023 | 11 | - | 2.0.0 | 2.9.0 | v20230206 | - +| 6.1 | Feb 6, 2023 | 11 | - | 2.0.0 | 2.9.0 | v20230103 | - +| 6.0 | Dec 27, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20221102 | - +| 5.8 | Dec 1, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20221102 | - +| 5.7 | Oct 24, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20221004 | - +| 5.6 | Sep 20, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220905 | - +| 5.5 | Aug 8, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220719 | - +| 5.4 | Jul 12, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220601 | 1.5.0 +| 5.3 | May 12, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220301 | 1.5.0 +| 5.2 | Apr 4, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220301 | 1.5.0 +| 5.1 | Feb 22, 2022 | 11 | - | 2.0.0 | 2.9.0 | v20220202 | 1.5.0 +| 5.0 | Dec 4, 2021 | 11 | - | 2.0.0 | 2.9.0 | v20211006 | 1.5.0 +| 4.2 | Oct 7, 2021 | 8 | - | 2.0.0 | 2.9.0 | v20210808 | 1.5.0 +| 4.1 | Jul 29, 2021 | 8 | - | 2.0.0 | 2.9.0 | v20210601 | - +| 4.0 | Jun 3, 2021 | 8 | - | 2.0.0 | 2.9.0 | v20210505 | - +| 3.3 | Oct 21, 2020 | 8 | 1.0.0 | 2.0.0 | 2.8.2 | v20201006 | - +| 3.2 | May 22, 2020 | 8 | 1.0.0 | 2.0.0 | 2.8.2 | v20200504 | - +| 3.1 | Mar 21, 2020 | 8 | 1.0.0 | 2.0.0 | 2.8.2 | v20200224 | - +| 3.0 | Feb 21, 2020 | 8 | 1.0.0 | 2.0.0 | 2.8.2 | v20200204 | - +| 2.8 | Jan 16, 2020 | 8 | - | 2.0.0 | 2.8.2 | v20200101 | - +| 2.7 | Dec 16, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20191111 | - +| 2.6 | Nov 3, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20190929 | - +| 2.5 | May 20, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20190415 | - +| 2.4 | Apr 15, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20190325 | - +| 2.3 | Mar 27, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20190301 | - +| 2.2 | Mar 26, 2019 | 8 | - | 1.0.2 | 2.8.2 | v20190301 | - +| 2.1 | Feb 28, 2019 | 8 | - | 1.0.2 | 2.8.2 | - | - +| 2.0 | Jan 25, 2019 | 8 | - | 1.0.2 | 2.8.2 | - | - +| 1.7 | Dec 4, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.6 | Oct 30, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.5 | Aug 28, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.4 | May 17, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.3 | Apr 9, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.2 | Feb 6, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.1 | Jan 31, 2018 | 8 | - | - | 2.8.2 | - | - +| 1.0 | Jan 29, 2018 | 8 | - | - | 2.8.2 | - | - + +**(1)** even if **Charba** maintains the dependency with [GWT Web toolkit](http://www.gwtproject.org/) version 2.8.2, it has been successfully tested and works with [GWT version 2.9.0](http://www.gwtproject.org/release-notes.html#Release_Notes_2_9_0). As of **Charba version 4.0**, there is the dependency with GWT version 2.9.0 but it is continuing working with GWT 2.8.2. As of **Charba version 5.5** it has been successfully tested and works with [GWT version 2.10.0](http://www.gwtproject.org/release-notes.html#Release_Notes_2_10_0) + +**(2)** as of **Charba version 5.5** Google Closure Stylesheets dependency has been removed and CSS minifying is done internally. + +### CHART.JS core + +| Charba | Chart.JS | Chart.JS
Luxon
adapter | Luxon | Chart.JS
Moment
adapter**(1)** | Moment**(1)** | Chart.JS
Datefns
adapter**(1)** | Datefns**(1)** | +| :- | :- | - | :- | - | :- | - | :- +| 6.5 | 4.4.1 | 1.3.1 | 3.4.4 | - | - | - | - +| 6.4 | 4.3.0 | 1.3.1 | 3.3.0 | - | - | - | - +| 6.3 | 4.2.1 | 1.3.1 | 3.3.0 | - | - | - | - +| 6.2 | 4.2.1 | 1.3.1 | 3.2.1 | - | - | - | - +| 6.1 | 4.2.0 | 1.3.1 | 3.2.1 | - | - | - | - +| 6.0 | 4.1.1 | 1.3.0 | 3.1.1 | - | - | - | - +| 5.8 | 3.9.1 | 1.3.0 | 3.1.1 | - | - | - | - +| 5.7 | 3.9.1 | 1.2.0 | 3.0.4 | - | - | - | - +| 5.6 | 3.9.1 | 1.2.0 | 3.0.3 | - | - | - | - +| 5.5 | 3.9.1 | 1.2.0 | 3.0.1 | - | - | - | - +| 5.4 | 3.8.0 | 1.1.0 | 3.0.1 | - | - | - | - +| 5.3 | 3.7.1 | 1.1.0 | 2.4.0 | - | - | - | - +| 5.2 | 3.7.1 | 1.1.0 | 2.3.1 | - | - | - | - +| 5.1 | 3.7.1 | 1.1.0 | 2.3.0 | - | - | - | - +| 5.0 | 3.6.1 | 1.1.0 | 2.0.2 | - | - | - | - +| 4.2 | 3.5.1 | 1.1.0 | 2.0.2 | - | - | - | - +| 4.1 | 3.5.0 | 1.0.0 | 2.0.1 | - | - | - | - +| 4.0 | 3.3.2 | 1.0.0 | 1.27.0 | - | - | - | - +| 3.3 | 2.9.4 | 0.2.2 | 1.25.0 | 0.1.2 | 2.28.0 | 1.0.0 | 2.9.0 +| 3.2 | 2.9.3 | 0.2.1 | 1.24.1 | 0.1.1 | 2.25.3 | 1.0.0 | 2.9.0 +| 3.1 | 2.9.3 | 0.2.0 | 1.22.0 | 0.1.1 | 2.24.0 | 1.0.0 | 2.9.0 +| 3.0 | 2.9.3 | 0.2.0 | 1.22.0 | 0.1.1 | 2.24.0 | 1.0.0 | 2.9.0 +| 2.8 | 2.9.3 | - | - | - | - | - | - +| 2.7 | 2.9.3 | - | - | - | - | - | - +| 2.6 | 2.9.2 | - | - | - | - | - | - +| 2.5 | 2.8.0 | - | - | - | - | - | - +| 2.4 | 2.8.0 | - | - | - | - | - | - +| 2.3 | 2.8.0 | - | - | - | - | - | - +| 2.2 | 2.8.0 | - | - | - | - | - | - +| 2.1 | 2.7.3 | - | - | - | - | - | - +| 2.0 | 2.7.3 | - | - | - | - | - | - +| 1.7 | 2.7.3 | - | - | - | - | - | - +| 1.6 | 2.7.2 | - | - | - | - | - | - +| 1.5 | 2.7.2 | - | - | - | - | - | - +| 1.4 | 2.7.1 | - | - | - | - | - | - +| 1.3 | 2.7.1 | - | - | - | - | - | - +| 1.2 | 2.7.1 | - | - | - | - | - | - +| 1.1 | 2.7.1 | - | - | - | - | - | - +| 1.0 | 2.7.1 | - | - | - | - | - | - + +**(1)** As of **version 4.0**, **Charba** (and [Chart.JS](http://www.chartjs.org/) version 3.x) introduces the internationalization and only [Luxon](https://moment.github.io/luxon/) is leveraging on [INTL](./intl/Locale) platform. The other dependencies has been removed. + +### CHART.JS extensions + +| Charba | Datalabels | Labels**(1)** | Zoom | HammerJS | Annotation | Gradient | Geo | Treemap | Matrix | Sankey +| :- | :- | :- | :- | :- | :- | :- | :- | :- | :- +| 6.5 | 2.2.0 | 1.1.0 | 2.0.1 | 2.0.8 | 3.0.1 | 0.6.1 | 4.2.8 | 2.3.0 | 2.0.1 | 0.12.0 +| 6.4 | 2.2.0 | 1.1.0 | 2.0.1 | 2.0.8 | 3.0.1 | 0.6.1 | 4.2.0 | 2.3.0 | 2.0.1 | 0.12.0 +| 6.3 | 2.2.0 | 1.1.0 | 2.0.1 | 2.0.8 | 2.2.1 | 0.6.1 | 4.1.2 | 2.3.0 | 2.0.1 | 0.12.0 +| 6.2 | 2.2.0 | 1.1.0 | 2.0.0 | 2.0.8 | 2.1.2 | 0.6.1 | 4.1.2 | 2.3.0 | 2.0.1 | 0.12.0 +| 6.1 | 2.2.0 | 1.1.0 | 2.0.0 | 2.0.8 | 2.1.2 | 0.6.1 | 4.1.2 | 2.3.0 | 2.0.1 | 0.12.0 +| 6.0 | 2.2.0 | 1.1.0 | 2.0.0 | 2.0.8 | 2.1.0 | 0.6.1 | 4.1.0 | 2.2.0 | 1.3.0 | 0.12.0 +| 5.8 | 2.1.0 | 1.1.0 | 2.0.0 | 2.0.8 | 2.1.0 | 0.5.1 | 3.10.0 | 2.1.3 | 1.3.0 | 0.12.0 +| 5.7 | 2.1.0 | 1.1.0 | 1.2.1 | 2.0.8 | 2.0.1 | 0.5.1 | 3.10.0 | 2.0.2 | 1.2.0 | 0.11.0 +| 5.6 | 2.1.0 | 1.1.0 | 1.2.1 | 2.0.8 | 2.0.1 | 0.5.1 | 3.9.0 | 2.0.2 | 1.1.1 | 0.9.1 +| 5.5 | 2.1.0 | 1.1.0 | 1.2.1 | 2.0.8 | 2.0.0 | 0.5.0 | 3.8.1 | 2.0.2 | 1.1.1 | 0.9.0 +| 5.4 | 2.0.0 | 1.1.0 | 1.2.1 | 2.0.8 | 1.4.0 | 0.5.0 | 3.8.0 | 2.0.2 | 1.1.1 | 0.9.0 +| 5.3 | 2.0.0 | 1.1.0 | 1.2.1 | 2.0.8 | 1.4.0 | 0.5.0 | 3.7.2 | 2.0.2 | 1.1.1 | 0.9.0 +| 5.2 | 2.0.0 | 1.1.0 | 1.2.1 | 2.0.8 | 1.4.0 | 0.4.0 | 3.7.1 | 2.0.2 | 1.1.1 | 0.9.0 +| 5.1 | 2.0.0 | 1.1.0 | 1.2.0 | 2.0.8 | 1.3.1 | - | 3.7.1 | 2.0.2 | 1.1.1 | 0.8.1 +| 5.0 | 2.0.0 | 1.1.0 | 1.2.0 | 2.0.8 | 1.1.0 | - | 3.6.0 | 2.0.0 | 1.1.0 | 0.8.0 +| 4.2 | 2.0.0 | 1.1.0 | 1.1.1 | 2.0.8 | 1.0.2 | - | 3.5.1 | 1.0.2 | 1.1.0 | 0.8.0 +| 4.1 | 2.0.0 | 1.1.0 | 1.1.1 | 2.0.8 | 1.0.2 | - | 3.1.0 | - | - | - +| 4.0 | 2.0.0-rc.1 | 1.1.0 | 1.0.1 | 2.0.8 | 1.0.2 | - | - | - | - | - +| 3.3 | 0.7.0 | 1.1.0 | 0.7.5 | 2.0.8 | 5363042 | - | - | - | - | - +| 3.2 | 0.7.0 | 1.1.0 | 0.7.5 | 2.0.8 | 5363042 | - | - | - | - | - +| 3.1 | 0.7.0 | 1.1.0 | 0.7.5 | 2.0.8 | 7037eea | - | - | - | - | - +| 3.0 | 0.7.0 | 1.1.0 | 0.7.5 | 2.0.8 | 7037eea | - | - | - | - | - +| 2.8 | 0.7.0 | 1.1.0 | 0.7.5 | 2.0.8 | 7037eea | - | - | - | - | - +| 2.7 | 0.7.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.6 | 0.7.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.5 | 0.6.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.4 | 0.6.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.3 | 0.6.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.2 | 0.6.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.1 | 0.5.0 | 1.1.0 | - | - | - | - | - | - | - | - +| 2.0 | - | - | - | - | - | - | - | - | - | - +| 1.7 | - | - | - | - | - | - | - | - | - | - +| 1.6 | - | - | - | - | - | - | - | - | - | - +| 1.5 | - | - | - | - | - | - | - | - | - | - +| 1.4 | - | - | - | - | - | - | - | - | - | - +| 1.3 | - | - | - | - | - | - | - | - | - | - +| 1.2 | - | - | - | - | - | - | - | - | - | - +| 1.1 | - | - | - | - | - | - | - | - | - | - +| 1.0 | - | - | - | - | - | - | - | - | - | - + +**(1)** The [Labels plugin](./extensions/Labels) has been heavily changed in order to be compliant with [Chart.JS](http://www.chartjs.org/) version 3.x) in the **Charba** [project](https://github.com/pepstock-org/Charba/blob/master/src/org/pepstock/charba/client/resources/js/chartjs-plugin-labels.js) because the [original project](https://github.com/emn178/chartjs-plugin-labels) is unmaintained. + +### Additional extensions + +| Charba | ML.js +| :- | :- +| 6.5 | 6.0.0 +| 6.4 | 6.0.0 +| 6.3 | 6.0.0 +| 6.2 | 6.0.0 +| 6.1 | 6.0.0 +| 6.0 | 6.0.0 +| 5.8 | 6.0.0 +| 5.7 | 6.0.0 +| 5.6 | 6.0.0 +| 5.5 | 6.0.0 +| 5.4 | 6.0.0 +| 5.3 | 6.0.0 diff --git a/versioned_docs/version-6.5/axes/AngleLines.md b/versioned_docs/version-6.5/axes/AngleLines.md new file mode 100644 index 000000000..f67786538 --- /dev/null +++ b/versioned_docs/version-6.5/axes/AngleLines.md @@ -0,0 +1,73 @@ +--- +id: AngleLines +title: Angle lines +hide_title: true +sidebar_label: Angle lines +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Angle lines + +The [angle lines](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialAngleLines.html) options are used to configure angled lines that radiate from the center of the chart to the point labels. + + + +:::caution +The angle lines can be **ONLY** applied to radial axes.
+These options only apply if **display** is **true**. +::: + +The [RadialAngleLines](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialAngleLines.html) provides all **set** and **get** methods to manage the configuration, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables the angle lines +axis.getAngleLines().setDisplay(true); +// sets and gets the line width value +axis.getAngleLines().setLineWidth(2); + +int lineWidth = axis.getAngleLines().getLineWidth(); +``` + + +Table with options: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Color of angled lines. +| display | boolean | - | If `true`, angle lines are shown. +| lineWidth | int | [Yes](#scriptable) | Width of angled lines. + +### Scriptable + +Scriptable options at grid level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables the angle lines +axis.getAngleLines().setDisplay(true); +// sets the option by a callback +axis.getAngleLines().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<ScaleContext> | int +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<ScaleContext> | double +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| lineWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int diff --git a/versioned_docs/version-6.5/axes/Axes.md b/versioned_docs/version-6.5/axes/Axes.md new file mode 100644 index 000000000..04127e0a9 --- /dev/null +++ b/versioned_docs/version-6.5/axes/Axes.md @@ -0,0 +1,314 @@ +--- +id: Axes +title: Introduction +hide_title: true +sidebar_label: Introduction +--- +## Axes + +Axes are an integral parts of a chart. They are used to determine how data maps to a pixel value on the chart. In a cartesian chart, there is 1 or more X axis and 1 or more Y axis to map points onto the 2 dimensional chart. These axes are know as ['cartesian axes'](CartesianAxes). + +In a radial chart, such as a radar chart or a polar area chart, there is a single axis that maps points in the angular and radial directions. These are known as ['radial axes'](RadialAxes). + +There are a number of options to allow styling an axis. There are settings to control [grid](Grid) and [ticks](#ticks). + +## Attributes + +Each axis has got a set of common attributes, mandatory options of all axes. + +At the creation time, an axis needs to have the following 3 attributes: + +| Name | Type | Description +| :- | :- | :- +| id | [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | The unique id of axis. +| type | [AxisType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/AxisType.html) | The type of scale being employed. +| axis | [AxisKind](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisKind.html) |The axis kind to define which directions are used in axis. + +Here is an example how to create an axis: + +```java +// creates the id "y-my" for the axis +ScaleId scaleId = ScaleId.create("y-my"); +// creates the by chart instance, my scale id and specifying that is a scale for Y +CartesianLinearAxis linearAxis = new CartesianLinearAxis(chart, scaleId, AxisKind.Y); +``` + +## Axis ID + +All axes must have a unique id which must be passed when the axis is creating. When the id is not passed, the axis will use a [default id](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) based on type and kind of axis. + +If you are creating a axis by a custom id and [AxisKind](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisKind.html) is not provided, the kind of axis is automatically set checking the first character of axis id: + + * if axis id is starting with `x`, then the kind of axis is ['X'](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisKind.html#X). + * if axis id is starting with `y`, then the kind of axis is ['Y'](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisKind.html#Y). + +Every axis has got own default axis id and kind, as following: + +| Type | Default Id | Default Orientation +| :- | :- | :- +| linear | DefaultScaleId.Y | AxisKind.Y +| logarithmic | DefaultScaleId.Y | AxisKind.Y +| category | DefaultScaleId.X | AxisKind.X +| time | DefaultScaleId.X | AxisKind.X +| timeseries | DefaultScaleId.X | AxisKind.X +| radialLinear | DefaultScaleId.R | AxisKind.R + +## Callbacks + +There are a number of configuration callbacks that can be used to change parameters in the scale at different points in the update process. + +All callbacks interfaces have got 2 arguments: + + * [Axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Axis.html) instance + * [Axis item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisItem.html) object with all details about axis. + +To add a callback, see the following example: + +```java +axis.setAxisUpdateCallback(new AxisUpdateCallback(){ + + // methods implementation + +}); +``` + +#### BuildTicks callback + +This callback can be used to change parameters in the scale during ticks building. Each axis can manage different type of ticks (strings, numbers, dates) and the description how to use the build ticks callback is described in the page of axes: + + * [Category cartesian axes](CartesianCategoryAxes#buildticks-callback) + * [Linear cartesian axes](CartesianLinearAxes#buildticks-callback) + * [Logarithmic cartesian axes](CartesianLogarithmicAxes#buildticks-callback) + * [Time cartesian axes](CartesianTimeAxes#buildticks-callback) + * [Linear radial axes](RadialAxes#buildticks-callback) + + +#### Calculate tick rotation callback + +This callback can be used to change parameters in the scale during tick rotation. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisCalculateTickRotationCallback.html). + +```java +public interface AxisCalculateTickRotationCallback { + + /** + * Callback that runs before tick rotation is determined. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeCalculateTickRotation(Axis axis, AxisItem item); + + /** + * Callback that runs after tick rotation is determined. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterCalculateTickRotation(Axis axis, AxisItem item); + +} +``` + +#### Data limit callback + +This callback can be used to change parameters in the scale during data limits determination. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisDataLimitsCallback.html). + +```java +public interface AxisDataLimitsCallback { + + /** + * Callback that runs before data limits are determined. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeDataLimits(Axis axis, AxisItem item); + + /** + * Callback that runs after data limits are determined. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterDataLimits(Axis axis, AxisItem item); +} +``` + +#### Dimensions callback + +This callback can be used to change parameters in the scale during setting dimensions. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisDimensionsCallback.html). + +```java +public interface AxisDimensionsCallback { + + /** + * Callback that runs before dimensions are set. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeSetDimensions(Axis axis, AxisItem item); + + /** + * Callback that runs after dimensions are set. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterSetDimensions(Axis axis, AxisItem item); + +} +``` + +#### Fit callback + +This callback can be used to change parameters in the scale during fitting phase. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisFitCallback.html). + +```java +public interface AxisFitCallback { + + /** + * Callback that runs before the scale fits to the canvas. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeFit(Axis axis, AxisItem item); + + /** + * Callback that runs after the scale fits to the canvas. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterFit(Axis axis, AxisItem item); + +} +``` + +#### Tick to label conversion callback + +This callback can be used to change parameters in the scale during ticks label conversion. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisTickToLabelConversionCallback.html). + +```java +public interface AxisTickToLabelConversionCallback { + + /** + * Callback that runs before ticks are converted in strings. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeTickToLabelConversion(Axis axis, AxisItem item); + + /** + * Callback that runs after ticks are converted in strings. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterTickToLabelConversion(Axis axis, AxisItem item); + +} +``` + +#### Update callback + +This callback can be used to change parameters in the scale during updating. To implement this callback, you must implement [this interface](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AxisUpdateCallback.html). + +```java +public interface AxisUpdateCallback { + + /** + * Callback called before the update process starts. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onBeforeUpdate(Axis axis, AxisItem item); + + /** + * Callback that runs at the end of the update process. + * + * @param axis axis instance where this callback as been defined + * @param item axis item instance + */ + void onAfterUpdate(Axis axis, AxisItem item); + +} +``` + +## Ticks + +All ticks generated by axes can be configured. All axes are providing the capability to set and get the options, by the **set** and **get** methods, as following: + +```java +// creates the axis for chart with default id and kind to "y" +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets display to the ticks +axis.getTicks().setDisplay(true); + +boolean display = axis.getTicks().isDisplay(); +``` + +Table with options: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Color of ticks.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#scriptable) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| padding | int | - | The padding between the tick label and the axis. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The color of the stroke around the text. +| textStrokeWidth | int | [Yes](#scriptable) | Stroke width around the text. +| z | int | - | The z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +### Scriptable + +Scriptable options at grid level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Major Tick + +The major tick configuration enables for the major tick marks that are generated by the axis. A major tick will affect auto-skipping and major will be defined on ticks in the scriptable options context, by [ScaleTickItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleTickItem.html) class and [isMajor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleTickItem.html#isMajor--) method. + +The major ticks configuration is nested in the ticks configuration as following: + +```java +// creates the axis for chart with default id and kind to "y" +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// enables major tick +axis.getTicks().getMajor().setEnabled(true); + +boolean enabled = axis.getTicks().getMajor().isEnabled(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- | :- +| enabled | boolean | If `true`, major ticks marks are generated. diff --git a/versioned_docs/version-6.5/axes/Cartesians.md b/versioned_docs/version-6.5/axes/Cartesians.md new file mode 100644 index 000000000..07efd4ea7 --- /dev/null +++ b/versioned_docs/version-6.5/axes/Cartesians.md @@ -0,0 +1,22 @@ +--- +id: CartesianAxes +title: Cartesian axes +hide_title: true +sidebar_label: Introduction +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Introduction + +Axes are an integral part of a chart. They are used to determine how data maps to a pixel value on the chart. +In a cartesian chart, there is 1 or more X axes and 1 or more Y axes to map points onto the 2 dimensional canvas. These axes are know as 'cartesian axes'. + + + +Axes that follow a cartesian grid are known as 'Cartesian Axes'. Cartesian axes are used for line, bar, scatter and bubble charts. + + * **[category](CartesianCategoryAxes)** + * **[linear](CartesianLinearAxes)** + * **[logarithmic](CartesianLogarithmicAxes)** + * **[time](CartesianTimeAxes)** + * **[time series](CartesianTimeSeriesAxes)** diff --git a/versioned_docs/version-6.5/axes/Category.md b/versioned_docs/version-6.5/axes/Category.md new file mode 100644 index 000000000..6372ec2ed --- /dev/null +++ b/versioned_docs/version-6.5/axes/Category.md @@ -0,0 +1,213 @@ +--- +id: CartesianCategoryAxes +title: Cartesian category +hide_title: true +sidebar_label: Category +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Cartesian Category Axes + +The [category axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianCategoryAxis.html) will draw the labels from one of the label arrays included in the chart data. + + + +Here are some example how to create category axes: + +```java +// creates a category axis with default scale id "x" and default kind "x" +CartesianCategoryAxis axis1 = new CartesianCategoryAxis(chart); + +// creates a category axis with scale id "my-axis" and default kind "x" +CartesianCategoryAxis axis2 = new CartesianCategoryAxis(chart, "my-axis"); + +// creates a category axis with scale id "my-axis" and default kind "x" +CartesianCategoryAxis axis3 = new CartesianCategoryAxis(chart, ScaleId.create("my-axis")); + +// creates a category axis with default scale id "x" and custom kind "x" +CartesianCategoryAxis axis4 = new CartesianCategoryAxis(chart, AxisKind.X); + +// creates a category axis with scale id "my-axis" and custom kind "x" +CartesianCategoryAxis axis5 = new CartesianCategoryAxis(chart, "my-axis", AxisKind.X; + +// creates a category axis with scale id "my-axis" and custom kind "x" +ScaleId myAxis = ScaleId.create("my-axis"); +CartesianCategoryAxis axis6 = new CartesianCategoryAxis(chart, myAxis, AxisKind.X); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis1, ...); +``` + +## Options + +The cartesian category axis allows to define a number of properties, used to display the data. + +```java +// creates a category axis +CartesianCategoryAxis axis = new CartesianCategoryAxis(chart); +// sets and gets the reverse value +axis.setReverse(true); + +boolean reverse = axis.isReverse(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | [Yes](#scriptable) | Determines the scale bounds on axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| max | String | [Yes](#scriptable) | User defined maximum string for the scale, overrides maximum value from data. +| min | String | [Yes](#scriptable) | User defined minimum string for the scale, overrides minimum value from data. +| labels | [Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Labels.html) | - | The labels to display. +| offset | boolean | [Yes](#scriptable) | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| position | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) | [Yes](#scriptable) | Position of the axis +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| singleStacked | boolean | - | If you might want to stack positive and negative values together. +| stack | String | [Yes](#scriptable) | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | [Yes](#scriptable) | If the axis are stacked. +| stackWeight | double | [Yes](#scriptable) | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianCategoryAxis axis = new CartesianCategoryAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| bounds | [BoundsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BoundsCallback.html) | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<String> | String +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<String> | String +| offset | [ScaleOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleOffsetCallback.html) | boolean +| position | [ScalePositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScalePositionCallback.html) | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| stack | [StackCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackCallback.html) | String +| stacked | [StackedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | boolean +| stackWeight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Ticks + +The category axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianCategoryTick.html). + +```java +// creates a category axis +CartesianCategoryAxis axis = new CartesianCategoryAxis(chart); +// sets and gets the max value +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | - | The tick alignment along the axis. +| autoSkip | boolean | - | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | - | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks. +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | - | The tick alignment perpendicular to the axis. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks. +| includeBounds | boolean | - | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | - | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | - | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| minRotation | int | - | The minimum rotation for tick labels. +| mirror | boolean | - | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| padding | int | - | The padding between the tick label and the axis. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int | [Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +For both the `min` and `max` properties, the value must be in the `labels` array. + +The further customization of ticks, a [callback](#callback) is provided. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianCategoryAxis axis = new CartesianCategoryAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. + +To apply a custom callback, you can set a [CategoryTickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CategoryTickCallback.html) instance to the axis options, as following: + +```java +axis.getTicks().setCallback(new CategoryTickCallback(){ + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, String value, int index, List values){ + // add a label + return value + myLabel; + } + +}); +``` + +The callback can return a string (for single line) or a list of strings (for multiple lines). diff --git a/versioned_docs/version-6.5/axes/Grid.md b/versioned_docs/version-6.5/axes/Grid.md new file mode 100644 index 000000000..dcb8e49ae --- /dev/null +++ b/versioned_docs/version-6.5/axes/Grid.md @@ -0,0 +1,124 @@ +--- +id: Grid +title: Grid and border +hide_title: true +sidebar_label: Grid and border +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Grid + +It defines options for the grid lines that run perpendicular to the axis. + + + +All axes are providing the capability to set and get the options, by the **set** and **get** methods, as following: + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets line width to the grid +axis.getGrid().setDisplay(true); + +boolean display = axis.getGrid().isDisplay(); +``` + +Table with options: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| circular | boolean | - | If `true`, grid lines are circular (on radar chart only). +| color | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | [Yes](#scriptable) | The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | - | If `false`, do not display grid lines for this axis. +| drawOnChartArea | boolean | - | If `true`, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn. +| drawTicks | boolean | - | If `true`, draw lines beside the ticks in the axis area beside the chart. +| lineWidth | int - int[] | [Yes](#scriptable) | Stroke width of grid lines. +| offset | boolean | - | If `true`, grid lines will be shifted to be between labels. This is set to `true` in the bar chart by default. +| tickBorderDash | int[] | [Yes](#scriptable) | Length and spacing of the tick mark line. If not set, defaults to the grid line `borderDash` value. +| tickBorderDashOffset | double - double[] | - | Offset for the line dash of the tick mark. If unset, defaults to the grid line `borderDashOffset` value +| tickColor | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | [Yes](#scriptable) | Color of the tick line. If unset, defaults to the grid line `color`. +| tickLength | int | - | Length in pixels that the grid lines will draw in the axis area. +| tickWidth | int - int[] | [Yes](#scriptable) | Width of the tick mark in pixels. If unset, defaults to the grid line `lineWidth`. +| z | int | - | The z-index of gridline layer. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +### Scriptable + +Scriptable options at grid level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getGrid().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| lineWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int +| tickBorderDash | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<ScaleContext> | double +| tickColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| tickWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +## Border + +The [border](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/AxisBorder.html) defines options for the border that run perpendicular to the axis. + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets color to the grid +axis.getBorder().setDisplay(true); +axis.getBorder().setColor(HtmlColor.RED); + +boolean display = axis.getBorder().isDisplay(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| display | boolean | - | If `true`, draw border at the edge between the axis and the chart area. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | - | If set, used as the color of the border line. +| dash | int[] | [Yes](#border-scriptable) | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| dashOffset | double | [Yes](#border-scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| width | int | - | If set, used as the width of the border line. +| z | int | - | z-index of the border layer. Values less than or equals to 0 are drawn under datasets, greater than 0 on top. + +### Border scriptable + +Scriptable options at grid level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getBorder().setDashOffset(new BorderDashOffsetCallback(){ + + @Override + public int invoke(ScaleContext context){ + // logic + return dashOffset; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| dash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<ScaleContext> | List<Integer> +| dashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<ScaleContext> | double diff --git a/versioned_docs/version-6.5/axes/Linear.md b/versioned_docs/version-6.5/axes/Linear.md new file mode 100644 index 000000000..6b495f410 --- /dev/null +++ b/versioned_docs/version-6.5/axes/Linear.md @@ -0,0 +1,265 @@ +--- +id: CartesianLinearAxes +title: Linear +hide_title: true +sidebar_label: Linear +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Cartesian Linear Axes + +The [linear axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLinearAxis.html) is use to chart numerical data. It can be placed on either the x or y axis. + + + +Here are some example how to create linear axes: + +```java +// creates a linear axis with default scale id "y" and default kind "y" +CartesianLinearAxis axis1 = new CartesianLinearAxis(chart); + +// creates a linear axis with scale id "my-axis" and default kind "y" +CartesianLinearAxis axis2 = new CartesianLinearAxis(chart, "my-axis"); + +// creates a linear axis with scale id "my-axis" and default kind "y" +CartesianLinearAxis axis3 = new CartesianLinearAxis(chart, ScaleId.create("my-axis")); + +// creates a linear axis with default scale id "y" and custom kind "y" +CartesianLinearAxis axis4 = new CartesianLinearAxis(chart, AxisKind.Y); + +// creates a linear axis with scale id "my-axis" and custom kind "y" +CartesianLinearAxis axis5 = new CartesianLinearAxis(chart, "my-axis", AxisKind.Y); + +// creates a linear axis with scale id "my-axis" and custom kind "y" +ScaleId myAxis = ScaleId.create("my-axis"); +CartesianLinearAxis axis6 = new CartesianLinearAxis(chart, myAxis, AxisKind.Y); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis1, ...); +``` + +## Options + +The cartesian linear axis allows to define a number of properties, used to display the data. + +```java +// creates a linear axis +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets and gets the max value +axis.setMax(100); + +double max = axis.getMax(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| beginAtZero | boolean | [Yes](#scriptable) | If `true`, scale will include 0 if it is not already included. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | [Yes](#scriptable) | Determines the scale bounds on axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| grace | int | [Yes](#scriptable) | Amount of pixels for added room in the scale range above and below data. +| graceAsPercentage | double | [Yes](#scriptable) | Sets a value, between 0 and 1, as percentage, for added room in the scale range above and below data. +| max | double | [Yes](#scriptable) | User defined maximum number for the scale, overrides maximum value from data. +| min | double | [Yes](#scriptable) | User defined minimum number for the scale, overrides minimum value from data. +| offset | boolean | [Yes](#scriptable) | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| position | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) | [Yes](#scriptable) | Position of the axis. +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| singleStacked | boolean | - | If you might want to stack positive and negative values together. +| stack | String | [Yes](#scriptable) | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | [Yes](#scriptable) | If the axis are stacked. +| stackWeight | double | [Yes](#scriptable) | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| suggestedMax | double | [Yes](#scriptable) | Adjustment used when calculating the maximum data value. +| suggestedMin | double | [Yes](#scriptable) | Adjustment used when calculating the minimum data value. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| beginAtZero | [BeginAtZeroCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BeginAtZeroCallback.html) | boolean +| bounds | [BoundsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BoundsCallback.html) | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| grace | [GraceCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/GraceCallback.html) | int - double +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| offset | [ScaleOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleOffsetCallback.html) | boolean +| position | [ScalePositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScalePositionCallback.html) | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| stack | [StackCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackCallback.html) | String +| stacked | [StackedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | boolean +| stackWeight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | double +| suggestedMax | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| suggestedMin | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Ticks + +The linear axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLinearTick.html). + +```java +// creates a linear axis +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets and gets the max value +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | - | The tick alignment along the axis. +| autoSkip | boolean | - | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | - | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks. +| count | int | [Yes](#ticks-scriptable-options) | The number of ticks to generate. If specified, this overrides the automatic generation. +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | - | The tick alignment perpendicular to the axis. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| includeBounds | boolean | - | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | - | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | - | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| maxTicksLimit | int | [Yes](#ticks-scriptable-options) | Maximum number of ticks and gridlines to show. +| minRotation | int | - | The minimum rotation for tick labels. +| mirror | boolean | - | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| numberFormat | [NumberFormatOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/NumberFormatOptions.html) | [Yes](#ticks-scriptable-options) | The number format options used by the default label formatter.
See [INTL number format](../intl/NumberFormat) documentation. +| padding | int | - | The padding between the tick label and the axis. +| precision | int | [Yes](#ticks-scriptable-options) | If defined and `stepSize` is not specified, the step size will be rounded to this many decimal places. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| stepSize | double | [Yes](#ticks-scriptable-options) | User defined fixed step size for the scale. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int | [Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +Given the number of axis range settings, it is important to understand how they all interact with each other. + +The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behavior. + +In contrast to the `suggested*` settings, the `min` and `max` settings set explicit ends to the axes. When these are set, some data points may not be visible. + +If `stepSize` set, the scale ticks will be enumerated by multiple of `stepSize`, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm. + +The further customization of ticks, a [callback](#callback) is provided. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| count | [CountCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CountCallback.html) | int +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| maxTicksLimit | [MaxTicksLimitCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MaxTicksLimitCallback.html) | int +| numberFormat | [NumberFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/NumberFormatCallback.html) | [NumberFormatItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/NumberFormatItem.html) +| precision | [PrecisionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PrecisionCallback.html) | int +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| stepSize | [StepSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StepSizeCallback.html) | double +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. For example, adding a dollar sign ('$'). To do this, you need to implement a ticks callback in the axis configuration. + +To apply a custom callback, you can set a [TickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TickCallback.html) instance to the axis options, as following: + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getTicks().setCallback(new TickCallback(){ + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, double value, int index, List values){ + // add $ + return "$" + value; + } + +}); +``` + +See [INTL number format](../intl/NumberFormat) documentation if you want to use a number formatter, provided out-of-the-box. + +The callback can return a string (for single line) or a list of strings (for multiple lines). + +### NoSelectedDatasetTicksCallback callback + +**Charba** provides a common implementation for tick callback to set the decimal digits of ticks in case of all data sets are hidden, to avoid the annoying standard format of doubles. + +To apply the callback, you can set an instance to the axis options, as following: + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback()); +``` + +The default decimal precision is `2`. A custom precision can be set by the constructor of callback, as following: + +```java +// creates the axis for chart +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// sets the option by a callback +// 3 decimal digits +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback(3)); +``` diff --git a/versioned_docs/version-6.5/axes/Logarithmic.md b/versioned_docs/version-6.5/axes/Logarithmic.md new file mode 100644 index 000000000..51433a2ac --- /dev/null +++ b/versioned_docs/version-6.5/axes/Logarithmic.md @@ -0,0 +1,241 @@ +--- +id: CartesianLogarithmicAxes +title: Cartesian logarithmic +hide_title: true +sidebar_label: Logarithmic +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Cartesian Logarithmic Axes + +The [logarithmic axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLogarithmicAxis.html) is use to chart numerical data. It can be placed on either the x or y axis. As the name suggests, logarithmic interpolation is used to determine where a value lies on the axis. + + + +Here are some example how to create logarithmic axes: + +```java +// creates a logarithmic axis with default scale id "y" and default kind "y" +CartesianLogarithmicAxis axis1 = new CartesianLogarithmicAxis(chart); + +// creates a logarithmic axis with scale id "my-axis" and default kind "y" +CartesianLogarithmicAxis axis2 = new CartesianLogarithmicAxis(chart, "my-axis"); + +// creates a logarithmic axis with scale id "my-axis" and default kind "y" +CartesianLogarithmicAxis axis3 = new CartesianLogarithmicAxis(chart, ScaleId.create("my-axis")); + +// creates a logarithmic axis with default scale id "y" and custom kind "y" +CartesianLogarithmicAxis axis4 = new CartesianLogarithmicAxis(chart, AxisKind.Y); + +// creates a logarithmic axis with scale id "my-axis" and custom kind "y" +CartesianLogarithmicAxis axis5 = new CartesianLogarithmicAxis(chart, "my-axis", AxisKind.Y); + +// creates a logarithmic axis with scale id "my-axis" and custom kind "y" +ScaleId myAxis = ScaleId.create("my-axis"); +CartesianLogarithmicAxis axis6 = new CartesianLogarithmicAxis(chart, myAxis, AxisKind.Y); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis1, ...); +``` + +## Options + +The cartesian logarithmic axis allows to define a number of properties, used to display the data. + +```java +// creates a logarithmic axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets and gets the max value +axis.setMax(10000); + +double max = axis.getMax(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | [Yes](#scriptable) | Determines the scale bounds on axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| max | double | [Yes](#scriptable) | User defined maximum number for the scale, overrides maximum value from data. +| min | double | [Yes](#scriptable) | User defined minimum number for the scale, overrides minimum value from data. +| offset | boolean | [Yes](#scriptable) | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| position | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) | [Yes](#scriptable) | Position of the axis. +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| singleStacked | boolean | - | If you might want to stack positive and negative values together. +| stack | String | [Yes](#scriptable) | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | [Yes](#scriptable) | If the axis are stacked. +| stackWeight | double | [Yes](#scriptable) | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| suggestedMax | double | [Yes](#scriptable) | Adjustment used when calculating the maximum data value. +| suggestedMin | double | [Yes](#scriptable) | Adjustment used when calculating the minimum data value. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| bounds | [BoundsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BoundsCallback.html) | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| offset | [ScaleOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleOffsetCallback.html) | boolean +| position | [ScalePositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScalePositionCallback.html) | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| stack | [StackCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackCallback.html) | String +| stacked | [StackedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | boolean +| stackWeight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | double +| suggestedMax | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| suggestedMin | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Ticks + +The logarithmic axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLogarithmicTick.html). + +```java +// creates a logarithmic axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets and gets the max value +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | - | The tick alignment along the axis. +| autoSkip | boolean | - | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | - | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks. +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | - | The tick alignment perpendicular to the axis. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| includeBounds | boolean | - | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | - | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | - | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| minRotation | int | - | The minimum rotation for tick labels. +| mirror | boolean | - | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| numberFormat | [NumberFormatOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/NumberFormatOptions.html) | [Yes](#ticks-scriptable-options) | The number format options used by the default label formatter.
See [INTL number format](../intl/NumberFormat) documentation +| padding | int | - | The padding between the tick label and the axis. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int | [Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +The further customization of ticks, a [callback](#callback) is provided. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a logarithmic axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| numberFormat | [NumberFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/NumberFormatCallback.html) | [NumberFormatItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/NumberFormatItem.html) +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. For example, adding a dollar sign ('$'). To do this, you need to implement a ticks callback in the axis configuration. + +To apply a custom callback, you can set a [TickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TickCallback.html) instance to the axis options, as following: + +```java +axis.getTicks().setCallback(new TickCallback(){ + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, double value, int index, List values){ + // add $ + return "$" + value; + } + +}); +``` + +See [INTL number format](../intl/NumberFormat) documentation if you want to use a number formatter, provided out-of-the-box. + +The callback can return a string (for single line) or a list of strings (for multiple lines). + +### NoSelectedDatasetTicksCallback callback + +**Charba** provides a common implementation for tick callback to set the decimal digits of ticks in case of all data sets are hidden, to avoid the annoying standard format of doubles. + +To apply the callback, you can set an instance to the axis options, as following: + +```java +// creates a logarithmic axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets the option by a callback +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback()); +``` + +The default decimal precision is `2`. A custom precision can be set by the constructor of callback, as following: + +```java +// creates a logarithmic axis +CartesianLogarithmicAxis axis = new CartesianLogarithmicAxis(chart); +// sets the option by a callback +// 3 decimal digits +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback(3)); +``` \ No newline at end of file diff --git a/versioned_docs/version-6.5/axes/PointLabels.md b/versioned_docs/version-6.5/axes/PointLabels.md new file mode 100644 index 000000000..ceb3a42c0 --- /dev/null +++ b/versioned_docs/version-6.5/axes/PointLabels.md @@ -0,0 +1,112 @@ +--- +id: PointLabels +title: Point labels +hide_title: true +sidebar_label: Point labels +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Point Labels + +The [point labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialPointLabels.html) options are used to configure the point labels that are shown on the perimeter of the scale. They can be found in the pointLabels sub options object. +Note + + + +:::caution +The point labels can be **ONLY** applied to radial axes.
+These options only apply if **display** is **true**. +::: + +The [RadialPointLabels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialPointLabels.html) provides all **set** and **get** methods to manage the configuration, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables point labels +axis.getPointLabels().setDisplay(true); +// sets and gets the color value +axis.getPointLabels().setColor(HtmlColor.RED); + +IsColor color = axis.getPointLabels().getColor(); +``` + +Table with options: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Background color of the point label. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of label backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | [Yes](#scriptable) | The border radius of the point label (in pixels). +| centerPointLabels | boolean | - | If `true`, point labels are centered. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | - | If `true`, point labels are shown. When Display.AUTO, the label is hidden if it overlaps with another label. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Color of point labels. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#scriptable) | Font of point labels. +| padding | int | [Yes](#scriptable) | Padding between chart and point labels, in pixel. + +The further customization of point labels, a [callback](#callback) is provided. + +### Scriptable + +Scriptable options at grid level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables point labels +axis.getPointLabels().setDisplay(true); +// sets the option by a callback +axis.getPointLabels().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<ScaleContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| padding | [SimplePaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimplePaddingCallback.html) | int + +### Callback + +Callback implementation can transform data labels to point labels. The default implementation simply returns the current string. + +To apply an own callback, you can set a [PointLabelCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointLabelCallback.html) instance to the axis options, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables point labels +axis.getPointLabels().setDisplay(true); +// sets callback +axis.getPointLabels().setCallBack(new PointLabelCallback(){ + + /** + * Callback function to transform data labels to point labels. The default implementation simply returns the current string. + * + * @param axis axis instance where this callback as been defined + * @param item label of current label + * @param index index of the label + * @return new label to apply to point label + */ + @Override + public String onCallback(Axis axis, String item, int index){ + // logic + return item; + } + +}); +``` + +The callback can return a string (for single line) or a list of strings (for multiple lines). diff --git a/versioned_docs/version-6.5/axes/Radial.md b/versioned_docs/version-6.5/axes/Radial.md new file mode 100644 index 000000000..30909aa75 --- /dev/null +++ b/versioned_docs/version-6.5/axes/Radial.md @@ -0,0 +1,224 @@ +--- +id: RadialAxes +title: Radial axes +hide_title: true +sidebar_label: Radial axes +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Radial Axes + +[Radial axes](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialAxis.html) are used specifically for the radar and polar area chart types. These axes overlay the chart area, rather than being positioned on one of the edges. + +Radial axes could be only + + * **linear**, is use to chart numerical data. As the name suggests, linear interpolation is used to determine where a value lies in relation the center of the axis. + +The [radial axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialAxis.html) is use to chart numerical data. + + + +Here is an example how to create a radial axis: + +```java +// creates a radial axis with default scale id "r" and default kind "r" +RadialAxis axis = new RadialAxis(chart); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis); +``` + +The axis has configuration properties for [ticks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialLinearTick.html), [angle lines](AngleLines) (line that appear in a radar chart outward from the center), [point labels](PointLabels) (labels around the edge in a radar chart): + +## Options + +The radial linear axis allows to define a number of properties, used to display the data. + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// sets and gets the max value +axis.setMax(100); + +double max = axis.getMax(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| animate | boolean | - | If `true`, animate scaling the chart from the center. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| beginAtZero | boolean | [Yes](#scriptable) | If `true`, scale will include 0 if it is not already included. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| max | double | [Yes](#scriptable) | User defined maximum number for the scale, overrides maximum value from data. +| min | double | [Yes](#scriptable) | User defined minimum number for the scale, overrides minimum value from data. +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| startAngle | double | [Yes](#scriptable) | Starting angle to draw arcs for the first item in a data set. In degrees, 0 is at top. +| suggestedMax | double | [Yes](#scriptable) | Adjustment used when calculating the maximum data value. +| suggestedMin | double | [Yes](#scriptable) | Adjustment used when calculating the minimum data value. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +RadialAxis axis = new RadialAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| beginAtZero | [BeginAtZeroCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BeginAtZeroCallback.html) | boolean +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| startAngle | [StartAngleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StartAngleCallback.html) | double +| suggestedMax | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| suggestedMin | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Double> | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Ticks + +The radial linear axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadialLinearTick.html). + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// sets and gets the max value +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks. +| count | int | [Yes](#ticks-scriptable-options | The number of ticks to generate. If specified, this overrides the automatic generation. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| maxTicksLimit | int | [Yes](#ticks-scriptable-options | Maximum number of ticks and gridlines to show. +| numberFormat | [NumberFormatOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/NumberFormatOptions.html) | [Yes](#ticks-scriptable-options) | The number format options used by the default label formatter.
See [INTL number format](../intl/NumberFormat) documentation. +| padding | int | - | The padding between the tick label and the axis. +| precision | int | [Yes](#ticks-scriptable-options | If defined and `stepSize` is not specified, the step size will be rounded to this many decimal places. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| stepSize | double | [Yes](#ticks-scriptable-options) | User defined fixed step size for the scale. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int | [Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +The further customization of ticks, a [callback](#callback) is provided. + +
See [padding documentation](../configuration/Commons#padding) for more details. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| count | [CountCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CountCallback.html) | int +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| maxTicksLimit | [MaxTicksLimitCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MaxTicksLimitCallback.html) | int +| numberFormat | [NumberFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/NumberFormatCallback.html) | [NumberFormatItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/NumberFormatItem.html) +| precision | [PrecisionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PrecisionCallback.html) | int +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| stepSize | [StepSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StepSizeCallback.html) | double +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. For example, adding a dollar sign ('$'). To do this, you need to implement a ticks callback in the axis configuration. + +To apply a custom callback, you can set a [TickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TickCallback.html) instance to the axis options, as following: + +```java +axis.getTicks().setCallback(new TickCallback(){ + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, double value, int index, List values){ + // add $ + return "$" + value; + } + +}); +``` + +See [INTL number format](../intl/NumberFormat) documentation if you want to use a number formatter, provided out-of-the-box. + +### NoSelectedDatasetTicksCallback callback + +**Charba** provides a common implementation for tick callback to set the decimal digits of ticks in case of all data sets are hidden, to avoid the annoying standard format of doubles. + +To apply the callback, you can set an instance to the axis options, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// sets the option by a callback +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback()); +``` + +The default decimal precision is `2`. A custom precision can be set by the constructor of callback, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// sets the option by a callback +// 3 decimal digits +axis.getTicks().setCallback(new NoSelectedDatasetTicksCallback(3)); +``` \ No newline at end of file diff --git a/versioned_docs/version-6.5/axes/ScaleTitle.md b/versioned_docs/version-6.5/axes/ScaleTitle.md new file mode 100644 index 000000000..644210029 --- /dev/null +++ b/versioned_docs/version-6.5/axes/ScaleTitle.md @@ -0,0 +1,40 @@ +--- +id: ScaleTitle +title: Scale title +hide_title: true +sidebar_label: Title +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Axis Title + +When creating a chart, you want to tell the viewer what data they are viewing. To do this, you need to label the axis. + + + +:::caution +The scale title can be **ONLY** applied to cartesian axes. +::: + +The [axis title](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianScaleTitle.html) provides all **set** and **get** methods to manage the configuration, as following: + +```java +// creates an axis +CartesianLinearAxis axis = new CartesianLinearAxis(chart); +// enables the title +axis.getTitle().setDisplay(true); +// sets and gets color of title +axis.getTitle().setColor(HtmlColor.RED); + +IsColor color = axis.getTitle().getColor(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| align | [ScaleTitleAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ScaleTitleAlign.html) | Alignment of the scale label. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color of scale label. +| display | boolean | `false` | If `true`, the scale label is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font of scale label. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | The padding of title.
See [padding documentation](../configuration/Commons#padding) for more details. diff --git a/versioned_docs/version-6.5/axes/Time.md b/versioned_docs/version-6.5/axes/Time.md new file mode 100644 index 000000000..017e955cf --- /dev/null +++ b/versioned_docs/version-6.5/axes/Time.md @@ -0,0 +1,328 @@ +--- +id: CartesianTimeAxes +title: Cartesian time +hide_title: true +sidebar_label: Time +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Cartesian Time Axes + +The [time axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeAxis.html) is used to display times and dates. When building its [ticks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeTick.html), it will automatically calculate the most comfortable unit base on the size of the scale. + + + +Here are some example how to create category axes: + +```java +// creates a time axis with default scale id "x" and default kind "x" +CartesianTimeAxis axis1 = new CartesianTimeAxis(chart); + +// creates a time axis with scale id "my-axis" and default kind "x" +CartesianTimeAxis axis2 = new CartesianTimeAxis(chart, "my-axis"); + +// creates a time axis with scale id "my-axis" and default kind "x" +CartesianTimeAxis axis3 = new CartesianTimeAxis(chart, ScaleId.create("my-axis")); + +// creates a time axis with default scale id "x" and custom kind "x" +CartesianTimeAxis axis4 = new CartesianTimeAxis(chart, AxisKind.X); + +// creates a time axis with scale id "my-axis" and custom kind "x" +CartesianTimeAxis axis5 = new CartesianTimeAxis(chart, "my-axis", AxisKind.X; + +// creates a time axis with scale id "my-axis" and custom kind "x" +ScaleId myAxis = ScaleId.create("my-axis"); +CartesianTimeAxis axis6 = new CartesianTimeAxis(chart, myAxis, AxisKind.X); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis1, ...); +``` + +## Datasets + +To use time axis, you must use [DataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/DataPoint.html) in order to set the date object in the axis. + +The `x` axis data points can be specified via the **setX** method when using the time axis. + +Here is the example: + +```java +// creates a dataset +BarDataset dataset = chart.newDataset(); +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setY(number_value1); +dp1.setX(new Date(time1)); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setY(number_value1); +dp2.setX(new Date(time2)); +// sets the datapoints to the dataset +dataset.setDataPoints(dp1, dp2); +// sets the datasets to the chart +chart.getData().setDatasets(dataset); +``` + +## Options + +The following options are provided by the time axis. + +The time axes are providing the capability to set and get the options, by the **set** and **get** methods, as following: + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets and gets the reverse value +axis.setReverse(true); + +boolean reverse = axis.isReverse(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | [Yes](#scriptable) | Determines the scale bounds on axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| max | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | [Yes](#scriptable) | User defined maximum date for the scale, overrides maximum value from data. +| min | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | [Yes](#scriptable) | User defined minimum date for the scale, overrides minimum value from data +| offset | boolean | [Yes](#scriptable) | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| offsetAfterAutoskip | boolean | - | If `true`, bar chart offsets are computed with auto skipped ticks. +| position | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) | [Yes](#scriptable) | Position of the axis. +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| singleStacked | boolean | - | If you might want to stack positive and negative values together. +| stack | String | [Yes](#scriptable) | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | [Yes](#scriptable) | If the axis are stacked. +| stackWeight | double | [Yes](#scriptable) | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| bounds | [BoundsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BoundsCallback.html) | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Object> | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) - int - double +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Object> | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) - int - double +| offset | [ScaleOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleOffsetCallback.html) | boolean +| position | [ScalePositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScalePositionCallback.html) | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| stack | [StackCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackCallback.html) | String +| stacked | [StackedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | boolean +| stackWeight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Time + +The time axis provides a [Time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Time.html) object to configure how times must be managed on axis. It provides the **set** and **get** methods as following: + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets and gets the unit value +axis.getTime().setUnit(TimeUnit.DAY); +// sets and gets the tooltip format value +axis.getTime().setTooltipFormat(TimeUnit.day.getDefaultFormat()); + +TimeUnit unit = axis.getTime().getUnit(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| isoWeekday | [IsoWeekDay](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsoWeekDay.html) | The first day of the week. +| minUnit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | The minimum display format to be used for a time unit. +| parser | String | `null` | Interpreted as a custom format to be used to parse the date. +| round | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | If defined, dates will be rounded to the start of this unit. +| tooltipFormat | String | Format string to use for the tooltip. +| unit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | If defined, will force the unit to be a certain type. + +The following time measurements are supported and are mapped in the [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) enumeration, to force a certain unit: + + * millisecond + * second + * minute + * hour + * day + * week + * month + * quarter + * year + + +The [Time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Time.html) object is also providing another object to set the display formats, based on [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html). + +The [DisplayFormats](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/DisplayFormats.html) can be used as following: + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets and gets the unit value +axis.getTime().setUnit(TimeUnit.DAY); +// sets display format for the unit +axis.getTime().getDisplayFormats().setDisplayFormat(TimeUnit.DAY, "MMM D h:mm a"); +``` + +This method can override the defaults. To see the defaults, see the [LUXON date adapter](../DateAdapters). + +## Adapters + +The adapters options are used to configure the adapter for [LUXON date library](../DateAdapters). + +The [adapters options](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Adapters.html) configuration is nested in the scale configuration as following: + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets and gets the locale to date adapter options +axis.getAdapters().getDate().setLocale(CLocale.US); + +CLocale locale = axis.getAdapters().getDate().getLocale(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | Using locale specifying the language to use generating or interpreting strings. +| zone | [TimeZone](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/TimeZone.html) | Implementation recognizes the time zone names of the IANA time zone database. +| outputCalendar | [Calendar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/Calendar.html) | The calendar type to use. +| numberingSystem | [NumberingSystem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/NumberingSystem.html) | The numbering system to use. + +For more details, have a look how to configure a [Luxon](../DateAdapters) date adapters. + +## Ticks + +The time axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeTick.html). + +```java +// creates a time axis +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets and gets the color to ticks +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | - | The tick alignment along the axis. +| autoSkip | boolean | - | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | - | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | CrossAlign.NEAR | The tick alignment perpendicular to the axis. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| includeBounds | boolean | - | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | - | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | - | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| minRotation | int | - | The minimum rotation for tick labels. +| mirror | boolean | - | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| padding | int | - | The padding between the tick label and the axis. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| source | [TickSource](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickSource.html) | - | How ticks are generated on axis time. +| stepSize | int | [Yes](#ticks-scriptable-options) | The number of units between grid lines. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int |[Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +The further customization of ticks, a [callback](#callback) is provided. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates the axis for chart +CartesianTimeAxis axis = new CartesianTimeAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| stepSize | [StepSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StepSizeCallback.html) | int +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. + +To apply a custom callback, you can set a [TimeTickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TimeTickCallback.html) instance to the axis options, as following: + +```java +axis.getTicks().setCallback(new TimeTickCallback(){ + + private final DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.GERMANY); + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick as date + * @param label label of tick, passed by CHART.JS formatting the date by the selected {@link TimeUnit} and its display + * format. + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, Date value, String label, int index, List values){ + return dateTimeFormat.format(value); + } + +}); +``` + +The callback is providing a specific list of items ([TimeTickItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TimeTickItem.html)) which maps [Chart.JS](http://www.chartjs.org/) object with the values (as date) and major booleans. + +See [INTL date time format](../intl/DateTimeFormat) documentation if you want to use a date formatter, provided out-of-the-box. + +The callback can return a string (for single line) or a list of strings (for multiple lines). diff --git a/versioned_docs/version-6.5/axes/TimeSeries.md b/versioned_docs/version-6.5/axes/TimeSeries.md new file mode 100644 index 000000000..66edcad3e --- /dev/null +++ b/versioned_docs/version-6.5/axes/TimeSeries.md @@ -0,0 +1,332 @@ +--- +id: CartesianTimeSeriesAxes +title: Cartesian time series +hide_title: true +sidebar_label: Time series +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Cartesian Time Series Axes + +The [time series axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeSeriesAxis.html) is used to display times and dates. When building its [ticks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeTick.html), it will automatically calculate the most comfortable unit base on the size of the scale. + +:::info +The time series axis extends from the time axis and supports all the same options. However, for the time series scale, each data point is spread equidistant. +::: + + + +Here are some example how to create category axes: + +```java +// creates a time series axis with default scale id "x" and default kind "x" +CartesianTimeSeriesAxis axis1 = new CartesianTimeSeriesAxis(chart); + +// creates a time series axis with scale id "my-axis" and default kind "x" +CartesianTimeSeriesAxis axis2 = new CartesianTimeSeriesAxis(chart, "my-axis"); + +// creates a time series axis with scale id "my-axis" and default kind "x" +CartesianTimeSeriesAxis axis3 = new CartesianTimeSeriesAxis(chart, ScaleId.create("my-axis")); + +// creates a time series axis with default scale id "x" and custom kind "x" +CartesianTimeSeriesAxis axis4 = new CartesianTimeSeriesAxis(chart, AxisKind.X); + +// creates a time series axis with scale id "my-axis" and custom kind "x" +CartesianTimeSeriesAxis axis5 = new CartesianTimeSeriesAxis(chart, "my-axis", AxisKind.X; + +// creates a time series axis with scale id "my-axis" and custom kind "x" +ScaleId myAxis = ScaleId.create("my-axis"); +CartesianTimeSeriesAxis axis6 = new CartesianTimeSeriesAxis(chart, myAxis, AxisKind.X); + +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis1, ...); +``` + +## Datasets + +To use time series axis, you must use [DataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/DataPoint.html) in order to set the date object in the axis. + +The `x` axis data points can be specified via the **setX** method when using the time axis. + +Here is the example: + +```java +// creates a dataset +BarDataset dataset = chart.newDataset(); +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setY(number_value1); +dp1.setX(new Date(time1)); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setY(number_value1); +dp2.setX(new Date(time2)); +// sets the datapoints to the dataset +dataset.setDataPoints(dp1, dp2); +// sets the datasets to the chart +chart.getData().setDatasets(dataset); +``` + +## Options + +The following options are provided by the time series axis. + +The time series axes are providing the capability to set and get the options, by the **set** and **get** methods, as following: + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the reverse value +axis.setReverse(true); + +boolean reverse = axis.isReverse(); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| alignToPixels | boolean | [Yes](#scriptable) | Align pixel values to device pixels. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | The background color of scale area. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | [Yes](#scriptable) | Determines the scale bounds on axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | [Yes](#scriptable) | If `Display.TRUE`, the axis is shown. +| max | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | [Yes](#scriptable) | User defined maximum date for the scale, overrides maximum value from data. +| min | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | [Yes](#scriptable) | User defined minimum date for the scale, overrides minimum value from data +| offset | boolean | [Yes](#scriptable) | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| offsetAfterAutoskip | boolean | - | If `true`, bar chart offsets are computed with auto skipped ticks. +| position | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) | [Yes](#scriptable) | Position of the axis. +| reverse | boolean | [Yes](#scriptable) | Reverses order of tick labels. +| singleStacked | boolean | - | If you might want to stack positive and negative values together. +| stack | String | [Yes](#scriptable) | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | [Yes](#scriptable) | If the axis are stacked. +| stackWeight | double | [Yes](#scriptable) | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| weight | double | [Yes](#scriptable) | The weight used to sort the axis. Higher weights are further away from the chart area. + +### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a category axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets the option by a callback +axis.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| alignToPixels | [AlignToPixelsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AlignToPixelsCallback.html) | boolean +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| bounds | [BoundsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BoundsCallback.html) | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html) | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| max | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Object> | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) - int - double +| min | [MinMaxCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MinMaxCallback.html)<Object> | [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) - int - double +| offset | [ScaleOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleOffsetCallback.html) | boolean +| position | [ScalePositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScalePositionCallback.html) | [AxisPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisPosition.html) - [AxisPositionItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AxisPositionItem.html) +| reverse | [ReverseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ReverseCallback.html) | boolean +| stack | [StackCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackCallback.html) | String +| stacked | [StackedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | boolean +| stackWeight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StackedCallback.html) | double +| weight | [ScaleWeightCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleWeightCallback.html) | double + +## Time + +The time series axis provides a [Time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Time.html) object to configure how times must be managed on axis. It provides the **set** and **get** methods as following: + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the unit value +axis.getTime().setUnit(TimeUnit.DAY); +// sets and gets the tooltip format value +axis.getTime().setTooltipFormat(TimeUnit.day.getDefaultFormat()); + +TimeUnit unit = axis.getTime().getUnit(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| isoWeekday | [IsoWeekDay](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsoWeekDay.html) | The first day of the week. +| minUnit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | The minimum display format to be used for a time unit. +| parser | String | `null` | Interpreted as a custom format to be used to parse the date. +| round | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | If defined, dates will be rounded to the start of this unit. +| tooltipFormat | String | Format string to use for the tooltip. +| unit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | If defined, will force the unit to be a certain type. + +The following time measurements are supported and are mapped in the [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) enumeration, to force a certain unit: + + * millisecond + * second + * minute + * hour + * day + * week + * month + * quarter + * year + + +The [Time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Time.html) object is also providing another object to set the display formats, based on [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html). + +The [DisplayFormats](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/DisplayFormats.html) can be used as following: + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the unit value +axis.getTime().setUnit(TimeUnit.DAY); +// sets display format for the unit +axis.getTime().getDisplayFormats().setDisplayFormat(TimeUnit.DAY, "MMM D h:mm a"); +``` + +This method can override the defaults. To see the defaults, see the [LUXON date adapter](../DateAdapters). + +## Adapters + +The adapters options are used to configure the adapter for [LUXON date library](../DateAdapters). + +The [adapters options](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Adapters.html) configuration is nested in the scale configuration as following: + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the locale to date adapter options +axis.getAdapters().getDate().setLocale(CLocale.US); + +CLocale locale = axis.getAdapters().getDate().getLocale(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | Using locale specifying the language to use generating or interpreting strings. +| zone | [TimeZone](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/TimeZone.html) | Implementation recognizes the time zone names of the IANA time zone database. +| outputCalendar | [Calendar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/Calendar.html) | The calendar type to use. +| numberingSystem | [NumberingSystem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/NumberingSystem.html) | The numbering system to use. + +For more details, have a look how to configure a [Luxon](../DateAdapters) date adapters. + +## Ticks + +The time series axis provides the following options for configuring [tick marks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeTick.html). + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets and gets the color to ticks +axis.getTicks().setColor(HtmlColor.RED); + +IsColor color = axis.gteTicks().getColor(); +``` + + + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | - | The tick alignment along the axis. +| autoSkip | boolean | - | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | - | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | - | The padding of tick backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | Color of ticks.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | CrossAlign.NEAR | The tick alignment perpendicular to the axis. +| display | boolean | - | If `true`, the tick marks are shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#ticks-scriptable-options) | Font of ticks.
See [Font](../defaults/DefaultsCharts#font). +| includeBounds | boolean | - | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | - | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | - | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| minRotation | int | - | The minimum rotation for tick labels. +| mirror | boolean | - | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| padding | int | - | The padding between the tick label and the axis. +| sampleSize | int | - | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | [Yes](#ticks-scriptable-options) | If `true`, draw a background behind the tick labels +| source | [TickSource](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickSource.html) | - | How ticks are generated on axis time. +| stepSize | int | [Yes](#ticks-scriptable-options) | The number of units between grid lines. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#ticks-scriptable-options) | The color of the stroke around the text. +| textStrokeWidth | int |[Yes](#ticks-scriptable-options) | Stroke width around the text. +| z | int | - | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +The further customization of ticks, a [callback](#callback) is provided. + +### Ticks scriptable options + +Scriptable options at ticks level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +All scriptable options callbacks will get a [ScaleContext](../configuration/ScriptableOptions#scale-context) instance. + +```java +// creates a time series axis +CartesianTimeSeriesAxis axis = new CartesianTimeSeriesAxis(chart); +// sets the option by a callback +axis.getTicks().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(ScaleContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backdropColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ScaleContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| showLabelBackdrop | [ShowLabelBackdropCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ShowLabelBackdropCallback.html) | boolean +| stepSize | [StepSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/StepSizeCallback.html) | int +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int + +### Callback + +It is also common to want to change the tick marks to include information about the data type. + +To apply a custom callback, you can set a [TimeTickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TimeTickCallback.html) instance to the axis options, as following: + +```java +axis.getTicks().setCallback(new TimeTickCallback(){ + + private final DateTimeFormat dateTimeFormat = new DateTimeFormat(CLocale.GERMANY); + + /** + * Changes the tick marks to include information about the data type. + * + * @param axis axis instance where this callback as been defined + * @param value value of tick as date + * @param label label of tick, passed by CHART.JS formatting the date by the selected {@link TimeUnit} and its display + * format. + * @param index index of tick + * @param values list of all tick values + * @return the tick to apply or if the callback returns null the associated grid line will be hidden. + */ + public String onCallback(Axis axis, Date value, String label, int index, List values){ + return dateTimeFormat.format(value); + } + +}); +``` + +The callback is providing a specific list of items ([TimeTickItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TimeTickItem.html)) which maps [Chart.JS](http://www.chartjs.org/) object with the values (as date) and major booleans. + +See [INTL date time format](../intl/DateTimeFormat) documentation if you want to use a date formatter, provided out-of-the-box. + +The callback can return a string (for single line) or a list of strings (for multiple lines). diff --git a/versioned_docs/version-6.5/charts/Api.md b/versioned_docs/version-6.5/charts/Api.md new file mode 100644 index 000000000..b50d51ee0 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Api.md @@ -0,0 +1,545 @@ +--- +id: Api +title: Api +hide_title: true +sidebar_label: Api +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Chart API + +For each chart, there are a set of methods which are wrapping the [Chart.JS API](http://www.chartjs.org/docs/latest/developers/api.html). These are available on all charts created with **Charba**. + +### draw + +Use this to draw the chart instance that is created. + +```java +// draws a specific chart instance +chart.draw(); +``` + +This method works with **drawOnAttach** options which can be used setting `true` to draw the chart when the chart has been attached to the parent GWT element. + +### destroy + +Use this to destroy any chart instances that are created. This will clean up any references stored within **Charba**, along with any associated event listeners attached. + +```java +// destroys a specific chart instance +chart.destroy(); +``` + +This method works with **destroyOnDetach** options which can be used setting `true` to destroy the chart when the chart has been detached from the parent GWT element. + +### update + +Triggers an update of the chart. This can be safely called after updating the data or options object. This will update all scales, legends, and then re-render the chart. + +```java +// gets all datasets of chart +List datasets = chart.getData().getDatasets(); +// updates the data of datasets +for (Dataset ds : datasets){ + ds.getData().add(getRandomDigit(negative)); +} +// updates the chart +chart.update(); +``` + +The update method can also be invoked providing a mode key or a mode configuration. + +A [mode key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/TransitionMode.html) can be provided to indicate what should be updated and what animation configuration should be used. + +```java +// creates a custom mode +TransitionMode mode = TransitionMode.create("myMode"); +// creates an animation transitions configuration for my mode +AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode); +// changes animation configuration setting duration to 10 seconds +animationMode.getAnimation().setDuration(10000); +// gets all datasets of chart +List datasets = chart.getData().getDatasets(); +// updates the data of datasets +for (Dataset ds : datasets){ + ds.getData().add(getRandomDigit(negative)); +} +// updates the chart using my mode +chart.update(mode); +``` + +The defaults modes are mapped in the [DefaultTransitionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html) enumeration and they are: + + * **ACTIVE** uses the animation configuration when an element is hovering + * **HIDE** uses the animation configuration when a dataset is hidden (by using legend or [hide](#hide) method). + * **RESET** uses the animation configuration when an element is resetting. + * **RESIZE** uses the animation configuration when an element is resizing. + * **SHOW** uses the animation configuration when a dataset is shown (by using legend or [show](#show) method). + * **NONE** used to ignore any animation configuration. + +```java +// gets all datasets of chart +List datasets = chart.getData().getDatasets(); +// updates the data of datasets +for (Dataset ds : datasets){ + ds.getData().add(getRandomDigit(negative)); +} +// updates the chart using "hide" mode +chart.update(DefaultTransitionMode.HIDE); +``` + +The update can be also invoke providing a specific animation configuration, created at runtime and not assigned to any mode. + +A [configuration object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/UpdateConfiguration.html) can be provided with additional configuration for the update process. This is useful when `update` is manually called inside an event handler and some different animation is desired. + +Example: + +```java +// creates an update configuration +UpdateConfiguration configuration = new UpdateConfiguration(); +// sets easing and duration to 4 seconds +configuration.setEasing(Easing.EASE_IN_OUT_QUART); +configuration.setDuration(4000); +// updates the chart using my configuration +chart.update(configuration); +``` + +### reconfigure + +To update the options changing the configuration at runtime, mutating the options property in place. + +```java +// changes the title directly on chart options +chart.getOptions().getTitle().setText("new Title"); +// reconfigures and updates the chart +chart.reconfigure(); +``` + +The reconfigure method can also be invoked providing a mode key or a mode configuration. + +A [mode key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsAnimationModeKey.html) can be provided to indicate what should be updated and what animation configuration should be used. + +```java +// creates a custom mode +TransitionMode mode = TransitionMode.create("myMode"); +// creates an animation transitions configuration for my mode +AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode); +// changes animation configuration setting duration to 10 seconds +animationMode.getAnimation().setDuration(10000); +// changes the title directly on chart options +chart.getOptions().getTitle().setText("new Title"); +// reconfigures and updates the chart using my mode +chart.reconfigure(mode); +``` + +The defaults modes are mapped in the [DefaultTransitionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html) enumeration and they are: + + * **ACTIVE** uses the animation configuration when an element is hovering + * **HIDE** uses the animation configuration when a dataset is hidden (by using legend or [hide](#hide) method). + * **RESET** uses the animation configuration when an element is resetting. + * **RESIZE** uses the animation configuration when an element is resizing. + * **SHOW** uses the animation configuration when a dataset is shown (by using legend or [show](#show) method). + * **NONE** used to ignore any animation configuration. + +```java +// changes the title directly on chart options +chart.getOptions().getTitle().setText("new Title"); +// updates the chart using "hide" mode +chart.reconfigure(DefaultTransitionMode.HIDE); +``` + +The update can be also invoke providing a specific animation configuration, created at runtime and not assigned to any mode. + +A [configuration object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/UpdateConfiguration.html) can be provided with additional configuration for the update process. This is useful when `update` is manually called inside an event handler and some different animation is desired. + +Example: + +```java +// changes the title directly on chart options +chart.getOptions().getTitle().setText("new Title"); +// creates an update configuration +UpdateConfiguration configuration = new UpdateConfiguration(); +// sets easing and duration to 4 seconds +configuration.setEasing(Easing.EASE_IN_OUT_QUART); +configuration.setDuration(4000); +// reconfigures and updates the chart using my configuration +chart.reconfigure(configuration); +``` + +### reset + +Resets the chart to it's state before the initial animation. A new animation can then be triggered using [update](#update). + +```java +// resets the chart +chart.reset(); +``` + +### render + +Triggers a redraw of all chart elements. Note, this does not update elements for new data. Use [update](#update) in that case. + +```java +// forces the chart rendering +chart.render(); +``` + +### stop + +Uses this to stop any current animation loop. This will pause the chart during any current animation frame. Call [render](#render) to re-animate. + +```java +// stops the charts animation loop at its current frame +chart.stop(); +``` + +### resize + +Use this to manually resize the canvas element. This is run each time the canvas container is resized, but you can call this method manually if you change the size of the canvas nodes container element. + + +You can call `.resize()` with no parameters to have the chart take the size of its container element, or you can pass explicit dimensions. + +```java +// resizes and redraws the chart to fill its container element +chart.resize(); +// resizes and redraws the chart to a specific size (in pixels) +chart.resize(400, 200); +``` + +### clear + +Will clear the chart canvas. Used extensively internally between animation frames, but you might find it useful. + +```java +// clears the canvas that chart instance is drawn on +chart.clear(); +``` + +### toBase64Image + +Returns a base 64 encoded string of the chart which containing a representation of the image in the different format and quality. + +The method can accept the image format that you want by an [ImageMimeType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ImageMimeType.html) instance and a number between 0 and 1 indicating the image quality to use for image formats that use lossy compression. + +The default image type is in [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) format and the default image quality is 0.92. + +```java +// gets the PNG image of the chart and default quality +String image = chart.toBase64Image(); +// gets the JPEG image of the chart and default quality +String imageJpeg = chart.toBase64Image(ImageMimeType.JPEG); +// gets the PNG image of the chart and maximum quality +String imagePngMaxQuality = chart.toBase64Image(ImageMimeType.PNG, 1); +// or +String imagePngMaxQuality1 = chart.toBase64Image(1); +``` + +### getDatasetItem + +Looks for the dataset that matches the current index and returns that the dataset item. + +The [dataset item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DatasetItem.html) will contain information about the dataset, depending on the chart type. + +```java +// gets the dataset item at index 0 +DatasetItem item = chart.getDatasetItem(0); +// uses the item +if (item.isHidden() || !item.isVisible()){ + ... + ... +} +``` + +### getDatasetAtEvent + +Looks for the datasets that matches the position of the event and returns a list of dataset referencef. + +The [dataset reference](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DatasetReference.html) will contain information about indexes of dataset and the element which depends on the chart type. + +```java +// gets the dataset references by event instance +List references = chart.getDatasetAtEvent(event); +// uses the references +for (DatasetReference reference : references){ + ... + ... +} +``` + +### isDatasetVisible + +Looks for the dataset if it's visible or not, selected by index. It returns `false` if index of out of range or if the dataset is hidden. + +```java +// checks if the dataset at index 0 is visible +if (chart.isDatasetVisible(0)){ + ... + ... +} +``` + +### getVisibleDatasetCount + +Returns the amount of visible datasets on the chart. If chart is not initiated, it returns a [undefined value](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/Undefined.html#INTEGER). + +```java +// gets the amount of visible datasets of chart +int amount = chart.getVisibleDatasetCount(); +if (amount > 0){ + ... + ... +} +``` + +### getSortedVisibleDatasetItems + +Returns a list of all the dataset items in the order that they are drawn on the canvas that are not hidden. + +```java +// gets the list of visible datasets of chart +List items = chart.getSortedVisibleDatasetItems(); +// uses the items +for (DatasetItem item : items){ + ... + ... +} +``` + +### setDatasetVisibility + +Sets the visibility for a given dataset. This can be used to build a chart legend in HTML. During click on one of the HTML items, you can call `setDatasetVisibility` to change the appropriate dataset. + +```java +// hides dataset at index 1 +chart.setDatasetVisibility(1, false); +// chart now renders with dataset hidden +chart.update(); +``` + +### toggleDataVisibility + +Toggles the visibility of an item in all datasets. A dataset needs to explicitly support this feature for it to have an effect. + +```java +// toggles the item in all datasets, at index 2 +chart.toggleDataVisibility(2); +// chart now renders with item hidden +chart.update(); +``` + +### isDataVisible + +Returns the stored visibility state of an data index for all datasets. Set by [toggleDataVisibility](#toggledatavisibility). A dataset should use this method to determine if an item should not be visible. + +```java +// checks if dataset 2 is visible +boolean visible = chart.isDataVisible(2); +``` + +### hide + +If the data index is not specified, sets the visibility for the given dataset to `false`. Updates the chart and animates the dataset with [DefaultTransitionMode.HIDE](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html#HIDE) mode. + +```java +// hides dataset at index 1 and does 'hide' animation. +chart.hide(1); +``` + +If the data index is specified, sets the hidden flag of that element to `true`. Updates the chart and animates the dataset with [DefaultTransitionMode.HIDE](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html#HIDE) mode. + +```java +// hides data at index 1 of dataset at index 0 and does 'hide' animation. +chart.hide(0, 1); +``` + +### show + +If the data index is not specified, sets the visibility for the given dataset to `true`. Updates the chart and animates the dataset with [DefaultTransitionMode.SHOW](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html#SHOW) mode. + +```java +// shows dataset at index 1 and does 'show' animation. +chart.show(1); +``` + +If the data index is specified, sets the hidden flag of that element to `false`. Updates the chart and animates the dataset with [DefaultTransitionMode.SHOW](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html#SHOW) mode. + +```java +// shows data at index 1 of dataset at index 0 and does 'show' animation. +chart.show(0, 1); +``` + +### Active elements + +Sets the active (hovered) elements for the chart. You can create a list of [ActiveDatasetElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ActiveDatasetElement.html) and set which dataset and/or data must be active, programmatically. + +```java +// creates a active element for data set at index 0 and for data at index 2 +ActiveDatasetElement active0 = new ActiveDatasetElement(0, 2); +// creates a active element for data set at index 1 and for data at index 2 +ActiveDatasetElement active1 = new ActiveDatasetElement(1, 2); +// sets the elements +chart.setActiveElements(active0, active1); + +chart.update(); +``` + + + +You can activate the tooltip programmatically. + +```java +// creates a active element for data set at index 0 and for data at index 2 +ActiveDatasetElement active0 = new ActiveDatasetElement(0, 2); +// creates a active element for data set at index 1 and for data at index 2 +ActiveDatasetElement active1 = new ActiveDatasetElement(1, 2); +// sets the elements +chart.setTooltipActiveElements(active0, active1); + +chart.update(); +``` + +For tooltip, you can also pass a point used to pass to the positioners. + +```java +// creates a active element for data set at index 0 and for data at index 2 +ActiveDatasetElement active0 = new ActiveDatasetElement(0, 2); +// creates a active element for data set at index 1 and for data at index 2 +ActiveDatasetElement active1 = new ActiveDatasetElement(1, 2); +// create a point +Point point = new Point(200, 200); +// sets the point and elements +chart.setTooltipActiveElements(point, active0, active1); + +chart.update(); +``` + +To reset the existing active elements, you can invoke as following: + +```java +// resets the elements +chart.resetActiveElements(); +// resets the tooltip's elements +chart.resetTooltipActiveElements(); + +chart.update(); +``` + +## Extended chart API + +For each chart, there are a set of methods which are available on all charts created with **Charba**. + +#### isInitialized() + +Provides `true` if [Chart.JS](http://www.chartjs.org/) chart instance has been initialized, otherwise `false`. + +#### getId() + +Returns the unique ID assigned to the chart which is set to DOM [DIV element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Div.html). This is NOT the same id property, used by [Chart.JS](http://www.chartjs.org/). + +#### getCanvas() + +Provides the DOM [CANVAS element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) instance used by [Chart.JS](http://www.chartjs.org/) to draw the chart. This is helpful when a plugin or controller is created to work directly on the canvas. + +#### getChartElement() + +Provides the the object's underlying DOM [DIV element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Div.html) used by **Charba** to wrap the chart. + +#### getNode() + +Provides an object which maps all [Chart.JS](http://www.chartjs.org/) internal objects used at runtime to draw and manage the chart. This is helpful when a plugin or controller is created to work directly on the canvas. The root object is mapped by [ChartNode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ChartNode.html) class. + +#### getBaseType() + +Provides the type which has been extended when a chart is a controller implementation. In case the chart is not a controller implementation, it will return the original type, if the controller is not extending any existing type, it will return `null`. + +#### getDefaultChartOptions() + +Provides the default options created based on chart type of the chart instance. + +#### getWholeOptions() + +Provides the default options by a chart instance, merging global, chart type global and chart options. + +## Chart life cycle + +It could be helpful to listen when the life-cycle of charts instances is changing, without activating a plugin to all charts, avoiding that someone can activate or deactivate the plugins, programmatically. + +For this reason, a life cycle listener interface has been implemented in order to be able to catch when a chart has been created and/or destroy, and when is configured. + +The interface [ChartsLifecycleListener](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ChartsLifecycleListener.html) is the following: + +```java +/** + * Called before initializing 'chart'. + * + * @param chart the chart instance. + */ +default void onBeforeInit(IsChart chart) { + // your logic +} + +/** + * Called after 'chart' has been initialized. + * + * @param chart the chart instance. + */ +default void onAfterInit(IsChart chart) { + // your logic +} + +/** + * Called before configuring 'chart'. + * + * @param chart the chart instance. + */ +default void onBeforeConfigure(IsChart chart) { + // your logic +} + +/** + * Called after 'chart' has been configured. + * + * @param chart the chart instance. + */ +default void onAfterConfigure(IsChart chart) { + // your logic +} + +/** + * Called before the chart has been destroyed. + * + * @param chart the chart instance. + */ +default void onBeforeDestroy(IsChart chart) { + // do nothing +} + +/** + * Called after the chart has been destroyed. + * + * @param chart the chart instance. + */ +default void onAfterDestroy(IsChart chart) { + // do nothing +} +``` + +To enable the life cycle listener, you must add the listener instance as following: + +```java +// creates a listener +ChartsLifecycleListener listener = new ChartsLifecycleListener(){ + + @Override + public void onBeforeConfigure(IsChart chart){ + // my logic + } + +}; +// Charts object contains all live charts instances +// adds new listener +Charts.addLifecycleListener(listener); +// removes existing listener +Charts.removeLifecycleListener(listener); +``` diff --git a/versioned_docs/version-6.5/charts/Area.md b/versioned_docs/version-6.5/charts/Area.md new file mode 100644 index 000000000..e4379388e --- /dev/null +++ b/versioned_docs/version-6.5/charts/Area.md @@ -0,0 +1,330 @@ +--- +id: ChartArea +title: Area chart +hide_title: true +sidebar_label: Area +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Area chart + +(quoted from [Area chart](https://en.wikipedia.org/wiki/Area_chart) definition in Wikipedia) + +A area chart displays graphically quantitative data. It is based on the area chart. The area between axis and area are commonly emphasized with colors, textures and hatchings. Commonly one compares two or more quantities with an area chart. + + + +Programmatically, you could use a area chart as following: + +```java +// creates the chart +AreaChart chart = new AreaChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a area chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The area chart allows to define the data and a number of properties, used to display the data, by a [area dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/AreaDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +AreaChart chart = new AreaChart(); +// creates the dataset +AreaDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +AreaDataset datasetNew = new AreaDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the area. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the area. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the area. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setAreaDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for area dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Area joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the area in pixels. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#scriptable) | Algorithm used to interpolate a smooth curve from the discrete data points. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active points of a dataset over the other points of the dataset. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the area, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the area, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the area, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setAreaDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for area dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Area joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/areaJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the area in pixels, when hovered. +| indexAxis | [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) | - | The base axis of the dataset. 'IndexAxis.X' for horizontal areas and 'IndexAxis.Y' for vertical areas. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| showArea | boolean | - | If `false`, the area is not drawn for this dataset. +| spanGaps | boolean - double | - | If `true`, areas will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the area. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| stepped | boolean - [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | [Yes](#scriptable) | If the area is shown as a stepped area. +| tension | double | - | Bezier curve tension of the area. Set to 0 to draw straight areas. This option is ignored if monotone cubic interpolation is used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a area dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active points of a dataset over the other points of the dataset. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all area datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all area datasets of all charts +defaultPoint.setRadius(6); +``` + +### Area styling + +The style of each area of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the area. +| borderCapStyle | Cap style of the area. +| borderColor | The color of the area. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for area dashes. +| borderJoinStyle | Area joint style +| borderWidth | The width of the area in pixels. +| cubicInterpolationMode | Algorithm used to interpolate a smooth curve from the discrete data points. +| stepped | If the area is shown as a stepped area. +| tension | Bezier curve tension of the area. + +All above options have got the fallback to the associated [Area](../configuration/Elements#area) elements, retrievable by the following statements: + +```java +// from chart instance +Area area = chart.getOptions().getElements().getArea(); +// sets options for all area datasets of the chart +area.setBorderWidth(6); +... +// from defaults +Area defaultArea = Defaults.get().getGlobal().getElements().getArea(); +// sets options for all area datasets of all charts +defaultArea.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all area datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all area datasets of all charts +defaultPoint.setRadius(6); +``` + +### Area interactions + +The interaction with each area can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the area, when hovered. +| hoverBorderCapStyle | Cap style of the area, when hovered. +| hoverBorderColor | The color of the area, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for area dashes, when hovered. +| hoverBorderJoinStyle | Area joint style, when hovered. +| hoverBorderWidth | The width of the area in pixels, when hovered. + +All above options have got the fallback to the associated [Area](../configuration/Elements#area) elements, retrievable by the following statements: + +```java +// from chart instance +Area area = chart.getOptions().getElements().getArea(); +// sets options for all area datasets of the chart +area.setBorderWidth(6); +... +// from defaults +Area defaultArea = Defaults.get().getGlobal().getElements().getArea(); +// sets options for all area datasets of all charts +defaultArea.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +AreaChart chart = new AreaChart(); +// creates dataset +AreaDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| stepped | [SteppedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SteppedCallback.html) | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) + +## Data structure + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When a area chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +## Options + +The area chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/AreaOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +AreaChart chart = new AreaChart(); +// gets the chart options +AreaOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setShowLine(false); +``` + +These are the options specific to area charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| showLine | boolean | `true` | If `false`, the lines between points are not drawn. +| spanGaps | boolean - double | `false` | If `true`, areas will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the area. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. diff --git a/versioned_docs/version-6.5/charts/Bar.md b/versioned_docs/version-6.5/charts/Bar.md new file mode 100644 index 000000000..d59f0a84b --- /dev/null +++ b/versioned_docs/version-6.5/charts/Bar.md @@ -0,0 +1,313 @@ +--- +id: ChartBar +title: Bar chart +hide_title: true +sidebar_label: Bar +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Bar chart + +(quoted from [Bar chart](https://en.wikipedia.org/wiki/Bar_chart) definition in Wikipedia) + +A bar chart is a chart that presents categorical data with rectangular bars with heights or lengths proportional to the values that they represent. The bars can be plotted vertically or horizontally. + +A bar chart shows comparisons among discrete categories. One axis of the chart shows the specific categories being compared, and the other axis represents a measured value. Some bar charts present bars clustered in groups of more than one, showing the values of more than one measured variable. + + + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +BarChart chart = new BarChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The bar chart allows to define the data and a number of properties, used to display the data, by a [bar dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +BarChart chart = new BarChart(); +// creates the dataset +BarDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +BarDataset datasetNew = new BarDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| autoInflateAmount | boolean | - | If `true`, the amount of pixels to inflate the bar rectangles, when drawing, is automatically calculating. +| base | double - double[] | [Yes](#scriptable) | Base value for the bar in data units along the value axis. +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) |The fill color/pattern of the bar. +| barPercentage | double | - | The percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| barThickness | int | - | The width of each bar in pixels. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The color of the bar border. +| borderSkipped | boolean - [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) | [Yes](#scriptable) | Which edge to skip drawing the border for. +| borderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels). +| borderWidth | int[] - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html)[] | [Yes](#scriptable) | The stroke width of the bar in pixels. +| categoryPercentage | double | - | The percent (0-1) of the available width each category should be within the sample width. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. When set to 0 means clip at chart area. +| enableBorderRadius | boolean | [Yes](#scriptable) | If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| grouped | boolean | - | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the bars when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the bars when hovered. +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the bars when hovered. +| hoverBorderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels) when hovered. +| indexAxis | [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) | - | The base axis of the dataset. 'IndexAxis.X' for vertical bars and 'IndexAxis.Y' for horizontal bars. +| inflateAmount | int[] | [Yes](#scriptable) | The amount of pixels to inflate the bar rectangles, when drawing. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| maxBarThickness | int | - | The maximum bar thickness, to ensure that bars are not sized thicker than this. +| minBarLength | int | - | Set this to ensure that bars have a minimum length in pixels. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | [Yes](#scriptable) | Point style for legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a bar dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Styling + +The style of each bar of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the bar. +| base | Base value for the bar in data units along the value axis. +| borderColor | The color of the bar border. +| borderSkipped | Which edge to skip drawing the border for. +| borderRadius | The bar border radius (in pixels). +| borderWidth | The stroke width of the bar in pixels. +| enableBorderRadius| If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| inflateAmount | This option can be used to inflate the rects that are used to draw the bars. This can be used to hide artifacts between bars when `(barPercentage * categoryPercentage)` is equals to 1. +| pointStyle | Point style for legend. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) element, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all bar datasets of the chart +bar.setBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all bar datasets of all charts +defaultBar.setBorderRadius(6); +``` + +### Interactions + +The interactions can change the styling of each bar of the dataset which can set by the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the bars when hovered. +| hoverBorderColor | The stroke color of the bars when hovered. +| hoverBorderRadius | The bar border radius (in pixels) when hovered. +| hoverBorderWidth | The stroke width of the bars when hovered. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) elements, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all bar datasets of the chart +bar.setHoverBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all bar datasets of all charts +defaultBar.setHoverBorderRadius(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +BarChart chart = new BarChart(); +// creates dataset +BarDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| base | [BaseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BaseCallback.html) | double +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderSkipped | [BorderSkippedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderSkippedCallback.html) | [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| enableBorderRadius | [EnableBorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/EnableBorderRadiusCallback.html) | boolean +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| hoverBorderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| inflateAmount | [InflateAmountCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/InflateAmountCallback.html) | int**(1)** +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +**(1)**To enable `autoInflateAmount` by the inflate amount callback, the value to return must be `Undefined.INTEGER`. + +### Configuration + +The bar chart accepts specific configuration not related to the styling or interactions which can be manage by the following options: + +| Name | Description +| :- | :- +| barPercentage | The percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| barThickness | The width of each bar in pixels. +| categoryPercentage | The percent (0-1) of the available width each category should be within the sample width. +| grouped | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| maxBarThickness | The maximum bar thickness, to ensure that bars are not sized thicker than this. +| minBarLength | Set this to ensure that bars have a minimum length in pixels. + +All above options have got the fallback to the associated [Datasets](../configuration/Datasets) elements which enables to define common values of the options for all bar datasets of the chart of globally, as following: + +```java +// from chart instance +Datasets datasets = chart.getOptions().getDatasets(); +// sets options for all bar datasets of the chart +datasets.setBarPercentage(0.7); +... +// from defaults +Datasets defaultDatasets = Defaults.get().getGlobal().getDatasets(); +// sets options for all bar datasets of all charts +defaultDatasets.setBarPercentage(0.7); +``` + +## Data structure + +The data of a dataset for a bar chart can be passed in two formats. + +#### Data as doubles + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When a bar chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +#### Data as DataPoint + +You can also specify the dataset when using the time series charts. Each data point is specified using an object containing `y` and `x` (as time type) properties for time series. + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setY(10); +dp1.setX(new Date()); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setY(30); +dp2.setX(new Date()); +// sets data by an array of datapoints +dataset.setDataPoint(dp1, dp2); +``` + +#### Floating bars + +You can also specify the dataset for a bar chart as list of floating bar data or by an array of arrays of doubles. This will force rendering of bars with the start and the end point of a bar respectively. + + + +```java +// sets in the constructor +FloatingData fd1 = new FloatingData(10, 30); +// sets by method to update values +FloatingData fd2 = new FloatingData(); +fd2.setValues(-10, 60) +// stores the data to dataset +dataset.setFloatingData(fd1, fd2); +``` + +## Options + +The bar chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/BarOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates the chart +BarChart chart = new BarChart(); +// gets the chart options +BarOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setSkipNull(true); +``` + +These are the options specific to bar charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| skipNull | boolean | `true` | If `true`, `NaN` values will not be drawn. diff --git a/versioned_docs/version-6.5/charts/Bubble.md b/versioned_docs/version-6.5/charts/Bubble.md new file mode 100644 index 000000000..e4167b96f --- /dev/null +++ b/versioned_docs/version-6.5/charts/Bubble.md @@ -0,0 +1,232 @@ +--- +id: ChartBubble +title: Bubble chart +hide_title: true +sidebar_label: Bubble +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Bubble chart + +(quoted from [Bubble chart](https://en.wikipedia.org/wiki/Bubble_chart) definition in Wikipedia) + +A bubble chart is a type of chart that displays three dimensions of data. Each entity with its triplet (x, y, r) of associated data is plotted as a disk that expresses two of the vi values through the disk's xy location and the third through its size. + +Bubble charts can be considered a variation of the scatter plot, in which the data points are replaced with bubbles. + +A bubble chart is used to display three dimensions of data at the same time. The location of the bubble is determined by the first two dimensions and the corresponding horizontal and vertical axes. The third dimension is represented by the size of the individual bubbles + + + + +Programmatically, you could use a bubble chart as following: + +```java +// creates the chart +BubbleChart chart = new BubbleChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bubble chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The bubble chart allows to define the data and a number of properties, used to display the data, by [bubble dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BubbleDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +BubbleChart chart = new BubbleChart(); +// creates the dataset +BubbleDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +BubbleDataset datasetNew = new BubbleDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The bubble background color. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The bubble border color. +| borderWidth | int[] | [Yes](#scriptable) | The bubble border width (in pixels). +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active bubbles of a dataset over the other bubbles of the dataset. +| hitRadius | double[] | [Yes](#scriptable) | The bubble additional radius for hit detection (in pixels). +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The bubble background color when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The bubble border color hovered. +| hoverBorderWidth | int[] | [Yes](#scriptable) | The bubble border width when hovered (in pixels) . +| hoverRadius | double[] | [Yes](#scriptable) | The bubble additional radius when hovered (in pixels). +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | The bubble shape style. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| radius | double[] | [Yes](#scriptable) | The bubble radius (in pixels). +| rotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. + +### General + +The general options for a bubble dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active bubbles of a dataset over the other bubbles of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +### Styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The bubble background color. +| borderColor | The bubble border color. +| borderWidth | The bubble border width (in pixels). +| hitRadius | The bubble additional radius for hit detection (in pixels). +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| pointStyle | The bubble shape style. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| radius | The bubble radius (in pixels). +| rotation | The rotation of the point in degrees. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The bubble background color when hovered. +| hoverBorderColor | The bubble border color when hovered. +| hoverBorderWidth | The bubble border width (in pixels) when hovered. +| hoverRadius | The bubble radius (in pixels) when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +BubbleChart chart = new BubbleChart(); +// creates dataset +BubbleDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| hitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| radius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double + +## Data structure + +Bubble chart datasets need to contain a data array of points, each point represented by an object containing `x`, `y` and `r`(radius) properties. + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setX(10); +dp1.setY(20); +// Bubble radius in pixels (not scaled). +dp1.setR(1); +// sets data by an array of datapoints +dataset.setDataPoint(dp1); +``` + +:::caution +**radius** options is not scaled by the chart, it is the raw radius in pixels of the bubble that is drawn. +::: + +## Options + +The bubble chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/BubbleOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +BubbleChart chart = new BubbleChart(); +// gets the chart options +BubbleOptions options = chart.getOptions(); +// sets option +options.setResponsive(true); +``` diff --git a/versioned_docs/version-6.5/charts/Charts.md b/versioned_docs/version-6.5/charts/Charts.md new file mode 100644 index 000000000..99408508c --- /dev/null +++ b/versioned_docs/version-6.5/charts/Charts.md @@ -0,0 +1,97 @@ +--- +id: Charts +title: Introduction +hide_title: true +sidebar_label: Introduction +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Charts + +Every **Charba** chart has got a common structure to define own configuration. + +There 3 main sections: + + 1. **Type** which represents the chart type. See [Type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Type.html) and [ChartType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ChartType.html) enumeration, with all available chart types out of the box. By controllers, you can create own charts and different types. + 2. **Data** which must be showed by the chart. See [Data](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html) and [the data section](#data) for details. + 3. **Options** which represents a set of options to configure the chart. See [Options](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/package-summary.html). + +## Usage + +A **Charba** chart extends always [AbstractChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/AbstractChart.html) which wraps a DOM [DIV element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Div.html) and implements [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) interface which is passed to callbacks, events handlers, plugins and all other customization items. + +Programmatically, you could use a chart as following: + +```java +... +// example for a line chart +LineChart chart = new LineChart(); +component.add(chart); +... +// example for Elemental2 +Element element = chart.getChartElement().as(); +DomGlobal.document.body.appendChild(element); +``` + +## Usage by widget (only GWT artifact) + +A **Charba** chart widget for GWT extends always [AbstractChartWidget](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gwt/widgets/AbstractChartWidget.html) which is a [GWT SimplePanel](http://www.gwtproject.org/javadoc/latest/com/google/gwt/user/client/ui/SimplePanel.html) and implements [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) interface which is passed to callbacks, events handlers, plugins and all other customization items. + +The charts can be implemented leveraging on [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) feature of GWT or also programmatically. + +Using as example a Line chart, here is an example how to include it in the a [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) file (be sure to have in the your classpath the `charba-[version.release]-gwt.jar` file): + +```xml + + + + .... + + ... + + +``` + +Into GWT component related to UIbinder definition, we could reference it as following: + +```java + ... + @UiField + LineChartWidget chart; + ... +``` + +In the java constructor of widget, you can set all options and datasets definitions needed for your project. + +Programmatically, you could implement a chart as following: + +```java + ... + LineChartWidget chart = new LineChartWidget(); + component.add(chart); + ... +``` + +## Data + +The [Data](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html) contains the [datasets](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Dataset.html) with data and configuration how data should be showed and the labels for each dataset and data. + +```java +// creates the chart +BarChart chart = new BarChart(); +// creates the dataset +BarDataset dataset = chart.newDataset(); +// sets labels of the data +chart.getData().setLabels("January", "February", "March", "April"); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Defaults | Description +| :- | :- | :- +| labels | String[] - [Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Labels.html) | The labels to display. +| datasets | [Dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Dataset.html)[] | The datasets of the chart. diff --git a/versioned_docs/version-6.5/charts/Doughnut.md b/versioned_docs/version-6.5/charts/Doughnut.md new file mode 100644 index 000000000..4a20c84d6 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Doughnut.md @@ -0,0 +1,254 @@ +--- +id: ChartDoughnut +title: Doughnut chart +hide_title: true +sidebar_label: Doughnut +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Doughnut chart + +(quoted from [Doughnut chart](https://en.wikipedia.org/wiki/Pie_chart#Doughnut_chart) definition in Wikipedia) + +A doughnut chart is a variant of the pie chart, with a blank center allowing for additional information about the data as a whole to be included. Doughnut charts are similar to pie charts in that their aim is to illustrate proportions. This type of circular graph can support multiple statistics at once and it provides a better data intensity ratio to standard pie charts. + +A doughnut charts are the same of pie charts and then divided in the segments, the arc of each segment shows the proportional value of each piece of data. + +They are excellent at showing the relational proportions between data. + + + +Programmatically, you could use a doughnut chart as following: + +```java +// creates the chart +DoughnutChart chart = new DoughnutChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a doughnut chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The doughnut chart allows to define the data and a number of properties, used to display the data, by a [doughnut dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/DoughnutDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +DoughnutChart chart = new DoughnutChart(); +// creates the dataset +DoughnutDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +DoughnutDataset datasetNew = new DoughnutDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs in the dataset. +| borderAlign | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) | [Yes](#scriptable) | The borders alignment of arcs. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color of the arcs in the dataset. +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderRadius | int[] - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html)[] | [Yes](#scriptable) | The arc border radius (in pixels). +| borderWidth | int[] | [Yes](#scriptable) | The border width of the arcs in the dataset. +| circumference | double | - | Sweep to allow arcs to cover.
For default value, see [doughnuts options](#options). +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the arcs when hovered. +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the arcs when hovered. +| hoverOffset | int | [Yes](#scriptable) | The offset of the arc (in pixels) when hovered. +| label | String | - | The label for the dataset. +| offset | int | [Yes](#scriptable) | The offset of the arc (in pixels). +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| rotation | double | - | Starting angle to draw arcs from.
For default value, see [doughnuts options](#options). +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| spacing | int | - | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. +| weight | double | - | The relative thickness of the dataset. Providing a value for weight will cause the doughnut dataset to be drawn with a thickness relative to the sum of all the dataset weight values. + +### General + +The general options for a doughnut dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| label | `null` | The label for the dataset. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +:::info +**label** options is just a pure label to add to the dataset and is **NOT** the label for the dataset which appears in the legend and tooltips. +::: + +### Styling + +The style of each arc of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the arcs in the dataset. +| borderAlign | The borders alignment of arcs. +| borderColor | The border color for arcs. +| borderJoinStyle | Arc line joint style +| borderRadius | The arc border radius (in pixels). +| borderWidth | The width of the arc border in pixels. +| offset | The offset of the arc (in pixels). +| spacing | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. +| weight | The relative thickness of the dataset. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setOffset(6); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setOffset(6); +``` + +### Interactions + +The interaction with each arc can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the arcs in the dataset when hovered. +| hoverBorderColor | The border color for arcs when hovered. +| hoverBorderJoinStyle | Arc line joint style when hovered. +| hoverBorderWidth | The width of the arc border in pixels when hovered. +| hoverOffset | The offset of the arc (in pixels) when hovered. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setOffset(6); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setOffset(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +DoughnutChart chart = new DoughnutChart(); +// creates dataset +DoughnutDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderAlign | [BorderAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderAlignCallback.html) | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverOffset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int +| offset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int + +## Data structure + +The data of a dataset for a doughnut chart is specified as a an array of numbers. Each point in the data array corresponds to the [label](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) at the same index. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +To provide context of what each point means, we include an array of strings that show around each point in the chart. + +```java +... +chart.getData().setLabels("label1", "label2"); +... +``` + +## Options + +The doughnut chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/DoughnutOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +DoughnutChart chart = new DoughnutChart(); +// gets the chart options +DoughnutOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setCircumference(180D); +``` + +These are the options specific to doughnut charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| circumference | double | 360 | Sweep to allow arcs to cover. +| cutoutPercentage | String | `50%` | The percentage of the chart that is cut out of the middle. It's a string, ending with '%', as percentage of the chart radius. +| cutout | double | `Undefined.DOUBLE` | The portion of the chart that is cut out of the middle, in pixels. +| radiusPercentage | String | `100%` | the outer radius of the chart. It's a string, ending with '%', as percentage of the maximum radius. +| radius | double | `Undefined.DOUBLE` | The outer radius of the chart, in pixels. +| rotation | double | 0 | Starting angle to draw arcs from. diff --git a/versioned_docs/version-6.5/charts/Gauge.md b/versioned_docs/version-6.5/charts/Gauge.md new file mode 100644 index 000000000..aa272e812 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Gauge.md @@ -0,0 +1,319 @@ +--- +id: ChartGauge +title: Gauge chart +hide_title: true +sidebar_label: Gauge +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Gauge chart + +A [gauge chart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/GaugeChart.html) is **Charba** extension of **[doughnut chart](ChartDoughnut)**, by a [controller](../Controllers) implementation. + +The gauge charts are divided in the segments, the arc of each segment shows the proportional value of data. + + + +Programmatically, you could use a gauge chart as following: + +```java +// creates the chart +GaugeChart chart = new GaugeChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a gauge chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The gauge chart allows a number of properties to be specified for the [gauge dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/GaugeDataset.html). + +```java +// creates the chart +GaugeChart chart = new GaugeChart(); +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the value +dataset.setValue(90.5D); +// sets thresholds +dataset.setThresholds(DefaultThreshold.NORMAL.getThreshold().setValue(40), + DefaultThreshold.WARNING.getThreshold().setValue(75), + DefaultThreshold.CRITICAL.getThreshold().setValue(100)); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +|:-|:-|:-|:- +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `color` option value | The border color of the arcs in the dataset. +| borderRadius | int - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html) | 0 | The arc border radius (in pixels). +| borderWidth | int | 0 | The border width of the arcs in the dataset. +| emptyColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | rgb(234,234,234) -          | The color to fill the segment of the chart which represents the empty part. +| max | double | 0 | The maximum value for the dataset. +| percentageThreshold | boolean | `true` | If `true`, it uses the percentage as threshold instead of the value. +| thresholds | [Threshold](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/Threshold.html)[] | [] | The thresholds to apply to the gauge dataset. + +:::caution +A gauge chart can have **ONLY** 1 dataset. +::: + +The dataset can be created instantiating the constructor, passing the maximum value of chart. The maximum value can be also changed at runtime. + +The default value of maximum value is **100**. + +```java +// sets max value +int maxValue = 200; +// creates the chart +GaugeChart chart = new GaugeChart(); +// creates the dataset with new max value +GaugeDataset dataset = chart.newDataset(maxValue); +// sets the value +dataset.setValue(90.5D); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +### Using thresholds + +The [thresholds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/Threshold.html)is the entity which defines the color of the dataset, based on the value of the threshold. + +A threshold is composed by 3 attributes: + + * **name**, mandatory attribute to apply the name, for instance `"warning"`. + * **value**, optional attribute to set the value, the default is `Double.MAX_VALUE`. + * **color**, optional attribute to set the color to use in the data set when the threshold is activated y the value of data set, the default is `rgb(140, 214, 16)` -         . + +The below example is configuring the chart in order to use + + * green color if the value of dataset is less or equals to 50, + * yellow color if the value of dataset is less or equals to 75 and greater than 50, + * red color if the value of dataset is greater than 75 (set to 100 because it's the maximum value of the data set). + +```java +Threshold myNorm = new Threshold("normal", 50, HtmlColor.GREEN); +Threshold myWarn = new Threshold("warning", 75, HtmlColor.YELLOW); +Threshold myCrit = new Threshold("critical", 100, HtmlColor.RED); +// creates the chart +GaugeChart chart = new GaugeChart(); +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the thresholds +dataset.setThresholds(myNorm, myWarn, myCrit); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +**Charba** provides a default threshold implementation by [gauge threshold](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/DefaultThreshold.html) enumeration. + +| Threshold instance| Name | Value | Color | +|:-|:-|:-|:- +| DefaultThreshold.NORMAL | "NORMAL" | `75` | rgb(140, 214, 16) -          +| DefaultThreshold.WARNING | "WARNING" | `90` | rgb(239, 198, 0) -          +| DefaultThreshold.CRITICAL | "CRITICAL" | `Double.MAX_VALUE` | rgb(231, 24, 49) -          + +You can reuse the [gauge threshold](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/DefaultThreshold.html) enumeration, changing color or value or both. + +```java +Threshold myNorm = DefaultThreshold.NORMAL.getThreshold().setValue(50).setColor(HtmlColor.GREEN); +Threshold myWarn = DefaultThreshold.WARNING.getThreshold().setValue(75).setColor(HtmlColor.YELLOW); +Threshold myCrit = DefaultThreshold.WARNING.getThreshold().setValue(100).setColor(HtmlColor.RED); +// creates the chart +GaugeChart chart = new GaugeChart(); +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the thresholds +dataset.setThresholds(myNorm, myWarn, myCrit); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +### Labels + +The gauge charts allow you to set labels inside the chart in order to improve the understanding of the chart for the user. + +There are 2 possible labels you can set in the chart: + + + +### Value label + +The value label allows you to show the value or percentage inside the chart. + +```java +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the percentage rendering +dataset.getValueLabel().setPercentage(true); +``` + +The value label element contains all options in order to configure the rendering. + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| animated | boolean | `false` | - |If the rendered label will be shown based on the animation of chart. +| autoFontSize | boolean | `true` | - | If `true`, the font size to applied to the rendered label is automatically calculated at runtime, otherwise uses the `size` property of the font. +| color | [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(128, 128, 128) -          | [Yes](#scriptable) | Color of the content. +| display | boolean | `true` | - | If `true`, the value label is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `null` | [Yes](#scriptable) | Font of rendered label. If `autoFontSize` is set to `true`, the `size` property is ignored because automatically calculated at runtime.

The default value is the font instance in the chart options.
See [Font](../defaults/DefaultsCharts#font). +| format | [MeterFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterFormatCallback.html) | `null` | [Yes](#scriptable) | The callback instance which format the value. +| percentage | boolean | `false` | - | If `true`, the rendered label will show the dataset value as a percentage. +| precision | int | `2` | - | The amount to decimals digits to apply to the value. + +### Description label + +The description label allows you to show a string as description inside the chart, below the [value label](#value-label). + +```java +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// enables rendering +dataset.getDescriptionLabel().setDisplay(true); +// enables rendering +dataset.getDescriptionLabel().setContent("RAM utilization"); + +``` + +The description label element contains all options in order to configure the rendering. + +:::caution +This label only apply if **display** options of **[value label](#value-label)** is **true**. +::: + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| autoFontSize | boolean | `true` | - | If `true`, the font size to applied to the rendered label is automatically calculated at runtime, otherwise uses the `size` property of the font. +| color | [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(128, 128, 128) -          | [Yes](#scriptable) | Color of the content. +| content | String | `null` | [Yes](#scriptable) | The content of description label. +| display | boolean | `false` | - | If `true`, the value label is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `null` | [Yes](#scriptable) | Font of rendered label. If `autoFontSize` is set to `true`, the `size` property is ignored because automatically calculated at runtime.

The default value is the font instance in the chart options.
See [Font](../defaults/DefaultsCharts#font). + +## Data structure + +The data of a dataset for a gauge chart is specified as single value. + +```java +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the value +dataset.setValue(90.5D); +``` + +:::caution +The `setData` methods are available, inherited by a doughnut dataset, but you can **NOT** use them otherwise an exception will throw.
Use `setValue` instead. +::: + +## Options + +The gauge chart defines the following configuration options. It extends the [meter options](ChartMeter#options). + +To set the options at chart level, you can get a typed object accordingly with the chart type. + +```java +// creates the chart +GaugeChart chart = new GaugeChart(); +// gets options +GaugeOptions options = chart.getOptions(); +// sets options +options.setRender(Render.PERCENTAGE); +options.setPrecision(3); +``` + +See **[doughnut chart](ChartDoughnut#options)** configuration how to configure the gauge chart, in addition of following options: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| cutoutPercentage | String | `"90%"` | It can be set with a value between `"80%"` and `"100%"`. +| cutout | double | Undefined.DOUBLE | It can be set with a value of pixels if the percentage is between `"80%"` and `"100%"`. +| circumference | double | `360` | Immutable property, always 360. +| rotation | double | `0` | Immutable property, always 0. + +:::info +The gauge chart disables the legend, tooltips and animation components. +::: + +## Scriptable + +Scriptable options in the configuration accept a callback which is called for each animation cycle. + +```java +// creates the chart +GaugeDataset dataset = chart.newDataset(); +// sets the color +dataset.getValueLabel().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(MeterContext context){ + // logic + return color; + } +}); +``` + +The callbacks are getting the only 1 argument, the [scriptable context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/MeterContext.html) which contains the context of the callback execution. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| datasetLabel | String | The label of the dataset. +| easing | double | The easing of drawing (between 0 and 1) for animation. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.METER`. +| value | double | The value of meter or gauge dataset. + +The gauge chart can provide scriptable options by the gauge data set and the labels. + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<MeterContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| content | [MeterContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterContentCallback.html) | String +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<MeterContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| format | [MeterFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterFormatCallback.html) | String + +Here is an example fo value formatting. + + + +```java +// creates the dataset +GaugeDataset dataset = chart.newDataset(); +// sets the formatter +dataset.getValueLabel().setFormatCallback(new MeterFormatCallback(){ + + @Override + public String invoke(MeterContext context){ + // logic + return Utilities.applyPrecision(context.getValue(), 0) + " logged users"; + } +}); +``` \ No newline at end of file diff --git a/versioned_docs/version-6.5/charts/HorizontalBar.md b/versioned_docs/version-6.5/charts/HorizontalBar.md new file mode 100644 index 000000000..4b439580b --- /dev/null +++ b/versioned_docs/version-6.5/charts/HorizontalBar.md @@ -0,0 +1,306 @@ +--- +id: ChartHorizontalBar +title: Horizontal bar chart +hide_title: true +sidebar_label: Horizontal bar +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Horizontal Bar chart + +A horizontal bar chart is a variation on a bar chart. It is sometimes used to show trend data, and the comparison of multiple data sets side by side. + + + +Programmatically, you could use an horizontal bar chart as following: + +```java +// creates the chart +HorizontalBarChart chart = new HorizontalBarChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use an horizontal bar chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The horizontal bar chart allows to define the data and a number of properties, used to display the data, by a [horizontal bar dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/HorizontalBarDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +HorizontalBarChart chart = new HorizontalBarChart(); +// creates the dataset +HorizontalBarDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +HorizontalBarDataset datasetNew = new HorizontalBarDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| autoInflateAmount | boolean | - | If `true`, the amount of pixels to inflate the bar rectangles, when drawing, is automatically calculating. +| base | double - double[] | [Yes](#scriptable) | Base value for the bar in data units along the value axis. +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) |The fill color/pattern of the bar. +| barPercentage | double | - | The percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| barThickness | int | - | The width of each bar in pixels. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The color of the bar border. +| borderSkipped | boolean - [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) | [Yes](#scriptable) | Which edge to skip drawing the border for. +| borderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels). +| borderWidth | int[] - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html)[] | [Yes](#scriptable) | The stroke width of the bar in pixels. +| categoryPercentage | double | - | The percent (0-1) of the available width each category should be within the sample width. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. When set to 0 means clip at chart area. +| enableBorderRadius| boolean | - | If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| grouped | boolean | - | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the bars when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the bars when hovered. +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the bars when hovered. +| hoverBorderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels) when hovered. +| inflateAmount | int[] | [Yes](#scriptable) | The amount of pixels to inflate the bar rectangles, when drawing. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| maxBarThickness | int | - | The maximum bar thickness, to ensure that bars are not sized thicker than this. +| minBarLength | int | - | Set this to ensure that bars have a minimum length in pixels. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | [Yes](#scriptable) | Point style for legend. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a horizontal bar dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Styling + +The style of each bar of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the bar. +| base | Base value for the bar in data units along the value axis. +| borderColor | The color of the bar border. +| borderSkipped | Which edge to skip drawing the border for. +| borderRadius | The bar border radius (in pixels). +| borderWidth | The stroke width of the bar in pixels. +| enableBorderRadius| If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| inflateAmount | This option can be used to inflate the rects that are used to draw the bars. This can be used to hide artifacts between bars when `(barPercentage * categoryPercentage)` is equals to 1. +| pointStyle | Point style for legend. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) elements, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all horizontal bar datasets of the chart +bar.setBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all horizontal bar datasets of all charts +defaultBar.setBorderRadius(6); +``` + +### Interactions + +The interactions can change the styling of each bar of the dataset which can set by the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the bars when hovered. +| hoverBorderColor | The stroke color of the bars when hovered. +| hoverBorderRadius | The bar border radius (in pixels) when hovered. +| hoverBorderWidth | The stroke width of the bars when hovered. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) elements, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all bar datasets of the chart +bar.setHoverBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all bar datasets of all charts +defaultBar.setHoverBorderRadius(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +HorizontalBarChart chart = new HorizontalBarChart(); +// creates dataset +HorizontalBarDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| base | [BaseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BaseCallback.html) | double +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderSkipped | [BorderSkippedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderSkippedCallback.html) | [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| hoverBorderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| inflateAmount | [InflateAmountCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/InflateAmountCallback.html) | int**(1)** +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +**(1)**To enable `autoInflateAmount` by the inflate amount callback, the value to return must be `Undefined.INTEGER`. + +### Configuration + +The horizontal bar chart accepts specific configuration not related to the styling or interactions which can be manage by the following options: + +| Name | Description +| :- | :- +| barPercentage | The percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| barThickness | The width of each bar in pixels. +| categoryPercentage | The percent (0-1) of the available width each category should be within the sample width. +| grouped | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| maxBarThickness | The maximum bar thickness, to ensure that bars are not sized thicker than this. +| minBarLength | Set this to ensure that bars have a minimum length in pixels. + +All above options have got the fallback to the associated [Datasets](../configuration/Datasets) elements which enables to define common values of the options for all horizontal bar datasets of the chart of globally, as following: + +```java +// from chart instance +Datasets datasets = chart.getOptions().getDatasets(); +// sets options for all bar datasets of the chart +datasets.setBarPercentage(0.7); +... +// from defaults +Datasets defaultDatasets = Defaults.get().getGlobal().getDatasets(); +// sets options for all bar datasets of all charts +defaultDatasets.setBarPercentage(0.7); +``` + +## Data structure + +The data of a dataset for an horizontal bar chart can be passed in two formats. + +#### Data as doubles + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When an horizontal bar chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +#### Data as DataPoint + +You can also specify the dataset when using the time series charts. Each data point is specified using an object containing `y` and `x` (as time type) properties for time series. + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setY(10); +dp1.setX(new Date()); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setY(30); +dp2.setX(new Date()); +// sets data by an array of datapoints +dataset.setDataPoint(dp1, dp2); +``` + +#### Floating bars + +You can also specify the dataset for a bar chart as list of floating bar data or by an array of arrays of doubles. This will force rendering of bars with the start and the end point of a bar respectively. + + + +```java +// sets in the constructor +FloatingData fd1 = new FloatingData(10, 30); +// sets by method to update values +FloatingData fd2 = new FloatingData(); +fd2.setValues(-10, 60) +// stores the data to dataset +dataset.setFloatingData(fd1, fd2); +``` + +## Options + +The horizontal bar chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/HorizontalBarOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates the chart +HorizontalBarChart chart = new HorizontalBarChart(); +// gets the chart options +HorizontalBarOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setSkipNull(true); +``` + +These are the options specific to horizontal bar charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| skipNull | boolean | `true` | If `true`, `NaN` values will not be drawn. diff --git a/versioned_docs/version-6.5/charts/Line.md b/versioned_docs/version-6.5/charts/Line.md new file mode 100644 index 000000000..e05f307d5 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Line.md @@ -0,0 +1,436 @@ +--- +id: ChartLine +title: Line chart +hide_title: true +sidebar_label: Line +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Line chart + +(quoted from [Line chart](https://en.wikipedia.org/wiki/Line_chart) definition in Wikipedia) + +A line chart is a type of chart which displays information as a series of data or data points connected by straight line segments. It is a basic type of chart common in many fields. The measurement points are ordered (typically by their x-axis value) and joined with straight line segments. A line chart is often used to visualize a trend in data over intervals of time, a time series, thus the line is often drawn chronologically. + + + +Programmatically, you could use a line chart as following: + +```java +// creates the chart +LineChart chart = new LineChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a line chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The line chart allows to define the data and a number of properties, used to display the data, by a [line dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/LineDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +LineChart chart = new LineChart(); +// creates the dataset +LineDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +LineDataset datasetNew = new LineDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#scriptable) | Algorithm used to interpolate a smooth curve from the discrete data points. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active points of a dataset over the other points of the dataset. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | [Yes](#scriptable) | How to fill the area under the line. See [Filling modes](../coloring/Colors#filling). +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| indexAxis | [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) | - | The base axis of the dataset. 'IndexAxis.X' for horizontal lines and 'IndexAxis.Y' for vertical lines. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| showLine | boolean | - | If `false`, the line is not drawn for this dataset. +| spanGaps | boolean - double | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| stepped | boolean - [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | [Yes](#scriptable) | If the line is shown as a stepped line. +| tension | double | - | Bezier curve tension of the line. Set to 0 to draw straight lines. This option is ignored if monotone cubic interpolation is used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a line dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active points of a dataset over the other points of the dataset. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style +| borderWidth | The width of the line in pixels. +| cubicInterpolationMode | Algorithm used to interpolate a smooth curve from the discrete data points. +| fill | How to fill the area under the line. +| stepped | If the line is shown as a stepped line. +| tension | Bezier curve tension of the line. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +LineChart chart = new LineChart(); +// creates dataset +LineDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FillCallback.html) | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| stepped | [SteppedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SteppedCallback.html) | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) + +## Data structure + +The data of a dataset for a line chart can be passed in three formats. + +#### Data as doubles + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When a line chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +#### Data as DataPoint + +This alternate is used for sparse datasets, such as those in scatter or time series charts. Each data point is specified using an object containing `x` and `y` properties (for scatter chart) or containing `y` and `t` (as time type) properties for time series. + + + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setX(10); +dp1.setY(20); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setX(30); +dp2.setY(40); +// sets data by an array of datapoints +dataset.setDataPoint(dp1, dp2); +``` + +#### Data as strings + +You can set data of charts as an array of strings. Each point in the data array corresponds to the label at the same index on the x axis. + + + +```java +... +dataset.setDataString("label1", "label2"); +.... +``` + +## Options + +The line chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/LineOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +LineChart chart = new LineChart(); +// gets the chart options +LineOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setShowLine(false); +``` + +These are the options specific to line charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| showLine | boolean | `true` | If `false`, the lines between points are not drawn. +| spanGaps | boolean - double | `false` | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. + +Setting `showLine` to `false`: + + + +### Segment + +The line charts can contain a segment options element which can manage the styles of data sets in each own segment between the points and can override the data set configuration by scriptable options. + +```java +// creates chart +LineChart chart = new LineChart(); +// sets segment callback for border color +chart.getOptions().getSegment().setBorderColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the border color will be "green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getY(); + double valuePoint1 = context.getEndPoint().getParsed().getY(); + return valuePoint0 < valuePoint1 ? HtmlColor.GRAY : HtmlColor.GREEN; + } +}); +// sets segment callback for background color +chart.getOptions().getSegment().setBackgroundColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the background color will be "light green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getY(); + double valuePoint1 = context.getEndPoint().getParsed().getY(); + return valuePoint0 < valuePoint1 ? HtmlColor.LIGHT_GRAY : HtmlColor.LIGHT_GREEN; + } +}); +``` + + + +Currently all of the border options and background color are supported. The segment styles are resolved for each section of the line between each point. + +These are the options specific to line charts: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<SegmentContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<SegmentContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<SegmentContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<SegmentContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<SegmentContext> | int + +The callbacks are getting the only 1 argument, the [segment context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SegmentContext.html) which contains the context of the callback execution. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| datasetIndex | int | The index of the dataset. +| endDataIndex | int | The index of second point in the data. +| endPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the end point of the segment. +| startDataIndex | int | The index of first point in the data. +| startPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the start point of the segment. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.SEGMENT`. diff --git a/versioned_docs/version-6.5/charts/Matrix.md b/versioned_docs/version-6.5/charts/Matrix.md new file mode 100644 index 000000000..e73dd02de --- /dev/null +++ b/versioned_docs/version-6.5/charts/Matrix.md @@ -0,0 +1,217 @@ +--- +id: ChartMatrix +title: Matrix chart +hide_title: true +sidebar_label: Matrix +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Matrix chart + +(quoted from [Matrix chart](https://en.wikipedia.org/wiki/Heat_map) definition in Wikipedia) + +A matrix chart is a data visualization technique that shows magnitude of a phenomenon as color in two dimensions. The variation in color may be by hue or intensity, giving obvious visual cues to the reader about how the phenomenon is clustered or varies over space. + +Matrix originated in 2D displays of the values in a data matrix. Larger values were represented by darker colored squares and smaller values by lighter colored squares. + + + +
+
+ +**Charba** provides out of the box the feature to enable matrix chart, leveraging on [Chart.js Matrix](https://github.com/kurkle/chartjs-chart-matrix). + +The [Chart.js Matrix](https://github.com/kurkle/chartjs-chart-matrix) is *native javascript* implementation and **Charba** provides the wrapper in order to be able to use it. + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +MatrixChart chart = new MatrixChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +### Controller registration + +The controller registration is performed when a first MATRIX chart has been instantiated. When there is a use case where some defaults options must be set before the first instantiation, you need to register the controller before changing the default options. + +```java +// registers the controller +MatrixChart.register(); +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default matrix element options +MatrixElementOptions defaultOptions = gOptions.getElements().getElement(MatrixElementOptions.FACTORY); +// sets default value +defaultOptions.setBorderColor(HtmlColor.RED); +``` + +## Dataset + +The matrix chart allows to define the data and a number of properties, used to display the data, by a [matrix dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/MatrixDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +MatrixChart chart = new MatrixChart(); +// creates the dataset +MatrixDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +MatrixDataset datasetNew = new MatrixDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | [Yes](#scriptable) | The fill color/pattern of the matrix element. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | [Yes](#scriptable) | The color of the matrix element border. +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 0 | [Yes](#scriptable) | The border radius (in pixels) of matrix element. +| borderWidth | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) | 0 | [Yes](#scriptable) | The stroke width of the matrix element in pixels. +| height | double | 20 | [Yes](#scriptable) | The height of matrix element. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | [Yes](#scriptable) | The fill color/pattern of the matrix elements when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | [Yes](#scriptable) | The stroke color of the matrix elements when hovered. +| hoverBorderWidth | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) | 0 | [Yes](#scriptable) | The stroke width of the matrix elements when hovered. +| width | double | 20 | [Yes](#scriptable) | The width of matrix element. +| xAnchor | [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/enums/Anchor.html) | Anchor.CENTER | - | Set the horizontal anchor value of the matrix elements.
For this property, only Anchor.LEFT, Anchor.RIGHT and Anchor.CENTER are valid. +| yAnchor | [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/enums/Anchor.html) | Anchor.CENTER | - | Set the vertical anchor value of the matrix elements.
For this property, only Anchor.TOP, Anchor.BOTTOM and Anchor.CENTER are valid. + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +MatrixChart chart = new MatrixChart(); +// creates dataset +MatrixDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| height | [SizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/callbacks/SizeCallback.html) | double +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| width | [SizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/callbacks/SizeCallback.html) | double + +## Data structure + +The data of a dataset for a matrix chart can be passed in [matrix data points](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/MatrixDataPoint.html). + +:::caution +The `setData` method is available but you can **NOT** use them otherwise an exception will throw.
Use `setDataPoints` instead. +::: + +#### Data as objects + +Matrix data should be provided by a list of objects. The [matrix data point](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/MatrixDataPoint.html) needs to have `x` and `y` values to bind to the axes to set, and `value` which represents the value of the matrix element. + + + +
+
+ +```java +// creates chart +MatrixChart chart = new MatrixChart(); +// creates dataset +MatrixDataset dataset = chart.newDataset(); +// creates a list of data points +List points = new LinkedList<>(); +// creates the start and end dates +Date end = adapter.startOf(new Date(), TimeUnit.DAY); +Date start = adapter.add(end, -365, TimeUnit.DAY); +// for each day, it creates a data point +while (start.getTime() <= end.getTime()) { + // x is the date in ISO format, y is the week of the day, and then the value + MatrixDataPoint point = new MatrixDataPoint(adapter.format(start, "yyyy-MM-dd") + , adapter.format(start, "EEE") + , getRandomDigit(0, 100)); + // adds to the list + points.add(point); + // increments the date of 1 day + start = adapter.add(start, 1, TimeUnit.DAY); +} +// stores datapoints to dataset +dataset.setDataPoints(points); +``` + +## Options + +The matrix chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/matrix/MatrixOptions.html) to be configured. + +```java +// creates chart +MatrixChart chart = new MatrixChart(); +// gets the chart options +MatrixOptions options = chart.getOptions(); +// gets matrix element options +MatrixElementOptions matrixOptions = options.getElements().getElement(MatrixElementOptions.FACTORY); +// sets value +matrixOptions.setBorderColor(HtmlColor.RED); + +// ------------------------ +// DEFAULTS +// ------------------------ +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default matrix element options +MatrixElementOptions defaultOptions = gOptions.getElements().getElement(MatrixElementOptions.FACTORY); +// sets default value +defaultOptions.setBorderColor(HtmlColor.RED); +``` + +:::info +The matrix chart disables the [LABELS](../extensions/Labels) plugin. +::: + +## Scales + +The matrix chart can use cartesian [time](../axes/CartesianTimeAxes), [linear](../axes/CartesianLinearAxes) or [category](../axes/CartesianCategoryAxes) axes. diff --git a/versioned_docs/version-6.5/charts/Meter.md b/versioned_docs/version-6.5/charts/Meter.md new file mode 100644 index 000000000..795da0209 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Meter.md @@ -0,0 +1,260 @@ +--- +id: ChartMeter +title: Meter chart +hide_title: true +sidebar_label: Meter +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Meter chart + +A [meter chart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/MeterChart.html) is **Charba** extension of **[doughnut chart](ChartDoughnut)**, by a [controller](../Controllers) implementation. + +The meter charts are divided in the 2 segments, the arc of each segment shows the proportional value of data. + + + +Programmatically, you could use a meter chart as following: + +```java +// creates the chart +MeterChart chart = new MeterChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a meter chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The meter chart allows a number of properties to be specified for the [meter dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/MeterDataset.html). + +```java +// creates the chart +MeterChart chart = new MeterChart(); +// creates the dataset +MeterDataset dataset = chart.newDataset(); +// sets the value +dataset.setValue(90.5D); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `color` option value | The border color of the arcs in the dataset. +| borderRadius | int - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html) | 0 | The arc border radius (in pixels). +| borderWidth | int | 0 | The border width of the arcs in the dataset. +| color | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | rgb(140,214,16) -          | The color to fill the segment of the chart which represents the value. +| emptyColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | rgb(234,234,234) -          | The color to fill the segment of the chart which represents the empty part. +| max | double | 0 | The maximum value for the dataset. + +:::caution +A meter chart can have **ONLY** 1 dataset.
+::: + +The dataset can be created instantiating the constructor, passing the maximum value of chart. The maximum value can be also changed at runtime. + +The default value of maximum value is **100**. + +```java +// sets max value +int maxValue = 200; +// creates the chart +MeterChart chart = new MeterChart(); +// creates the dataset with new max value +MeterDataset dataset = chart.newDataset(maxValue); +// sets the value +dataset.setValue(90.5D); +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +### Labels + +The meter charts allow you to set labels inside the chart in order to improve the understanding of the chart for the user. + +There are 2 possible labels you can set in the chart: + + + +### Value label + +The value label allows you to show the value or percentage inside the chart. + +```java +// creates the dataset +MeterDataset dataset = chart.newDataset(); +// sets the percentage rendering +dataset.getValueLabel().setPercentage(true); +``` + +The value label element contains all options in order to configure the rendering. + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| animated | boolean | `false` | - |If the rendered label will be shown based on the animation of chart. +| autoFontSize | boolean | `true` | - | If `true`, the font size to applied to the rendered label is automatically calculated at runtime, otherwise uses the `size` property of the font. +| color | [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(128, 128, 128) -          | [Yes](#scriptable) | Color of the content. +| display | boolean | `true` | - | If `true`, the value label is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `null` | [Yes](#scriptable) | Font of rendered label. If `autoFontSize` is set to `true`, the `size` property is ignored because automatically calculated at runtime.

The default value is the font instance in the chart options.
See [Font](../defaults/DefaultsCharts#font). +| format | [MeterFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterFormatCallback.html) | `null` | [Yes](#scriptable) | The callback instance which format the value. +| percentage | boolean | `false` | - | If `true`, the rendered label will show the dataset value as a percentage. +| precision | int | `2` | - | The amount to decimals digits to apply to the value. + +### Description label + +The description label allows you to show a string as description inside the chart, below the [value label](#value-label). + +```java +// creates the dataset +MeterDataset dataset = chart.newDataset(); +// enables rendering +dataset.getDescriptionLabel().setDisplay(true); +// enables rendering +dataset.getDescriptionLabel().setContent("RAM utilization"); + +``` + +The description label element contains all options in order to configure the rendering. + +:::caution +This label only apply if **display** options of **[value label](#value-label)** is **true**. +::: + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| autoFontSize | boolean | `true` | - | If `true`, the font size to applied to the rendered label is automatically calculated at runtime, otherwise uses the `size` property of the font. +| color | [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(128, 128, 128) -          | [Yes](#scriptable) | Color of the content. +| content | String | `null` | [Yes](#scriptable) | The content of description label. +| display | boolean | `false` | - | If `true`, the value label is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `null` | [Yes](#scriptable) | Font of rendered label. If `autoFontSize` is set to `true`, the `size` property is ignored because automatically calculated at runtime.

The default value is the font instance in the chart options.
See [Font](../defaults/DefaultsCharts#font). + +## Data structure + +The data of a dataset for a meter chart is specified as single value. + +```java +// creates the dataset +MeterDataset dataset = chart.newDataset(); +// sets the value +dataset.setValue(90.5D); +``` + +:::caution +The `setData` methods are available, inherited by a doughnut dataset, but you can **NOT** use them otherwise an exception will throw.
Use `setValue` instead. +::: + +## Options + +The meter chart defines the following configuration options. It extends the [doughnut options](ChartDoughnut). + +To set the options at chart level, you can get a typed object accordingly with the chart type. + +```java +// creates the chart +MeterChart chart = new MeterChart(); +// gets options +MeterOptions options = chart.getOptions(); +// sets options +options.setRender(Render.PERCENTAGE); +options.setPrecision(3); +``` + +See **[doughnut chart](ChartDoughnut#options)** configuration how to configure the meter chart, in addition of following options: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| cutoutPercentage | String | `"90%"` | It can be set with a value between `"80%"` and `"100%"`. +| cutout | double | Undefined.DOUBLE | It can be set with a value of pixels if the percentage is between `"80%"` and `"100%"`. +| circumference | double | `360` | Immutable property, always 360. +| rotation | double | `0` | Immutable property, always 0. + +:::info +The meter chart disables the legend, tooltips and animation components. +::: + +## Scriptable + +Scriptable options in the configuration accept a callback which is called for each animation cycle. + +```java +// creates the chart +MeterDataset dataset = chart.newDataset(); +// sets the color +dataset.getValueLabel().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(MeterContext context){ + // logic + return color; + } +}); +``` + +The callbacks are getting the only 1 argument, the [scriptable context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/impl/charts/MeterContext.html) which contains the context of the callback execution. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| datasetLabel | String | The label of the dataset. +| easing | double | The easing of drawing (between 0 and 1) for animation. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.METER`. +| value | double | The value of meter or gauge dataset. + +The meter chart can provide scriptable options by the meter data set and the labels. + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<MeterContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| content | [MeterContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterContentCallback.html) | String +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<MeterContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| format | [MeterFormatCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/MeterFormatCallback.html) | String + +Here is an example fo value formatting. + + + +```java +// creates the dataset +MeterDataset dataset = chart.newDataset(); +// sets the formatter +dataset.getValueLabel().setFormatCallback(new MeterFormatCallback(){ + + @Override + public String invoke(MeterContext context){ + // logic + return Utilities.applyPrecision(context.getValue(), 0) + " logged users"; + } +}); +``` \ No newline at end of file diff --git a/versioned_docs/version-6.5/charts/Pie.md b/versioned_docs/version-6.5/charts/Pie.md new file mode 100644 index 000000000..a684212c9 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Pie.md @@ -0,0 +1,254 @@ +--- +id: ChartPie +title: Pie chart +hide_title: true +sidebar_label: Pie +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Pie chart + +(quoted from [Pie chart](https://en.wikipedia.org/wiki/Pie_chart) definition in Wikipedia) + +A pie chart is a circular statistical graphic, which is divided in the slices to illustrate numerical proportion. In a pie chart, the arc length of each slice (and consequently its central angle and area), is proportional to the quantity it represents. + +A pie charts are divided in the segments, the arc of each segment shows the proportional value of each piece of data. + +They are excellent at showing the relational proportions between data. + + + +Programmatically, you could use a pie chart as following: + +```java +// creates the chart +PieChart chart = new PieChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a pie chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The pie chart allows to define the data and a number of properties, used to display the data, by a [pie dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/PieDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +PieChart chart = new PieChart(); +// creates the dataset +PieDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +PieDataset datasetNew = new PieDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs in the dataset. +| borderAlign | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) | [Yes](#scriptable) | The borders alignment of arcs. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color of the arcs in the dataset. +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderRadius | int[] - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html)[] | [Yes](#scriptable) | The arc border radius (in pixels). +| borderWidth | int[] | [Yes](#scriptable) | The border width of the arcs in the dataset. +| circumference | double | - | Sweep to allow arcs to cover.
For default value, see [pie options](#options). +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the arcs when hovered. +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the arcs when hovered. +| hoverOffset | int | [Yes](#scriptable) | The offset of the arc (in pixels) when hovered. +| label | String | - | The label for the dataset. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| offset | int | [Yes](#scriptable) | The offset of the arc (in pixels). +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| rotation | double | - | Starting angle to draw arcs from.
For default value, see [pie options](#options). +| spacing | int | - | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. +| weight | double | - | The relative thickness of the dataset. Providing a value for weight will cause the pie dataset to be drawn with a thickness relative to the sum of all the dataset weight values. + +### General + +The general options for a pie dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| label | `null` | The label for the dataset. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +:::info +**label** options is just a pure label to add to the dataset and is **NOT** the label for the dataset which appears in the legend and tooltips. +::: + +### Styling + +The style of each arc of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the arcs in the dataset. +| borderAlign | The borders alignment of arcs. +| borderColor | The border color for arcs. +| borderJoinStyle | Arc line joint style +| borderRadius | The arc border radius (in pixels). +| borderWidth | The width of the arc border in pixels. +| offset | The offset of the arc (in pixels). +| spacing | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. +| weight | The relative thickness of the dataset. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setOffset(6); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setOffset(6); +``` + +### Interactions + +The interaction with each arc can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the arcs in the dataset when hovered. +| hoverBorderColor | The border color for arcs when hovered. +| hoverBorderJoinStyle | Arc line joint style when hovered. +| hoverBorderWidth | The width of the arc border in pixels when hovered. +| hoverOffset | The offset of the arc (in pixels) when hovered. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setOffset(6); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setOffset(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +PieChart chart = new PieChart(); +// creates dataset +PieDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderAlign | [BorderAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderAlignCallback.html) | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [ArcBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ArcBorderRadius.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverOffset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int +| offset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int + +## Data structure + +The data of a dataset for a pie chart is specified as a an array of numbers. Each point in the data array corresponds to the [label](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) at the same index. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +To provide context of what each point means, we include an array of strings that show around each point in the chart. + +```java +... +chart.getData().setLabels("label1", "label2"); +... +``` + +## Options + +The pie chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/PieOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +PieChart chart = new PieChart(); +// gets the chart options +PieOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setCircumference(180D); +``` + +These are the options specific to pie charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| circumference | double | 360 | Sweep to allow arcs to cover. +| cutoutPercentage | String | `null` | The percentage of the chart that is cut out of the middle. It's a string, ending with '%', as percentage of the chart radius. +| cutout | double | 0 | The portion of the chart that is cut out of the middle, in pixels. +| radiusPercentage | String | `100%` | the outer radius of the chart. It's a string, ending with '%', as percentage of the maximum radius. +| radius | double | Undefined.DOUBLE | The outer radius of the chart, in pixels. +| rotation | double | 0 | Starting angle to draw arcs from. diff --git a/versioned_docs/version-6.5/charts/PolarArea.md b/versioned_docs/version-6.5/charts/PolarArea.md new file mode 100644 index 000000000..184fa0718 --- /dev/null +++ b/versioned_docs/version-6.5/charts/PolarArea.md @@ -0,0 +1,216 @@ +--- +id: ChartPolarArea +title: PolarArea chart +hide_title: true +sidebar_label: PolarArea +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## PolarArea chart + +(quoted from [Polar area chart](https://en.wikipedia.org/wiki/Pie_chart#Polar_area_diagram) definition in Wikipedia) + +The polar area chart is similar to a usual pie chart, except sectors have equal angles and differ rather in how far each sector extends from the center of the circle. The polar area chart is used to plot cyclic phenomena. + +Polar area charts are similar to pie charts, but each segment has the same angle - the radius of the segment differs depending on the value. + +This type of chart is often useful when we want to show a comparison data similar to a pie chart, but also show a scale of values for context. + + + +Programmatically, you could use a polar area chart as following: + +```java +// creates the chart +PolarAreaChart chart = new PolarAreaChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a polar area chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The polar area chart allows to define the data and a number of properties, used to display the data, by [polar area dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/PolarAreaDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +PolarAreaChart chart = new PolarAreaChart(); +// creates the dataset +PolarAreaDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +PolarAreaDataset datasetNew = new PolarAreaDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs in the dataset. +| borderAlign | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) | [Yes](#scriptable) | The borders alignment of arcs. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color of the arcs in the dataset. +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int[] | [Yes](#scriptable) | The border width of the arcs in the dataset. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| circular | boolean | [Yes](#scriptable) | If the arc is curved. If `false` the arc will be flat. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the arcs when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the arcs when hovered. +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html)[] | [Yes](#scriptable) | Arc line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the arcs when hovered. +| label | String | - | The label for the dataset. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +### General + +The general options for a polar area dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| label | `null` | The label for the dataset. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +:::info +**label** options is just a pure label to add to the dataset and is **NOT** the label for the dataset which appears in the legend and tooltips. +::: + +### Styling + +The style of each arc of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the arcs in the dataset. +| borderAlign | The borders alignment of arcs. +| borderColor | The border color for arcs. +| borderJoinStyle | Arc line joint style +| borderWidth | The width of the arc border in pixels. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setBorderWidth(3); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setBorderWidth(3); +``` + +### Interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the arcs in the dataset when hovered. +| hoverBorderColor | The border color for arcs when hovered. +| hoverBorderJoinStyle | Arc line joint style when hovered. +| hoverBorderWidth | The width of the arc border in pixels when hovered. + +All above options have got the fallback to the associated [Arc](../configuration/Elements#arc) elements, retrievable by the following statements: + +```java +// from chart instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets options for all pie datasets of the chart +arc.setBorderWidth(3); +... +// from defaults +Arc defaultArc = Defaults.get().getGlobal().getElements().getArc(); +// sets options for all pie datasets of all charts +defaultArc.setBorderWidth(3); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates the chart +PolarAreaChart chart = new PolarAreaChart(); +// creates the dataset +PolarAreaDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderAlign | [BorderAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderAlignCallback.html) | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| circular | [CircularCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CircularCallback.html) | boolean +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int + +## Data structure + +The data of a dataset for a polar area chart is specified as a an array of numbers. Each point in the data array corresponds to the [label](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) at the same index on the axis. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +To provide context of what each point means, we include an array of strings that show around each point in the chart. + +```java +... +chart.getData().setLabels("label1", "label2"); +... +``` diff --git a/versioned_docs/version-6.5/charts/Radar.md b/versioned_docs/version-6.5/charts/Radar.md new file mode 100644 index 000000000..8c7b8c6ef --- /dev/null +++ b/versioned_docs/version-6.5/charts/Radar.md @@ -0,0 +1,331 @@ +--- +id: ChartRadar +title: Radar chart +hide_title: true +sidebar_label: Radar +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Radar chart + +(quoted from [Radar chart](https://en.wikipedia.org/wiki/Radar_chart) definition in Wikipedia) + +A radar chart is a graphical method of displaying multivariate data in the form of a two-dimensional chart of three or more quantitative variables represented on axes starting from the same point. The relative position and angle of the axes is typically uninformative. It is equivalent to a parallel coordinates plot, with the axes arranged radially. + +They are often useful for comparing the points of two or more different data sets. + + + + +Programmatically, you could use a radar chart as following: + +```java +// creates the chart +RadarChart chart = new RadarChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a radar chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The radar chart allows to define the data and a number of properties, used to display the data, by a [radar dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/RadarDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +RadarChart chart = new RadarChart(); +// creates the dataset +RadarDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +RadarDataset datasetNew = new RadarDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)| [Yes](#scriptable) | The fill color under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active points of a dataset over the other points of the dataset. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | [Yes](#scriptable) | How to fill the area under the line. See [Filling modes](../coloring/Colors#filling-modes). +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | the rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| spanGaps | boolean | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. +| tension | double | - | Bezier curve tension of the line. Set to 0 to draw straight lines. + +### General + +The general options for a line dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active points of a dataset over the other points of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltip. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style. +| borderWidth | The width of the line in pixels. +| fill | How to fill the area under the line. +| tension | Bezier curve tension of the line. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +RadarChart chart = new RadarChart(); +// creates dataset +RadarDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FillCallback.html) | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +The data of a dataset for a radar chart is specified as a an array of numbers. Each point in the data array corresponds to the [label](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) at the same index on the x axis. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +To provide context of what each point means, we include an array of strings that show around each point in the chart. + +```java +... +chart.getData().setLabels("label1", "label2"); +... +``` + +## Options + +The radar chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/RadarOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +RadarChart chart = new RadarChart(); +// gets the chart options +RadarOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setSpanGaps(true); +``` + +These are the options specific to radar charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| spanGaps | boolean | `false` | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. + \ No newline at end of file diff --git a/versioned_docs/version-6.5/charts/Sankey.md b/versioned_docs/version-6.5/charts/Sankey.md new file mode 100644 index 000000000..b37a841e9 --- /dev/null +++ b/versioned_docs/version-6.5/charts/Sankey.md @@ -0,0 +1,213 @@ +--- +id: ChartSankey +title: Sankey chart +hide_title: true +sidebar_label: Sankey +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Sankey chart + +(quoted from [Sankey chart](https://en.wikipedia.org/wiki/Sankey_diagram) definition in Wikipedia) + +Sankey charts are a type of flow diagram in which the width of the arrows is proportional to the flow rate. + +The illustration shows a sankey chart that represents all the primary energy that flows into a factory. The widths of the bands are linearly proportional to energy production, utilization and loss. The primary energy inputs enter the left side of the diagram, and are differentiated into gas, electricity and coal/oil. + +Sankey diagrams can also visualize the energy accounts, material flow accounts on a regional or national level, and cost breakdowns, and emphasize the major transfers or flows within a system. They help locate the most important contributions to a flow. They often show conserved quantities within defined system boundaries. + + + +
+
+ +**Charba** provides out of the box the feature to enable sankey chart, leveraging on [Chart.js Sankey](https://github.com/kurkle/chartjs-chart-sankey). + +The [Chart.js Sankey](https://github.com/kurkle/chartjs-chart-sankey) is *native javascript* implementation and **Charba** provides the wrapper in order to be able to use it. + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +SankeyChart chart = new SankeyChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +### Controller registration + +The controller registration is performed when a first SANKEY chart has been instantiated. When there is a use case where some defaults options must be set before the first instantiation, you need to register the controller before changing the default options. + +```java +// registers the controller +SankeyChart.register(); +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default sankey element options +SankeyElementOptions defaultOptions = gOptions.getElements().getElement(SankeyElementOptions.FACTORY); +// sets default value +defaultOptions.setColorMode(ColorMode.GRADIENT); +``` + +## Dataset + +The sankey chart allows to define the data and a number of properties, used to display the data, by a [sankey dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/SankeyDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +SankeyChart chart = new SankeyChart(); +// creates the dataset +SankeyDataset dataset = chart.newDataset(); +// sets the option +dataset.setColorMode(ColorMode.GRADIENT); +... +// creates the dataset +SankeyDataset datasetNew = new SankeyDataset(); +// sets the option +datasetNew.setColorMode(ColorMode.GRADIENT); +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.BLACK -          | - | The color of the node border. +| borderWidth | int | 1 | - | The stroke width of the sankey nodes in pixels. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.BLACK -          | - | The color of the node label. +| colorFrom | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | empty list | [Yes](#scriptable) | The starting color of the flow between nodes. +| colorMode | [ColorMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/enums/ColorMode.html) | ColorMode.GRADIENT | [Yes](#scriptable) | How the flow is drawn on the chart. +| colorTo | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | empty list | [Yes](#scriptable) | The ending color of the flow between nodes. +| column | [Column](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/Column.html) | `null` | - | Is a map to apply a specific position, by column number, to the nodes, affecting the chart layout. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `Defaults.get().getGlobal()`
`.getFont()` | [Yes](#scriptable) | Font of text of node label.
See [Font](../defaults/DefaultsCharts#font). +| hoverColorFrom | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | empty list | [Yes](#scriptable) | The starting color of the flow between nodes, when hovered. +| hoverColorTo | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | empty list | [Yes](#scriptable) | The ending color of the flow between nodes, when hovered. +| labels | [Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/Labels.html) | `null` | - | Is a map to apply a different label to the nodes. +| nodeWidth | int | 10 | - | The width of node. +| padding | double | `font.getLineheight() / 2` | [Yes](#scriptable) | The padding of the node label from the top. +| priority | [Priority](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/Priority.html) | `null` | - | Is a map to apply a different priority to the nodes, affecting the chart layout. +| size | [Size](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/enums/Size.html) | Size.MAX | [Yes](#scriptable) | Sets Size.MIN if flow overlap is preferred. + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +SankeyChart chart = new SankeyChart(); +// creates dataset +SankeyDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setColorFrom(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| colorFrom | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| colorMode | [ColorModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/callbacks/ColorModeCallback.html) | [ColorMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/enums/ColorMode.html) +| colorTo | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<DatasetContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| hoverColorFrom | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| hoverColorTo | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/callbacks/PaddingCallback.html) | double +| size | [SizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/callbacks/SizeCallback.html) | [Size](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/enums/Size.html) + +## Data structure + +The data of a dataset for a sankey chart can be passed in [sankey data points](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/SankeyDataPoint.html). + +:::caution +The `setData` method is available but you can **NOT** use them otherwise an exception will throw.
Use `setDataPoints` instead. +::: + +#### Data as objects + +Sankey data should be provided by a list of objects. The [sankey data point](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/SankeyDataPoint.html) contains the relations between nodes and their value. + +It needs to have `from` and `to` values, which represent the nodes, and `value` which represents the value of the sankey element. + + + +
+
+ +```java +// creates chart +SankeyChart chart = new SankeyChart(); +// creates dataset +SankeyDataset dataset = chart.newDataset(); +// creates a list of data points +List datapoints = dataset1.getDataPoints(true); +datapoints.add(new SankeyDataPoint("a", "b", 20)); +datapoints.add(new SankeyDataPoint("c", "d", 10)); +datapoints.add(new SankeyDataPoint("c", "e", 5)); +// stores datapoints to dataset +dataset.setDataPoints(datapoints); +``` + +## Options + +The sankey chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/sankey/SankeyOptions.html) to be configured. + +```java +// creates chart +SankeyChart chart = new SankeyChart(); +// gets the chart options +SankeyOptions options = chart.getOptions(); +// gets sankey element options +SankeyElementOptions sankeyOptions = options.getElements().getElement(SankeyElementOptions.FACTORY); +// sets value +sankeyOptions.setColorMode(ColorMode.GRADIENT); + +// ------------------------ +// DEFAULTS +// ------------------------ +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default sankey element options +SankeyElementOptions defaultOptions = gOptions.getElements().getElement(SankeyElementOptions.FACTORY); +// sets default value +defaultOptions.setColorMode(ColorMode.GRADIENT); +``` + +:::info +The sankey chart disables the [DATALABELS](../extensions/DataLabels), [LABELS](../extensions/Labels), [ANNOTATION](../extensions/Annotation), [HTML legend](../plugins/PluginHTMLLegend), [color schemes](../plugins/PluginColorSchemes) and [dataset items selector](../plugins/PluginDatasetsItemsSelector) plugins. +::: + +## Scales + +The sankey chart can use cartesian [linear](../axes/CartesianLinearAxes) axes and they are not showed. diff --git a/versioned_docs/version-6.5/charts/Scatter.md b/versioned_docs/version-6.5/charts/Scatter.md new file mode 100644 index 000000000..9af2ac3df --- /dev/null +++ b/versioned_docs/version-6.5/charts/Scatter.md @@ -0,0 +1,314 @@ +--- +id: ChartScatter +title: Scatter chart +hide_title: true +sidebar_label: Scatter +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Scatter chart + +(quoted from [Scatter chart](https://en.wikipedia.org/wiki/Scatter_plot) definition in Wikipedia) + +A scatter chart is a type of plot or mathematical diagram using Cartesian coordinates to display values for typically two variables for a set of data. If the points are color-coded, one additional variable can be displayed. The data are displayed as a collection of points, each having the value of one variable determining the position on the horizontal axis and the value of the other variable determining the position on the vertical axis. + +Scatter charts are based on basic line charts with the x axis changed to a linear axis. To use a scatter chart, data must be passed as objects containing X and Y properties. + + + +Programmatically, you could use a scatter chart as following: + +```java +// creates the chart +ScatterChart chart = new ScatterChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a scatter chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The scatter chart allows to define the data and a number of properties, used to display the data, by a [scatter dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/ScatterDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +ScatterChart chart = new ScatterChart(); +// creates the dataset +ScatterDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +ScatterDataset datasetNew = new ScatterDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active points of a dataset over the other points of the dataset. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| spanGaps | boolean - double | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a scatter dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active points of a dataset over the other points of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style +| borderWidth | The width of the line in pixels. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +ScatterChart chart = new ScatterChart(); +// creates dataset +ScatterDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +Unlike the line chart where data can be supplied in two different formats, the scatter chart only accepts data in a point format. Each data point is specified using an object containing `x` and `y` properties. + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setX(10); +dp1.setY(20); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setX(30); +dp2.setY(40); +// sets data by an array of datapoints +dataset.setDataPoint(dp1, dp2); +``` + +## Options + +The scatter chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/ScatterOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +ScatterChart chart = new BubbleChart(); +// gets the chart options +ScatterOptions options = chart.getOptions(); +// sets option +options.setResponsive(true); +``` \ No newline at end of file diff --git a/versioned_docs/version-6.5/charts/StackedArea.md b/versioned_docs/version-6.5/charts/StackedArea.md new file mode 100644 index 000000000..525a74bad --- /dev/null +++ b/versioned_docs/version-6.5/charts/StackedArea.md @@ -0,0 +1,319 @@ +--- +id: ChartStackedArea +title: Stacked area chart +hide_title: true +sidebar_label: Stacked area +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Stacked Area chart + +A stacked area chart is a way of plotting data points on a filled line. Often, it is used to show trend data, or the comparison of two data sets. + + + + +Programmatically, you could use a stacked area chart as following: + +```java +// creates the chart +StackedAreaChart chart = new StackedAreaChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a stacked area chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The stacked area chart allows a number of properties to be specified for each [stacked area dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/StackedAreaDataset.html). These are used to set display properties for a specific dataset. + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +StackedAreaChart chart = new StackedAreaChart(); +// creates the dataset +StackedAreaDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +StackedAreaDataset datasetNew = new StackedAreaDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#scriptable) | Algorithm used to interpolate a smooth curve from the discrete data points. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| indexAxis | [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) | - | The base axis of the dataset. 'IndexAxis.X' for horizontal lines and 'IndexAxis.Y' for vertical lines. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| showLine | boolean | - | If `false`, the line is not drawn for this dataset. +| spanGaps | boolean - double | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| stepped | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | - | If the line is shown as a stepped line. +| tension | double | - | Bezier curve tension of the line. Set to 0 to draw straight lines. This option is ignored if monotone cubic interpolation is used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a stacked area dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style +| borderWidth | The width of the line in pixels. +| cubicInterpolationMode | Algorithm used to interpolate a smooth curve from the discrete data points. +| stepped | If the line is shown as a stepped line. +| tension | Bezier curve tension of the line. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +StackedAreaChart chart = new StackedAreaChart(); +// creates dataset +StackedAreaDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +The data of a dataset for a stacked area chart are passed by an array or list of doubles and the x axis is generally a category. When a stacked area chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +## Options + +The stacked area chart specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/StackedLineOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +StackedAreaChart chart = new StackedAreaChart(); +// gets the chart options +StackedLineOptions options = chart.getOptions(); +// sets option +options.setResponsive(true); +``` + + \ No newline at end of file diff --git a/versioned_docs/version-6.5/charts/StackedBar.md b/versioned_docs/version-6.5/charts/StackedBar.md new file mode 100644 index 000000000..50fd69934 --- /dev/null +++ b/versioned_docs/version-6.5/charts/StackedBar.md @@ -0,0 +1,333 @@ +--- +id: ChartStackedBar +title: Stacked bar chart +hide_title: true +sidebar_label: Stacked bar +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Stacked Bar chart + +Stacked bar charts can be configured like bar charts and changes the settings on the X and Y axes to enable stacking. Stacked bar charts can be used to show how one data series is made up of a number of smaller pieces. + + + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +StackedBarChart chart = new StackedBarChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The stacked bar chart allows a number of properties to be specified for each [stacked bar dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/StackedBarDataset.html). These are used to set display properties for a specific dataset. + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +StackedBarChart chart = new StackedBarChart(); +// creates the dataset +StackedBarDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +StackedBarDataset datasetNew = new StackedBarDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| base | double - double[] | [Yes](#scriptable) | Base value for the bar in data units along the value axis. +| backgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) |The fill color/pattern of the bar. +| barPercentage | double | - | The percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| barThickness | int | - | The width of each bar in pixels. +| borderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The color of the bar border. +| borderSkipped | boolean - [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) | [Yes](#scriptable) | Which edge to skip drawing the border for. +| borderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels). +| borderWidth | int[] - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html)[] | [Yes](#scriptable) | The stroke width of the bar in pixels. +| categoryPercentage | double | - | The percent (0-1) of the available width each category should be within the sample width. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. When set to 0 means clip at chart area. +| enableBorderRadius| boolean | - | If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| grouped | boolean | - | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| hoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color/pattern of the bars when hovered. +| hoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The stroke color of the bars when hovered. +| hoverBorderWidth | int[] | [Yes](#scriptable) | The stroke width of the bars when hovered. +| hoverBorderRadius | int[] - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html)[] | [Yes](#scriptable) | The bar border radius (in pixels) when hovered. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| maxBarThickness | int | - | The maximum bar thickness, to ensure that bars are not sized thicker than this. +| minBarLength | int | - | Set this to ensure that bars have a minimum length in pixels. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | [Yes](#scriptable) | Point style for legend. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a stacked bar dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltips, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Styling + +The style of each bar of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color of the bar. +| base | Base value for the bar in data units along the value axis. +| borderColor | The color of the bar border. +| borderSkipped | Which edge to skip drawing the border for. +| borderRadius | The bar border radius (in pixels). +| borderWidth | The stroke width of the bar in pixels. +| enableBorderRadius| If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| pointStyle | Point style for legend. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) element, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all bar datasets of the chart +bar.setBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all bar datasets of all charts +defaultBar.setBorderRadius(6); +``` + +### Interactions + +The interactions can change the styling of each bar of the dataset which can set by the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color of the bars when hovered. +| hoverBorderColor | The stroke color of the bars when hovered. +| hoverBorderRadius | The bar border radius (in pixels) when hovered. +| hoverBorderWidth | The stroke width of the bars when hovered. + +All above options have got the fallback to the associated [Bar](../configuration/Elements#bar) elements, retrievable by the following statements: + +```java +// from chart instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets options for all bar datasets of the chart +bar.setHoverBorderRadius(6); +... +// from defaults +Bar defaultBar = Defaults.get().getGlobal().getElements().getBar(); +// sets options for all bar datasets of all charts +defaultBar.setHoverBorderRadius(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +BarChart chart = new BarChart(); +// creates dataset +BarDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| base | [BaseCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BaseCallback.html) | double +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderSkipped | [BorderSkippedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderSkippedCallback.html) | [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [BarBorderWidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BarBorderWidthCallback.html) | int - [BarBorderWidth](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderWidth.html) +| hoverBorderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When a stacked bar chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +### Floating bars + +You can also specify the dataset for a bar chart as list of floating bar data or by an array of arrays of doubles. This will force rendering of bars with the start and the end point of a bar respectively. + + + +```java +... +// set in the constructor +FloatingData fd1 = new FloatingData(10, 30); +// set by method to update values +FloatingData fd2 = new FloatingData(); +fd2.setValues(-10, 60) +// stores the data to dataset +dataset.setFloatingData(fd1, fd2); +``` + +## Options + +The stacked bar chart specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/StackedBarOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +To set the options at chart level, you can get a typed object accordingly with the chart type. + +```java +// creates the chart +StackedBarChart chart = new StackedBarChart(); +// gets the chart options +StackedBarOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +``` + +## Axes + +The chart is creating the default axes out-of-the-box, setting them as `scaled`. It defines a [category axis](../axes/CartesianCategoryAxes) for index, and a [linear axis](../axes/CartesianLinearAxes) for values. + +You can anyway override them setting your axes. + +To access to predefined axes as following: + +```java +// gets category axis +CartesianCategoryAxis axis1 = (CartesianCategoryAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.X); +// sets axis options +axis1.setDisplay(true); +axis1.getTitle().setDisplay(true); +axis1.getTitle().setText("Index"); +// gets linear axis +CartesianLinearAxis axis2 = (CartesianLinearAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.Y); +// sets axis options +axis2.setDisplay(true); +axis2.getTitle().setDisplay(true); +axis2.getTitle().setText("Value"); +``` + +## Horizontal bar + +A stacked horizontal bar chart enables to have stacked data represented by horizontal bars. + +Programmatically, you could use a stacked horizontal bar chart as following: + +```java +// creates the chart +StackedHorizontalBarChart chart = new StackedHorizontalBarChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a line chart as following: + +```xml + + + + .... + + ... + + +``` + +The stacked horizontal bar allows a number of properties to be specified for each [stacked horizontal bar dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/StackedHorizontalBarDataset.html). These are used to set display properties for a specific dataset. + +The properties are the same of the [stacked bar dataset](#dataset). + +### Axes + +The chart is creating the default axes out-of-the-box, setting them as `scaled`. It defines a [category axis](../axes/CartesianCategoryAxes) for index, and a [linear axis](../axes/CartesianLinearAxes) for values. + +You can anyway override them setting your axes. + +To access to predefined axes as following: + +```java +// gets category axis as Y +CartesianCategoryAxis axis1 = (CartesianCategoryAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.Y); +// sets axis options +axis1.setDisplay(true); +axis1.getTitle().setDisplay(true); +axis1.getTitle().setText("Index"); +// gets linear axis as X +CartesianLinearAxis axis2 = (CartesianLinearAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.X); +// sets axis options +axis2.setDisplay(true); +axis2.getTitle().setDisplay(true); +axis2.getTitle().setText("Value"); +``` diff --git a/versioned_docs/version-6.5/charts/StackedLine.md b/versioned_docs/version-6.5/charts/StackedLine.md new file mode 100644 index 000000000..9103850fa --- /dev/null +++ b/versioned_docs/version-6.5/charts/StackedLine.md @@ -0,0 +1,403 @@ +--- +id: ChartStackedLine +title: Stacked line chart +hide_title: true +sidebar_label: Stacked line +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Stacked Line chart + +A stacked line chart is a way of plotting data points on a line. Often, it is used to show trend data, or the comparison of two data sets. + + + + +Programmatically, you could use a stacked line chart as following: + +```java +// creates the chart +StackedLineChart chart = new StackedLineChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a line chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The stacked line chart allows a number of properties to be specified for each [stacked line dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/StackedLineDataset.html). These are used to set display properties for a specific dataset. + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +StackedLineChart chart = new StackedLineChart(); +// creates the dataset +StackedLineDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +StackedLineDataset datasetNew = new StackedLineDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#scriptable) | Algorithm used to interpolate a smooth curve from the discrete data points. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | [Yes](#scriptable) | How to fill the area under the line. See [Filling modes](../coloring/Colors#filling). +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| showLine | boolean | - | If `false`, the line is not drawn for this dataset. +| spanGaps | boolean - double | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| stepped | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | - | If the line is shown as a stepped line. +| tension | double | - | Bezier curve tension of the line. Set to 0 to draw straight lines. This option is ignored if monotone cubic interpolation is used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a line dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| indexAxis | IndexAxis.X | The base axis of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style +| borderWidth | The width of the line in pixels. +| cubicInterpolationMode | Algorithm used to interpolate a smooth curve from the discrete data points. +| fill | How to fill the area under the line. +| stepped | If the line is shown as a stepped line. +| tension | Bezier curve tension of the line. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +StackedLineChart chart = new StackedLineChart(); +// creates dataset +StackedLineDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FillCallback.html) | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +The data of a dataset for a stacked line chart are passed by an array or list of doubles and the x axis is generally a category. When a stacked line chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +## Options + +The stacked line chart specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/StackedLineOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +StackedLineChart chart = new StackedLineChart(); +// gets the chart options +StackedLineOptions options = chart.getOptions(); +// sets option +options.setResponsive(true); +``` + +## Axes + +The chart is creating the default axes out-of-the-box, setting them as `scaled`. It defines a [category axis](../axes/CartesianCategoryAxes) for index, and a [linear axis](../axes/CartesianLinearAxes) for values. + +You can anyway override them setting your axes. + +To access to predefined axes as following: + +```java +// gets category axis +CartesianCategoryAxis axis1 = (CartesianCategoryAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.X); +// sets axis options +axis1.setDisplay(true); +axis1.getTitle().setDisplay(true); +axis1.getTitle().setText("Index"); +// gets linear axis +CartesianLinearAxis axis2 = (CartesianLinearAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.Y); +// sets axis options +axis2.setDisplay(true); +axis2.getTitle().setDisplay(true); +axis2.getTitle().setText("Value"); +``` + +## Vertical line + +A stacked vertical line chart enables to have stacked data represented by vertical lines. + +Programmatically, you could use a stacked vertical line chart as following: + +```java +// creates the chart +StackedVerticalLineChart chart = new StackedVerticalLineChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a line chart as following: + +```xml + + + + .... + + ... + + +``` + +The stacked vertical line chart allows a number of properties to be specified for each [stacked vertical line dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/StackedVerticalLineDataset.html). These are used to set display properties for a specific dataset. + +The properties are the same of the [stacked line dataset](#dataset). + +### Axes + +The chart is creating the default axes out-of-the-box, setting them as `scaled`. It defines a [category axis](../axes/CartesianCategoryAxes) for index, and a [linear axis](../axes/CartesianLinearAxes) for values. + +You can anyway override them setting your axes. + +To access to predefined axes as following: + +```java +// gets category axis as Y +CartesianCategoryAxis axis1 = (CartesianCategoryAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.Y); +// sets axis options +axis1.setDisplay(true); +axis1.getTitle().setDisplay(true); +axis1.getTitle().setText("Index"); +// gets linear axis as X +CartesianLinearAxis axis2 = (CartesianLinearAxis) chart.getOptions().getScales().getAxisById(DefaultScaleId.X); +// sets axis options +axis2.setDisplay(true); +axis2.getTitle().setDisplay(true); +axis2.getTitle().setText("Value"); +``` diff --git a/versioned_docs/version-6.5/charts/TimeSeries.md b/versioned_docs/version-6.5/charts/TimeSeries.md new file mode 100644 index 000000000..67837c93f --- /dev/null +++ b/versioned_docs/version-6.5/charts/TimeSeries.md @@ -0,0 +1,199 @@ +--- +id: ChartTimeSeries +title: Time series chart +hide_title: true +sidebar_label: Time series +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Time series charts + +A time series chart is a data visualization tool that illustrates data points at successive intervals of time. Each point on the chart corresponds to both a time and a quantity that is being measured. + +Time series charts present a series of data points collected over a specified reporting period. The x-axis plots time and the y-axis plots data points. + + + +**Charba** provides 2 time series charts which are extending the [line](ChartLine) and [bar](ChartBar) charts implementation. These time series charts help the developer providing some methods and axes implementations. + +A time series chart have already defined the axes to use ([time series cartesian axis](../axes/CartesianTimeSeriesAxes) for X axes and [linear cartesian axis](../axes/CartesianLinearAxes) for Y axis). The developer can access to the instances and just configure them without creating any axis instance. + +## Dataset + +The time series charts allow a number of properties to be specified for each time series [line](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/TimeSeriesLineDataset.html) or [bar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/TimeSeriesBarDataset.html) datasets which are implementing the same properties of line and bar ones. + +See **[line dataset](ChartLine#dataset)** or **[bar dataset](ChartBar#dataset)** configuration how to configure the time series dataset, because no additional options are defined. + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// for GWT +// TimeSeriesLineChartWidget chart = new TimeSeriesLineChartWidget(); +// creates a dataset +TimeSeriesLineDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... // adds data and dataset configuration +// adds dataset to chart +chart.getData().setDatasets(dataset); +``` + +## Data structure + +The data of a dataset for a time series chart can be passed in two formats. + +#### Data as doubles or as strings + +Even if the methods to load data by these methods are not hidden, you can NOT use them to load data in a time series chart (not allowed and an exception will throw). See how to load data by [time series items](#data-as-timeseriesitems) or [data points](#data-as-datapoints). + +#### Data as TimeSeriesItems + +A [time series item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/TimeSeriesItem.html) is a wrapper to the data points in order to simplify how to set data in a time series chart. + +The chart instance will sort automatically the time series items by date in ascending mode (as required). + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// for GWT +// TimeSeriesLineChartWidget chart = new TimeSeriesLineChartWidget(); +// creates a dataset +TimeSeriesLineDataset dataset = chart.newDataset(); +// creates an empty list to contain the items +List data = new LinkedList<>(); +// creates time series items and add to the list +data.add(new TimeSeriesItem(new Date(time1), number_value1)); +data1.add(new TimeSeriesItem(new Date(time2), number_value2)); +// sets the time series items as data to the dataset +dataset.setTimeSeriesData(data); +// adds dataset to chart +chart.getData().setDatasets(dataset); +``` + + +#### Data as DataPoints + +Each data point is specified using an object containing `y` and `x` (as time type) properties for time series. + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// for GWT +// TimeSeriesLineChartWidget chart = new TimeSeriesLineChartWidget(); +// creates a dataset +TimeSeriesLineDataset dataset = chart.newDataset(); +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setY(number_value1); +dp1.setX(new Date(time1)); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setY(number_value1); +dp2.setX(new Date(time2)); +// sets the data points as data to the dataset +dataset.setDataPoints(dp1, dp2); +// adds dataset to chart +chart.getData().setDatasets(dataset); +``` + +## Options + +The time series chart defines specific options implementation of [line](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/TimeSeriesLineOptions.html) or [bar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/TimeSeriesBarOptions.html) to be configured. + +See **[line chart](ChartLine#options)** or **[bar chart](ChartBar#options)** options how to configure the time series chart, because no additional options are defined. + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// for GWT +// TimeSeriesLineChartWidget chart = new TimeSeriesLineChartWidget(); +// gets options +TimeSeriesLineOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +``` + + + +The time series options have already defined the out-of-the-box axes ([time series cartesian axis](../axes/CartesianTimeSeriesAxes) for X axes and [linear cartesian axis](../axes/CartesianLinearAxes) for Y axis) to use. The developer can access to the instances and just configure them without creating any axis instance. + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// gets time series cartesian axis +CartesianTimeSeriesAxis timeseriesAxis = chart.getOptions().getScales().getTimeAxis(); +// sets options +timeseriesAxis.getTime().setUnit(TimeUnit.DAY); +// gets linear cartesian axis +CartesianLinearAxis linearAxis = chart.getOptions().getScales().getLinearAxis(); +// sets options +linearAxis.setBeginAtZero(true); +``` + +### Segment + +The time series line charts can contain a segment options element which can manage the styles of data sets in each own segment between the points and can override the data set configuration by scriptable options. + +```java +// creates a line time series chart +TimeSeriesLineChart chart = new TimeSeriesLineChart(); +// sets segment callback for border color +chart.getOptions().getSegment().setBorderColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the border color will be "green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getY(); + double valuePoint1 = context.getEndPoint().getParsed().getY(); + return valuePoint0 < valuePoint1 ? HtmlColor.GRAY : HtmlColor.GREEN; + } +}); +// sets segment callback for background color +chart.getOptions().getSegment().setBackgroundColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the background color will be "light green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getY(); + double valuePoint1 = context.getEndPoint().getParsed().getY(); + return valuePoint0 < valuePoint1 ? HtmlColor.LIGHT_GRAY : HtmlColor.LIGHT_GREEN; + } +}); +``` + +Below an example how you have a time series line chart where each week is colored with different color: + + + +Currently all of the border options and background color are supported. The segment styles are resolved for each section of the time series line between each point. + +These are the options specific to line charts: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<SegmentContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<SegmentContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<SegmentContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<SegmentContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<SegmentContext> | int + +The callbacks are getting the only 1 argument, the [segment context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SegmentContext.html) which contains the context of the callback execution. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| datasetIndex | int | The index of the dataset. +| endDataIndex | int | The index of second point in the data. +| endPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the end point of the segment. +| startDataIndex | int | The index of first point in the data. +| startPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the start point of the segment. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.SEGMENT`. diff --git a/versioned_docs/version-6.5/charts/TreeMap.md b/versioned_docs/version-6.5/charts/TreeMap.md new file mode 100644 index 000000000..4d08ec1e9 --- /dev/null +++ b/versioned_docs/version-6.5/charts/TreeMap.md @@ -0,0 +1,468 @@ +--- +id: ChartTreeMap +title: TreeMap chart +hide_title: true +sidebar_label: TreeMap +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## TreeMap chart + +(quoted from [Treemap chart](https://en.wikipedia.org/wiki/Treemapping) definition in Wikipedia) + +In information visualization and computing, treemapping is a method for displaying hierarchical data using nested figures, usually rectangles. + +Treemaps display hierarchical (tree-structured) data as a set of nested rectangles. Each branch of the tree is given a rectangle, which is then tiled with smaller rectangles representing sub-branches. A leaf node's rectangle has an area proportional to a specified dimension of the data. Often the leaf nodes are colored to show a separate dimension of the data. + +When the color and size dimensions are correlated in some way with the tree structure, one can often easily see patterns that would be difficult to spot in other ways, such as whether a certain color is particularly relevant. A second advantage of treemaps is that, by construction, they make efficient use of space. As a result, they can legibly display thousands of items on the screen simultaneously. + + + +
+
+ +**Charba** provides out of the box the feature to enable treemap chart, leveraging on [Chart.js Treemap](https://github.com/kurkle/chartjs-chart-treemap). + +The [Chart.js Treemap](https://github.com/kurkle/chartjs-chart-treemap) is *native javascript* implementation and **Charba** provides the wrapper in order to be able to use it. + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +TreeMapChart chart = new TreeMapChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +### Controller registration + +The controller registration is performed when a first TREEMP chart has been instantiated. When there is a use case where some defaults options must be set before the first instantiation, you need to register the controller before changing the default options. + +```java +// registers the controller +TreeMapChart.register(); +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default matrix element options +TreeMapElementOptions defaultOptions = gOptions.getElements().getElement(TreeMapElementOptions.FACTORY); +// sets default value +defaultOptions.setBorderColor(HtmlColor.RED); +``` + +## Dataset + +The treemap chart allows to define the data and a number of properties, used to display the data, by a [treemap dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/TreeMapDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +TreeMapChart chart = new TreeMapChart(); +// creates the dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +... +// creates the dataset +TreeMapDataset datasetNew = new TreeMapDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | [Yes](#scriptable) |The fill color/pattern of the treemap element. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | [Yes](#scriptable) | The color of the treemap element border. +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 0 | [Yes](#scriptable) | The radius of the rectangle of treemap element (in pixels). +| borderWidth | int | 0 | - | The stroke width of the treemap element in pixels. +| groups | String[] - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html)[] | | - | Set the properties names of the tree object to group by the data. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | [Yes](#scriptable) | The fill color/pattern of the treemap elements when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | [Yes](#scriptable) | The stroke color of the treemap elements when hovered. +| hoverBorderWidth | int | 0 | - | The stroke width of the treemap elements when hovered. +| key | String - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html) | `null` | - | Set the property name of the tree object to use to get the value of the data. +| rtl | boolean | `false` | - | Set `true` for rendering the treemap elements from right to left. +| spacing | double | 0.5 | - | Fixed distance between all treemap elements. +| sumKeys | String[] - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html)[] | | - | Set the properties names of the tree object to define multiple keys to add additional sums, on top of the `key` one. +| treeLeafKey | String - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html) | `"_leaf"` | - | The name of the key where the object key of leaf node of tree object is stored. Used only when tree is an object, as hierarchical data. + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<DatasetContext> | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) + +### Labels + +The labels options can control if and how a label, to represent the data, can be shown in the rectangle. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// gets labels +Labels labels = dataset.getLabels(); +// labels must be enabled +labels.setDisplay(true); +// sets font and color of labels +labels.setColor(HtmlColor.WHITE); +labels.getFont().setFamily("Tahoma"); +labels.getFont().setSize(10); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| align | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Align.html) | Align.LEFT | [Yes](#label-options-scriptable) | Specifies the text horizontal alignment used when drawing the label. +| [color](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | HtmlColor.TRANSPARENT | [Yes](#label-options-scriptable) | Color of label.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | `false` | - | If `true`, the labels will be applied to the elements. +| [font](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | `Defaults.get().getGlobal()`
`.getFont()` | [Yes](#label-options-scriptable) | Font of text of label.
See [Font](../defaults/DefaultsCharts#font). +| formatter | [FormatterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/FormatterCallback.html) | `null` | [Yes](#label-formatter) | Scriptable options to enable custom formatting for the label text to show. +| [hoverColor](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | HtmlColor.TRANSPARENT` | [Yes](#label-options-scriptable) | Color of label, when hovered.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| [hoverFont](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | `Defaults.get().getGlobal()`
`.getFont()` | [Yes](#label-options-scriptable) | Font of text of label, when hovered.
See [Font](../defaults/DefaultsCharts#font). +| overflow | [Overflow](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Overflow.html) | Overflow.CUT | [Yes](#label-options-scriptable) | The overflow property controls what happens to a label that is too big to fit into a rectangle. +| padding | int | 3 | - | Specifies the space, in pixels, to apply around labels. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Position.html) | Position.MIDDLE | [Yes](#label-options-scriptable) | Specifies the text vertical alignment used when drawing the label. + +#### Fonts and colors + +When the label to draw has multiple lines, you can use different font and color for each row of the label. This is enabled configuring an array or list of fonts or colors for those options. When the lines are more than the configured fonts of colors, the last configuration of those options is used for all remaining lines. + +#### Label options scriptable + +Scriptable options at labels level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the labels option by a callback +dataset.getLabels().setColor(new ColorsCallback(){ + + @Override + public List invoke(DatasetContext context){ + // logic + return colors; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| align | [AlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/AlignCallback.html) | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Align.html) +| color | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html))<DatasetContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| font | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<DatasetContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| hoverColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html))<DatasetContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| hoverFont | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<DatasetContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| overflow | [OverflowCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/OverflowCallback.html) | [Overflow](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Overflow.html) +| position | [PositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/PositionCallback.html) | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Position.html) + +#### Label Formatter + +Data values are converted to string. If values are grouped, the value of the group and the value (as string) are shown. + +This default behavior can be overridden by the `formatter` which is a [FormatterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/FormatterCallback.html). + +A `formatter` can return a string (for a single line) or a list of strings (for multiple lines, where each item represents a new line). + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the labels formatter +dataset.getLabels().setFormatter(new FormatterCallback(){ + + @Override + public List invoke(DatasetContext context){ + // logic + return myLabelText; + } +}); +``` + +### Captions + +The captions options can control if and how a captions, to represent the group of the chart, can be shown in the rectangle. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// gets captions +Captions captions = dataset.getCaptions(); +// sets font and color of captions +captions.setColor(HtmlColor.WHITE); +captions.getFont().setFamily("Tahoma"); +captions.getFont().setSize(10); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| align | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Align.html) | Align.LEFT | [Yes](#caption-options-scriptable) | Specifies the text horizontal alignment used when drawing the caption. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#caption-options-scriptable) | Color of caption.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | `true` | - | If `true`, the captions will be applied to the elements. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `Defaults.get().getGlobal()`
`.getFont()` | [Yes](#caption-options-scriptable) | Font of text of caption.
See [Font](../defaults/DefaultsCharts#font). +| formatter | [FormatterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/FormatterCallback.html) | `null` | [Yes](#caption-formatter) | Scriptable options to enable custom formatting for the caption text to show. +| hoverColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT` | [Yes](#caption-options-scriptable) | Color of caption, when hovered.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| hoverFont | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | `Defaults.get().getGlobal()`
`.getFont()` | [Yes](#caption-options-scriptable) | Font of text of caption, when hovered.
See [Font](../defaults/DefaultsCharts#font). +| padding | int | 3 | - | Specifies the space, in pixels, to apply around captions. + +#### Caption options scriptable + +Scriptable options at captions level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the captions option by a callback +dataset.getCaptions().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| align | [AlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/AlignCallback.html) | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/enums/Align.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<DatasetContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| hoverColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| hoverFont | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<DatasetContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) + + +#### Caption Formatter + +If values are grouped, the value of the group is shown in the chart as caption for all elements belonging to the group. + +This default behavior can be overridden by the `formatter` which is a [FormatterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/callbacks/FormatterCallback.html). + +A `formatter` can return a string which represents the label text. + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets the captions formatter +dataset.getCaptions().setFormatter(new FormatterCallback(){ + + @Override + public String invoke(DatasetContext context){ + // logic + return myLabelText; + } +}); +``` + +### Dividers + +The divider is a line which splits a treemap elements in grouped elements and can be controlled by some options. + + + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// gets dividers +Dividers dividers = dataset.getDividers(); +// dividers must be enabled +dividers.setDisplay(true); +// sets width and color of dividers +dividers.setLineColor(HtmlColor.BLACK); +dividers.setLineWidth(2); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| display | boolean | `false` | - | If `true`, the labels will be applied to the elements. +| lineCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT | - | Cap style of the divider line.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| lineColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.BLACK -          | - | The color of the divider line. +| lineDash | int[] | [] | - | Length and spacing of dashes of the line.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| lineDashOffset | double | 0 | - | Offset for line dashes of the line.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| lineWidth | int | 1 | - | The stroke width of the line, in pixels. + +## Data structure + +The data of a dataset for a treemap chart can be passed in two formats. The data are automatically built, based on the tree data, provided by the users. + +:::caution +The `setData` and `setDataPoints` methods are available, inherited by the bar dataset, but you can **NOT** use them otherwise an exception will throw.
Use `setTree`, `setTreeObjects`, `setTreeObject` or `setTreeNativeObject` instead. + +The `getDataPoints` methods is available and can provide a list of [TreeMapDataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/TreeMapDataPoint.html). +::: + +#### Data as doubles + +A treemap dataset can contain the data as an array or list of doubles, + +```java +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets data as an array of doubles +dataset.setTree(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setTree(list); +``` + +#### Data as objects + +Tree data should be provided by a list of objects. Data is then automatically build. When the data are provided by objects, the `key` dataset property defines the key name in data objects to use for value, and the `groups` dataset property, as list of keys, can be provided to display multiple levels of hierarchy. When you need additional sums based on the data of the objects, the `sumKeys` dataset property, as list of keys, defines multiple keys to add additional sums, on top of the `key` one. + +Data is summarized to groups internally. + + + +
+
+ +```java +// list of TreeMapObject properties +private enum Property implements Key +{ + STATE("state"), + CODE("code"), + REGION("region"), + DIVISION("division"), + INCOME("income"), + POPULATION("population"), + AREA("area"); + + private final String value; + + private Property(String value) { + this.value = value; + } + + @Override + public String value() { + return value; + } +} +// tree objects type +private static class TreeMapObject extends NativeObjectContainer { + + private TreeMapObject(NativeObject nativeObject) { + super(nativeObject); + } +} +// creates the tree objects +List objects = new LinkedList<>(); +// creates or loads objects from external source +... +// creates chart +TreeMapChart chart = new TreeMapChart(); +// creates dataset +TreeMapDataset dataset = chart.newDataset(); +// sets data as an array of doubles +dataset.setTreeObjects(objects); +// sets the value by the key of the object +dataset.setKey(Property.POPULATION); +// sets the keys of the object to group by +dataset.setGroups(Property.REGION, Property.DIVISION, Property.CODE); +``` + +## Options + +The treemap chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/treemap/TreeMapOptions.html) to be configured. + +```java +// creates the chart +TreeMapChart chart = new TreeMapChart(); +// gets the chart options +TreeMapOptions options = chart.getOptions(); +// gets treemap element options +TreeMapElementOptions treemapOptions = options.getElements().getElement(TreeMapElementOptions.FACTORY); +// sets value +treemapOptions.setBorderColor(HtmlColor.RED); + +// ------------------------ +// DEFAULTS +// ------------------------ +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default matrix element options +TreeMapElementOptions defaultOptions = gOptions.getElements().getElement(TreeMapElementOptions.FACTORY); +// sets default value +defaultOptions.setBorderColor(HtmlColor.RED); +``` + +:::info +The treemap chart disables the [LABELS](../extensions/Labels), [ANNOTATION](../extensions/Annotation), [HTML legend](../plugins/PluginHTMLLegend) and [dataset items selector](../plugins/PluginDatasetsItemsSelector) plugins. +::: diff --git a/versioned_docs/version-6.5/charts/VerticalLine.md b/versioned_docs/version-6.5/charts/VerticalLine.md new file mode 100644 index 000000000..ce1ab17c3 --- /dev/null +++ b/versioned_docs/version-6.5/charts/VerticalLine.md @@ -0,0 +1,413 @@ +--- +id: ChartVerticalLine +title: Vertical line chart +hide_title: true +sidebar_label: Vertical line +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Vertical line chart + +A vertical line chart is a variation on a line chart. A line chart is a type of chart which displays information as a series of data or data points connected by straight line segments. + + + +Programmatically, you could use a line chart as following: + +```java +// creates the chart +VerticalLineChart chart = new VerticalLineChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a line chart as following: + +```xml + + + + .... + + ... + + +``` + +## Dataset + +The vertical line chart allows to define the data and a number of properties, used to display the data, by a [vertical line dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/VerticalLineDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +VerticalLineChart chart = new VerticalLineChart(); +// creates the dataset +VerticalLineDataset dataset = chart.newDataset(); +// sets the option +dataset.setBorderColor(HtmlColor.RED); +... +// creates the dataset +VerticalLineDataset datasetNew = new VerticalLineDataset(); +// sets the option +datasetNew.setBorderColor(HtmlColor.RED); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line. +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line. +| borderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#scriptable) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#scriptable) | The width of the line in pixels. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#scriptable) | Algorithm used to interpolate a smooth curve from the discrete data points. +| clip | boolean - double - [Clip](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Clip.html) | - | How to clip relative to chart area. Positive value allows overflow, negative value clips that many pixels inside chart area. +| drawActiveElementsOnTop | boolean | [Yes](#scriptable) | Draw the active points of a dataset over the other points of the dataset. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | [Yes](#scriptable) | How to fill the area under the line. See [Filling modes](../coloring/Colors#filling). +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The fill color/pattern under the line, when hovered. +| hoverBorderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#scriptable) | Cap style of the line, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) | [Yes](#scriptable) | The color of the line, when hovered. +| hoverBorderDash | int[] | [Yes](#scriptable) | Length and spacing of dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| hoverBorderDashOffset | int | [Yes](#scriptable) | Offset for line dashes, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#scriptable) | Line joint style, when hovered. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#scriptable) | The width of the line in pixels, when hovered. +| label | String | - | The label for the dataset which appears in the legend and tooltips. +| normalized | boolean | - | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | int | - | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | boolean | - | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| pointBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The fill color for points. +| pointBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | The border color for points. +| pointBorderWidth | int[] | [Yes](#scriptable) | The width of the point border in pixels. +| pointHitRadius | double[] | [Yes](#scriptable) | The pixel size of the non-displayed point that reacts to mouse events. +| pointHoverBackgroundColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point background color when hovered. +| pointHoverBorderColor | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html)[] | [Yes](#scriptable) | Point border color when hovered. +| pointHoverBorderWidth | int[] | [Yes](#scriptable) | Border width of point when hovered. +| pointHoverRadius | double[] | [Yes](#scriptable) | The radius of the point when hovered. +| pointRadius | double[] | [Yes](#scriptable) | The radius of the point shape. If set to 0, the point is not rendered. +| pointRotation | double[] | [Yes](#scriptable) | The rotation of the point in degrees. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html)[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html)[] - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html)[] | [Yes](#scriptable) | Style of the point. +| showLine | boolean | - | If `false`, the line is not drawn for this dataset. +| spanGaps | boolean - double | - | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. +| stepped | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | - | If the line is shown as a stepped line. +| tension | double | - | Bezier curve tension of the line. Set to 0 to draw straight lines. This option is ignored if monotone cubic interpolation is used. +| xAxisID | String | - | The ID of the x axis to plot this dataset on. +| yAxisID | String | - | The ID of the y axis to plot this dataset on. + +### General + +The general options for a vertical line dataset can control behaviors not related to styling or interactions and they are the following: + +| Name | Defaults | Description +| :- | :- | :- +| clip | Undefined.DOUBLE | How to clip relative to chart area. +| drawActiveElementsOnTop | `true` | Draw the active points of a dataset over the other points of the dataset. +| label | `null` | The label for the dataset which appears in the legend and tooltips. +| normalized | `false` | If `true`, you provide data with indices that are unique, sorted, and consistent across data sets and provide the normalized. +| order | 0 | The drawing order of dataset. Also affects order for stacking, tooltip, and legend. +| parsing | `true` | If `false`, the data set parsing is disable. If parsing is disabled, data must be sorted and in the formats the associated chart type and scales use internally. +| xAxisID | [DefaultScaleId.X](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the x axis to plot this dataset on. +| yAxisID | [DefaultScaleId.Y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultScaleId.html) | The ID of the y axis to plot this dataset on. + +### Point styling + +The style of each point of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| pointBackgroundColor | The fill color for points. +| pointBorderColor | The border color for points. +| pointBorderWidth | The width of the point border in pixels. +| pointHitRadius | The pixel size of the non-displayed point that reacts to mouse events. +| pointRadius | The radius of the point shape. +| pointRotation | The rotation of the point in degrees. +| pointStyle | Style of the point. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line styling + +The style of each line of the dataset can be configured by the following properties: + +| Name | Description +| :- | :- +| backgroundColor | The fill color under the line. +| borderCapStyle | Cap style of the line. +| borderColor | The color of the line. +| borderDash | Length and spacing of dashes. +| borderDashOffset | Offset for line dashes. +| borderJoinStyle | Line joint style +| borderWidth | The width of the line in pixels. +| cubicInterpolationMode | Algorithm used to interpolate a smooth curve from the discrete data points. +| fill | How to fill the area under the line. +| stepped | If the line is shown as a stepped line. +| tension | Bezier curve tension of the line. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Point interactions + +The interaction with each point can be controlled with the following properties: + +| Name | Description +| :- | :- +| pointHoverBackgroundColor | Point background color when hovered. +| pointHoverBorderColor | Point border color when hovered. +| pointHoverBorderWidth | Border width of point when hovered. +| pointHoverRadius | The radius of the point when hovered. + +All above options have got the fallback to the associated [Point](../configuration/Elements#point) elements, retrievable by the following statements: + +```java +// from chart instance +Point point = chart.getOptions().getElements().getPoint(); +// sets options for all line datasets of the chart +point.setRadius(6); +... +// from defaults +Point defaultPoint = Defaults.get().getGlobal().getElements().getPoint(); +// sets options for all line datasets of all charts +defaultPoint.setRadius(6); +``` + +### Line interactions + +The interaction with each line can be controlled with the following properties: + +| Name | Description +| :- | :- +| hoverBackgroundColor | The fill color under the line, when hovered. +| hoverBorderCapStyle | Cap style of the line, when hovered. +| hoverBorderColor | The color of the line, when hovered. +| hoverBorderDash | Length and spacing of dashes, when hovered. +| hoverBorderDashOffset | Offset for line dashes, when hovered. +| hoverBorderJoinStyle | Line joint style, when hovered. +| hoverBorderWidth | The width of the line in pixels, when hovered. + +All above options have got the fallback to the associated [Line](../configuration/Elements#line) elements, retrievable by the following statements: + +```java +// from chart instance +Line line = chart.getOptions().getElements().getLine(); +// sets options for all line datasets of the chart +line.setBorderWidth(6); +... +// from defaults +Line defaultLine = Defaults.get().getGlobal().getElements().getLine(); +// sets options for all line datasets of all charts +defaultLine.setBorderWidth(6); +``` + +### Scriptable + +Scriptable options at dataset level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](../configuration/ScriptableOptions) section. + +```java +// creates chart +VerticalLineChart chart = new VerticalLineChart(); +// creates dataset +VerticalLineDataset dataset = chart.newDataset(); +// sets the option by a callback +dataset.setBorderColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| drawActiveElementsOnTop | [DrawActiveElementsOnTopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DrawActiveElementsOnTopCallback.html) | boolean +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FillCallback.html) | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| hoverBorderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | int +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointHoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| pointHoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| pointHoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointRotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +## Data structure + +The data of a dataset for a line chart can be passed in three formats. + +#### Data as doubles + +When the data is an array or list of doubles, the x axis is generally a category. The points are placed onto the axis using their position in the array. When a line chart is created with a category axis, the [labels property of the data object](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Data.html#setLabels-java.lang.String...-) must be specified. + +```java +// sets data as an array of doubles +dataset.setData(1,2,3,4,6); + +// sets data as a list of double +List list = new LinkedList<>(); +list.add(1); +list.add(2); +list.add(3); +dataset.setData(list); +``` + +#### Data as DataPoint + +This alternate is used for sparse datasets, such as those in scatter or time series charts. Each data point is specified using an object containing `x` and `y` properties (for scatter chart) or containing `y` and `t` (as time type) properties for time series. + +```java +// creates a datapoint +DataPoint dp1 = new DataPoint(); +dp1.setX(10); +dp1.setY(20); +// creates a datapoint +DataPoint dp2 = new DataPoint(); +dp2.setX(30); +dp2.setY(40); +// sets data by an array of datapoints +dataset.setDataPoint(dp1, dp2); +``` + +## Options + +The line chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/LineOptions.html) to be configured. These options are merged with the global chart configuration options to form the options passed to the chart. + +```java +// creates chart +VerticalLineChart chart = new VerticalLineChart(); +// gets the chart options +VerticalLineOptions options = chart.getOptions(); +// sets options +options.setResponsive(true); +options.setShowLine(false); +``` + +These are the options specific to line charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| showLine | boolean | `true` | If `false`, the lines between points are not drawn. +| spanGaps | boolean - double | `false` | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. + +### Segment + +The vertical line charts can contain a segment options element which can manage the styles of data sets in each own segment between the points and can override the data set configuration by scriptable options. + +```java +// creates chart +VerticalLineChart chart = new VerticalLineChart(); +// sets segment callback for border color +chart.getOptions().getSegment().setBorderColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the border color will be "green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getX(); + double valuePoint1 = context.getEndPoint().getParsed().getX(); + return valuePoint0 < valuePoint1 ? HtmlColor.GRAY : HtmlColor.GREEN; + } +}); +// sets segment callback for background color +chart.getOptions().getSegment().setBackgroundColor(new ColorCallback() { + + @Override + public Object invoke(SegmentContext context) { + // if value of point 1 greater than value of point 0 + // the background color will be "light green", otherwise "gray" + double valuePoint0 = context.getStartPoint().getParsed().getX(); + double valuePoint1 = context.getEndPoint().getParsed().getX(); + return valuePoint0 < valuePoint1 ? HtmlColor.LIGHT_GRAY : HtmlColor.LIGHT_GREEN; + } +}); +``` + + + +Currently all of the border options and background color are supported. The segment styles are resolved for each section of the vertical line between each point. + +These are the options specific to line charts: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<SegmentContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<SegmentContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<SegmentContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<SegmentContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<SegmentContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<SegmentContext> | int + +The callbacks are getting the only 1 argument, the [segment context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SegmentContext.html) which contains the context of the callback execution. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| datasetIndex | int | The index of the dataset. +| endDataIndex | int | The index of second point in the data. +| endPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the end point of the segment. +| startDataIndex | int | The index of first point in the data. +| startPoint | [PointElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PointElement.html) | The line element for the start point of the segment. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.SEGMENT`. diff --git a/versioned_docs/version-6.5/charts/geo/BubbleMap.md b/versioned_docs/version-6.5/charts/geo/BubbleMap.md new file mode 100644 index 000000000..8a159519f --- /dev/null +++ b/versioned_docs/version-6.5/charts/geo/BubbleMap.md @@ -0,0 +1,333 @@ +--- +id: ChartBubbleMap +title: BubbleMap chart +hide_title: true +sidebar_label: BubbleMap +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Bubble map chart + +(quoted from [Proportional Symbol Map](https://en.wikipedia.org/wiki/Proportional_symbol_map) definition in Wikipedia) + +A Bubble Map (or Proportional Symbol Map) is a type of thematic map that uses map symbols that vary in size to represent a quantitative variable. For example, circles may be used to show the location of cities within the map, with the size of each circle sized proportionally to the population of the city. + +It is a map chart type that uses the visual variable of size to display differences in the magnitude of a certain discrete, abruptly changing phenomenon. + + + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +BubbleMapChart chart = new BubbleMapChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +### Controller registration + +The controller registration is performed when a first BUBBLE MAP chart has been instantiated. When there is a use case where some defaults options must be set before the first instantiation, you need to register the controller before changing the default options. + +```java +// registers the controller +BubbleMapChart.register(); +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default bubble map element options +GeoFeatureElementOptions defaultOptions = gOptions.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets default value +defaultOptions.setOutlineBorderColor(HtmlColor.RED); +``` + +## Dataset + +The bubble map chart allows to define the data and a number of properties, used to display the data, by a [bubble map dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/BubbleMapDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +BubbleMapChart chart = new BubbleMapChart(); +// creates the dataset +BubbleMapDataset dataset = chart.newDataset(); +// sets the option +dataset.setBackgroundColor(HtmlColor.RED); +dataset.setShowGraticule(true); +... +// creates the dataset +BubbleMapDataset datasetNew = new BubbleMapDataset(); +// sets the option +datasetNew.setBackgroundColor(HtmlColor.RED); +datasetNew.setShowGraticule(true); +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| clipMap | boolean - [ClipMap](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/ClipMap.html)| ClipMap.TRUE | Whether to clip the rendering to the chart area of the graph or to another area. +| outline | [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html)[] | [] | The features used to scale and centralize the projection in the chart area. +| showGraticule | boolean - [Graticule](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Graticule.html) | `false` | If enabled it by `true` or graticule object instance, it renders the lines in the background. +| showOutline | boolean | `false` | If `true` to render the outline in the background + +### Styling + +The style of the dataset can be configured by a [Point](../../configuration/Elements#point) element. + +The style for the geografical configuration of the dataset can be configured by [`geoFeature` element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoFeature.html), as following: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| graticuleBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(204,204,204) -          | The graticule border color. +| graticuleBorderWidth | int | 0 | The outline border width. +| outlineBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `null` | The outline background color. +| outlineBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | The outline border color. +| outlineBorderWidth | int | 0 | The outline border width. + +```java +// from chart instance +GeoFeature geoElement = chart.getOptions().getElements().getGeoFeature(); +// sets options for bubble map datasets of the chart +geoElement.setOutlineBorderWidth(3); +geoElement.setGraticuleBorderColor(HtmlColor.RED); +... +``` + +## Data structure + +Bubble map dataset needs to contain a data array of points, each data point has to contain the latitude and longitude of the point to render and containing the value for the coloring. + +Bubble map data points are mapped by [ChoroplethDataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/BubbleMapDataPoint.html). + +```java +// creates data points container +List dataPoints = new LinkedList<>(); +// creates a data point +BubbleMapDataPoint dp = new BubbleMapDataPoint(latitude, longitude, 20); +// adds data points +dataPoints.add(dp); +// sets values by an list of data points +dataset.setValues(dataPoints); +``` + +:::caution +The `setData` and `setDataPoints` methods are available, inherited by the bubble dataset, but you can **NOT** use them otherwise an exception will throw.
Use `setValues` instead. +::: + +## Options + +The bubble map chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/BubbleMapOptions.html) to be configured. + +```java +// creates the chart +BubbleMapChart chart = new BubbleMapChart(); +// gets the chart options +BubbleMaOptions options = chart.getOptions(); +options.setShowGraticule(true); + +// ------------------------ +// ELEMENT +// ------------------------ +// gets bubble map element options +GeoFeatureElementOptions bubbleMapOptions = options.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets value +bubbleMapOptions.setOutlineBorderColor(HtmlColor.RED); + +// ------------------------ +// DEFAULTS +// ------------------------ +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default bubble map element options +GeoFeatureElementOptions defaultOptions = gOptions.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets default value +defaultOptions.setOutlineBorderColor(HtmlColor.RED); +``` + +These are the options specific to bubble map charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| clipMap | boolean - [ClipMap](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/ClipMap.html)| ClipMap.OUTLINE_GRATICULE | Whether to clip the rendering to the chart area of the graph or to another area. +| outline | [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html)[] | empty list | The features used to scale and centralize the projection in the chart area. +| showGraticule | boolean - [Graticule](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Graticule.html) | `false` | If enabled it by `true` or graticule object instance, it renders the lines in the background. +| showOutline | boolean | `false` | If `true` to render the outline in the background + +:::info +The bubble map chart disables the legend component. +::: + +## Scales + +A bubble map chart can have maximum 2 scales, of the following types: + + * [Projection](ChartBubbleMap#projection-axis) scale which defines a way to flatten a globe's surface into a plane in order to make a map. + * [Size](ChartBubbleMap#size-axes) scale which is used to map the values to symbol radius size. + +### Projection axis + +A [Projection axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ProjectionAxis.html) is managing the map projection. + +A map projection is a way to flatten a globe's surface into a plane in order to make a map. + +This requires a systematic transformation of the latitudes and longitudes of locations from the surface of the globe into locations on a plane. + +Here is an example how to create a projection axis: + +```java +// creates the chart +BubbleMapChart chart = new BubbleMapChart(); +// creates a projection axis +// scale id and axis kind are already defined +ProjectionAxis axis = new ProjectionAxis(chart); +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis); +``` + +#### Options + +The projection axis allows to define a number of properties, used to display the data. + +```java +// creates a projection axis +ProjectionAxis axis = new ProjectionAxis(chart); +// sets options +axis.setProjection(Projection.EQUAL_EARTH); +axis.setProjectionScale(0.5); +axis.setProjectionOffset(0, -50); + +Projection projection = axis.getProjection(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 0 to all dimensions | Sets padding applied during auto scaling of the map in pixels, i.e. the chart size is reduce by the padding before fitting the map. +| projection | [Projection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Projection.html) | Projection.ALBERS_USA | The map projection which is a way to flatten a globe's surface into a plane in order to make a map +| projectionOffset | [double, double] | [] | The map projection offset value. +| projectionScale | double | Undefined.DOUBLE | How much the map will be scaled. + +### Size axis + +A size axis is used to map the values to symbol radius size. + +There are 2 axis types to map the values to symbol radius size: + + * [Size axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/SizeAxis.html) which extends the [cartesian linear axis](../../axes/CartesianLinearAxes) to repesent numbers. + * [Size logarithmic axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/SizeLogarithmicAxis.html) which extends the [cartesian logarithmic axis](../../axes/CartesianLogarithmicAxes) to represent number by logarithmic base. + +Here is an example how to create a size axis: + +```java +// creates the chart +BubbleMapChart chart = new BubbleMapChart(); +// creates a size axis +// scale id and axis kind are already defined +SizeAxis axis = new SizeAxis(chart); +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis); +``` + +#### Options + +The size axis allows to define a number of properties, used to display the data. + +```java +// creates a size axis +SizeAxis axis = new SizeAxis(chart); +// sets options +axis.setInterpolate(Interpolate.BLUES); +axis.setQuantize(5); + +Interpolate interpolate = axis.getInterpolate(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| mode | [Mode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Mode.html) | Mode.AREA | [Yes](#scriptable) | The operation modes for the scale, area means that the area is linearly increasing whereas radius the radius is. +| missingRadius | double | 1 | [Yes](#scriptable) | The radius of the points to use the data is missing. +| range | [int, int] | [2, 20] | [Yes](#scriptable) | The radius range in pixel, the minimal data value will be mapped to the first entry, the maximal one to the second and a linear interpolation for all values in between. + +#### Legend + +You can configure the legend which is representing the color interpolation for bubble map chart. + +```java +// creates a size axis +SizeAxis axis = new SizeAxis(chart); +// sets legend options +axis.getLegend().setPosition(Position.TOP_RIGHT); + +Position position = axis.getLegend().getPosition(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| align | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Align.html) | Align.RIGHT | [Yes](#scriptable) | The alignment of the legend on the chart area. +| indicatorWidth | int | 10 | [Yes](#scriptable) | how many pixels should be used for the color bar. +| length | int | 100 | [Yes](#scriptable) | The length of the legend, in terms of value. +| margin | int | 8 | [Yes](#scriptable) | The margin pixels such that it doesn't stick to the edge of the chart. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Position.html) - [PositionPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/PositionPoint.html) | Position.BOTTOM_RIGHT | [Yes](#scriptable) | The location of the legend on the chart area. +| width | int | 50 | [Yes](#scriptable) | How wide the scale is.
For a horizontal scale the height if a value less than 1 is given, is it assume to be a ratio of the corresponding chart area. + +#### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying scale values. See more details in [Configuring charts](../../configuration/ScriptableOptions) section. + +```java +// creates a size axis +SizeAxis axis = new SizeAxis(chart); +// sets legend options by a callback +axis.getLegend().setPosition(new PositionCallback(){ + + @Override + public Position invoke(ScaleContext context){ + // logic + return position; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| mode | [ModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/ModeCallback.html) | [Mode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Mode.html) +| missingRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<ScaleContext> | double +| range | [RangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/RangeCallback.html) | List<Integer> +| align | [AlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/AlignCallback.html) | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Align.html) +| indicatorWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int +| length | [LengthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/LengthCallback.html) | int +| margin | [MarginCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/MarginCallback.html) | int - [Margin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Margin.html) +| position | [PositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/PositionCallback.html) | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Position.html) - [PositionPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/PositionPoint.html) +| width | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int diff --git a/versioned_docs/version-6.5/charts/geo/Choropleth.md b/versioned_docs/version-6.5/charts/geo/Choropleth.md new file mode 100644 index 000000000..7d2dd6b2f --- /dev/null +++ b/versioned_docs/version-6.5/charts/geo/Choropleth.md @@ -0,0 +1,375 @@ +--- +id: ChartChoropleth +title: Choropleth chart +hide_title: true +sidebar_label: Choropleth +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Choropleth chart + +(quoted from [Choropleth chart](https://en.wikipedia.org/wiki/Choropleth_map) definition in Wikipedia) + +A choropleth chart is a type of thematic map in which a set of pre-defined areas is colored or patterned in proportion to a statistical variable that represents an aggregate summary of a geographic characteristic within each area, such as population density or per-capita income. + +Choropleth maps provide an easy way to visualize how a variable varies across a geographic area or show the level of variability within a region. The choropleth is likely the most common type of thematic map because published statistical data (from government or other sources) is generally aggregated into well-known geographic units, such as countries, states, provinces, and counties. + + + +Programmatically, you could use a bar chart as following: + +```java +// creates the chart +ChoroplethChart chart = new ChoroplethChart(); +// adds to DOM +component.add(chart); +... +// example for Elemental2 +// gets the chart instance as DOM element +Element element = chart.getChartElement().as(); +// adds to DOM +DomGlobal.document.body.appendChild(element); +``` + +By [UIBinder](http://www.gwtproject.org/doc/latest/DevGuideUiBinder.html) (**ONLY for GWT**), you could use a bar chart as following: + +```xml + + + + .... + + ... + + +``` + +### Controller registration + +The controller registration is performed when a first CHOROPLETH chart has been instantiated. When there is a use case where some defaults options must be set before the first instantiation, you need to register the controller before changing the default options. + +```java +// registers the controller +ChoroplethChart.register(); +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default choropleth element options +GeoFeatureElementOptions defaultOptions = gOptions.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets default value +defaultOptions.setOutlineBorderColor(HtmlColor.RED); +``` + +## Dataset + +The choropleth chart allows to define the data and a number of properties, used to display the data, by a [choropleth dataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ChoroplethDataset.html). + +Every chart has got a method to create a typed dataset accordingly with the chart type. The dataset can be also created instantiating the constructor. + +```java +// creates the chart +ChoroplethChart chart = new ChoroplethChart(); +// creates the dataset +ChoroplethDataset dataset = chart.newDataset(); +// sets the option +dataset.setShowGraticule(true); +... +// creates the dataset +ChoroplethDataset datasetNew = new ChoroplethDataset(); +// sets the option +datasetNew.setShowGraticule(true); +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| clipMap | boolean - [ClipMap](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/ClipMap.html)| ClipMap.TRUE | Whether to clip the rendering to the chart area of the graph or to another area. +| outline | [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html)[] | [] | The features used to scale and centralize the projection in the chart area. +| showGraticule | boolean - [Graticule](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Graticule.html) | `false` | If enabled it by `true` or graticule object instance, it renders the lines in the background. +| showOutline | boolean | `false` | If `true` to render the outline in the background + +### Styling + +The style of the dataset can be configured by [`geoFeature` element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoFeature.html), which extends a [Bar](../../configuration/Elements#bar) elements, as following: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| graticuleBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgb(204,204,204) -          | The graticule border color. +| graticuleBorderWidth | int | 0 | The outline border width. +| outlineBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `null` | The outline background color. +| outlineBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | The outline border color. +| outlineBorderWidth | int | 0 | The outline border width. + +```java +// from chart instance +GeoFeature geoElement = chart.getOptions().getElements().getGeoFeature(); +// sets options for choropleth datasets of the chart +geoElement.setOutlineBorderWidth(3); +geoElement.setGraticuleBorderColor(HtmlColor.RED); +... +``` + +## Data structure + +Choropleth dataset needs to contain a data array of points, each data point has to contain the [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html) to render and containing the value for the coloring. + +Choropleth data points are mapped by [ChoroplethDataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ChoroplethDataPoint.html). + +```java +// gets the topoJSON map as string +String topoJsonText = MyResources.INSTANCE.topojsonEarth().getText(); +// creates a topoJSON object, needed for further computations +TopoJson world = GeoUtil.createTopoJson(topoJsonText); +// the node name in "objects" one where the topology +// are stored is "countries" +List features = GeoUtil.features(world, "countries"); +... +// creates data points container +List dataPoints = new LinkedList<>(); +for (Feature feature : features){ + // creates a data point + ChoroplethDataPoint dp = new ChoroplethDataPoint(feature, 20); + // adds data points + dataPoints.add(dp); +} +// sets values by an list of data points +dataset.setValues(dataPoints); +``` + +:::caution +The `setData` and `setDataPoints` methods are available, inherited by the bar dataset, but you can **NOT** use them otherwise an exception will throw.
Use `setValues` instead. +::: + +## Options + +The choropleth chart defines specific [options implementation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ChoroplethOptions.html) to be configured. + +```java +// creates the chart +ChoroplethChart chart = new ChoroplethChart(); +// gets the chart options +ChoroplethOptions options = chart.getOptions(); +// sets value +options.setShowGraticule(true); + +// ------------------------ +// ELEMENT +// ------------------------ +// gets choropleth element options +GeoFeatureElementOptions choroplethOptions = options.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets value +choroplethOptions.setOutlineBorderColor(HtmlColor.RED); + +// ------------------------ +// DEFAULTS +// ------------------------ +// gets default options +GlobalOptions gOptions = Defaults.get().getGlobal(); +// gets default bubble map element options +GeoFeatureElementOptions defaultOptions = gOptions.getElements().getElement(GeoFeatureElementOptions.FACTORY); +// sets default value +defaultOptions.setOutlineBorderColor(HtmlColor.RED); +``` + +These are the options specific to choropleth charts: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| clipMap | boolean - [ClipMap](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/ClipMap.html)| ClipMap.TRUE | Whether to clip the rendering to the chart area of the graph or to another area. +| outline | [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html)[] | empty list | The features used to scale and centralize the projection in the chart area. +| showGraticule | boolean - [Graticule](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Graticule.html) | `false` | If enabled it by `true` or graticule object instance, it renders the lines in the background. +| showOutline | boolean | `false` | If `true` to render the outline in the background + +:::info +The choropleth chart disables the legend component. +::: + +## Scales + +A choropleth chart can have maximum 2 scales, of the following types: + + * [Projection](ChartChoropleth#projection-axis) scale which defines a way to flatten a globe's surface into a plane in order to make a map. + * [Color](ChartChoropleth#color-axes) scale which enables the coloring of the nodes. + +### Projection axis + +A [Projection axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ProjectionAxis.html) is managing the map projection. + +A map projection is a way to flatten a globe's surface into a plane in order to make a map. + +This requires a systematic transformation of the latitudes and longitudes of locations from the surface of the globe into locations on a plane. + +Here is an example how to create a projection axis: + +```java +// creates the chart +ChoroplethChart chart = new ChoroplethChart(); +// creates a projection axis +// scale id and axis kind are already defined +ProjectionAxis axis = new ProjectionAxis(chart); +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis); +``` + +#### Options + +The projection axis allows to define a number of properties, used to display the data. + +```java +// creates a projection axis +ProjectionAxis axis = new ProjectionAxis(chart); +// sets options +axis.setProjection(Projection.EQUAL_EARTH); +axis.setProjectionScale(0.5); +axis.setProjectionOffset(0, -50); + +Projection projection = axis.getProjection(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 0 to all dimensions | Sets padding applied during auto scaling of the map in pixels, i.e. the chart size is reduce by the padding before fitting the map. +| projection | [Projection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Projection.html) | Projection.ALBERS_USA | The map projection which is a way to flatten a globe's surface into a plane in order to make a map +| projectionOffset | [double, double] | [] | The map projection offset value. +| projectionScale | double | Undefined.DOUBLE | How much the map will be scaled. + +### Color axis + +A color axis is managing the coloring of the nodes. + +A color axis manages how the map must be colored providing also a legend to see the color distribution for the choropleth chart. + + + +There are 2 axis types for coloring the nodes: + + * [Color axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ColorAxis.html) which extends the [cartesian linear axis](../../axes/CartesianLinearAxes) to repesent numbers. + * [Color logarithmic axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/ColorLogarithmicAxis.html) which extends the [cartesian logarithmic axis](../../axes/CartesianLogarithmicAxes) to represent number by logarithmic base. + +Here is an example how to create a color axis: + +```java +// creates the chart +ChoroplethChart chart = new ChoroplethChart(); +// creates a color axis +// scale id and axis kind are already defined +ColorAxis axis = new ColorAxis(chart); +// adds axes to chart configuration +chart.getOptions().getScales().setAxes((axis); +``` + +#### Options + +The color axis allows to define a number of properties, used to display the data. + +```java +// creates a color axis +ColorAxis axis = new ColorAxis(chart); +// sets options +axis.setInterpolate(Interpolate.BLUES); +axis.setQuantize(5); + +Interpolate interpolate = axis.getInterpolate(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| interpolate | [Interpolate](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Interpolate.html) | Interpolate.BLUES | [Yes](#scriptable) | The color interpolation of the scale. +| missingColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#scriptable) | The color to use the data is missing. +| quantize | int | 0 | [Yes](#scriptable) | The amount of pieces to allow to split the color scale in N quantized equal bin. + +#### Interpolate callback + +You can set the color interpolation of the scale at runtime, providing different colors for different features. + + + +The interpolate property can be set as [scriptable option](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/InterpolateCallback.html), as following: + +```java +// uses the color list of tableau color scheme +private static final List COLORS = TableauScheme.CLASSIC_AREA_RED_GREEN21.getColors(); +... +... +// creates a color axis +ColorAxis axis = new ColorAxis(chart); +// sets callback +axis.setInterpolate(new InterpolateCallback(){ + + /** + * Returns a color instance. + * + * @param normalizedValue normalized value of the data set + * @return a color instance + */ + @Override + public Object interpolate(double normalizedValue) { + int index = (int)Math.round(normalizedValue * (COLORS.size() - 1)); + return COLORS.get(Math.min(index, COLORS.size() - 1)); + } +}); +``` + +#### Legend + +You can configure the legend which is representing the color interpolation for choropleth chart. + +```java +// creates a color axis +ColorAxis axis = new ColorAxis(chart); +// sets legend options +axis.getLegend().setPosition(Position.TOP_RIGHT); + +Position position = axis.getLegend().getPosition(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| align | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Align.html) | Align.RIGHT | [Yes](#scriptable) | The alignment of the legend on the chart area. +| indicatorWidth | int | 10 | [Yes](#scriptable) | how many pixels should be used for the color bar. +| length | int | 100 | [Yes](#scriptable) | The length of the legend, in terms of value. +| margin | int | 8 | [Yes](#scriptable) | The margin pixels such that it doesn't stick to the edge of the chart. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Position.html) - [PositionPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/PositionPoint.html) | Position.BOTTOM_RIGHT | [Yes](#scriptable) | The location of the legend on the chart area. +| width | int | 50 | [Yes](#scriptable) | How wide the scale is.
For a horizontal scale the height if a value less than 1 is given, is it assume to be a ratio of the corresponding chart area. + +#### Scriptable + +Scriptable options at scale level accept a callback which is called for each of the underlying scale values. See more details in [Configuring charts](../../configuration/ScriptableOptions) section. + +```java +// creates a color axis +ColorAxis axis = new ColorAxis(chart); +// sets legend options by a callback +axis.getLegend().setPosition(new PositionCallback(){ + + @Override + public Position invoke(ScaleContext context){ + // logic + return position; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| missingColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ScaleContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| quantize | [QuantizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/QuantizeCallback.html) | int +| align | [AlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/AlignCallback.html) | [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Align.html) +| indicatorWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int +| length | [LengthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/LengthCallback.html) | int +| margin | [MarginCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/MarginCallback.html) | int - [Margin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Margin.html) +| position | [PositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/callbacks/PositionCallback.html) | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/enums/Position.html) - [PositionPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/PositionPoint.html) +| width | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<ScaleContext> | int diff --git a/versioned_docs/version-6.5/charts/geo/Introduction.md b/versioned_docs/version-6.5/charts/geo/Introduction.md new file mode 100644 index 000000000..d609d882e --- /dev/null +++ b/versioned_docs/version-6.5/charts/geo/Introduction.md @@ -0,0 +1,152 @@ +--- +id: Geo +title: Introduction +hide_title: true +sidebar_label: Introduction +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Geographic map charts + +**Charba** provides out of the box the feature to enable some geographic map chart, leveraging on [Chart.js Geo](https://github.com/sgratzl/chartjs-chart-geo). + +The [Chart.js Geo](https://github.com/sgratzl/chartjs-chart-geo) is *native javascript* implementation and **Charba** provides the wrapper in order to be able to use it. + + + +Currently the [Chart.js Geo](https://github.com/sgratzl/chartjs-chart-geo), ready to use inside **Charba**, can provide the following charts types: + + * [Choropleth](ChartChoropleth) which can be used to render maps with the area filled according to some numerical value. + * [BubbleMap](ChartBubbleMap), as know as Proportional Symbol, which is used to render maps with dots that are scaled according to some numerical value. + +## Maps + +The maps used to render the chart must be based on [TopoJSON](https://github.com/topojson/topojson) definitions. + +[TopoJSON](https://github.com/topojson/topojson) is an extension of GeoJSON that encodes topology. [TopoJSON](https://github.com/topojson/topojson) is a topological geospatial data format. In contrast to a geometry, where each shape is encoded with separate (and often redundant) arrays of coordinates, a topology encodes sequences of coordinates in line fragments called arcs that can be shared. For example, the border between 2 states is an arc that is shared by both polygons. + +The main benefit of a topology is that it improves shape simplification by avoiding artifacts that would be caused by simplifying shapes independently. It also enables applications like map coloring and selective meshing, and makes the format more compact by removing redundant coordinates. + +Here is the [TopoJSON specification](https://github.com/topojson/topojson-specification) + +However, **Charba** does not include any [TopoJSON](https://github.com/topojson/topojson) files itself. Some useful resources are the following: + + * US map: https://www.npmjs.com/package/us-atlas + * World map: https://www.npmjs.com/package/world-atlas + * [TopoJSON](https://github.com/topojson/topojson) collection: https://github.com/deldersveld/topojson + +### Loading + +The maps can be loaded: + + * at runtime, invoking some HTTP services in order to get the needed [TopoJSON](https://github.com/topojson/topojson) definitions. + * at project level, by [GWT Web toolkit clientBundle](http://www.gwtproject.org/doc/latest/DevGuideClientBundle.html#TextResource), if you are developing a [GWT Web toolkit](http://www.gwtproject.org/) project. + * at project level, by the implementation of a [AbstractInjectableResource](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/resources/AbstractInjectableResource.html) class. + +An example how to load a map by [GWT Web toolkit clientBundle](http://www.gwtproject.org/doc/latest/DevGuideClientBundle.html#TextResource) is the following: + + 1. take the [TopoJSON](https://github.com/topojson/topojson) definition and store in your project in a resource folder. + 1. create a GWT [ClientBundle](http://www.gwtproject.org/doc/latest/DevGuideClientBundle.html) to get the [TopoJSON](https://github.com/topojson/topojson) definition as GWT [TextResource](http://www.gwtproject.org/doc/latest/DevGuideClientBundle.html#TextResource) + 1. use [GeoUtil](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoUtil.html) to get a [TopoJson](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/TopoJson.html) instance. + +An example how to load a map by [GWT Web toolkit clientBundle](http://www.gwtproject.org/doc/latest/DevGuideClientBundle.html#TextResource) is the following: + + * get the world map JSON file from [NPMjs](https://cdn.jsdelivr.net/npm/world-atlas@2/countries-50m.json) and store it in your project, in this example we are using the **Charba** showcase paths: + * `/src/org/pepstock/charba/showcase/client/resources/topojson/countries-50m.json` + * create a client bundle (called in this example `org.pepstock.charba.showcase.client.resources.MyResources.java`) with the [TopoJSON](https://github.com/topojson/topojson) map reference: + +```java +package org.pepstock.charba.showcase.client.resources; + +import com.google.gwt.core.client.GWT; +import com.google.gwt.resources.client.ClientBundle; +import com.google.gwt.resources.client.TextResource; + +public interface MyResources extends ClientBundle { + + public static final MyResources INSTANCE = GWT.create(MyResources.class); + + @Source("topojson/countries-50m.json") + TextResource topojsonEarth(); + +} +``` + + * use [GeoUtil](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoUtil.html) to get a [TopoJson](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/TopoJson.html) instance. + +```java +// gets the topoJSON map as string +String topoJsonText = MyResources.INSTANCE.topojsonEarth().getText(); +// creates a topoJSON object, needed for further computations +TopoJson world = GeoUtil.createTopoJson(topoJsonText); +``` + +## Features + +A topology is a [TopoJSON](https://github.com/topojson/topojson) object where the type member’s value is the topology. + +A topology must have a member with the name `objects` whose value is another object. The value of each member of this object is a geometry object. + +**Charba** provides methods, by [GeoUtil](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoUtil.html), to parse the [TopoJSON](https://github.com/topojson/topojson) definition and provide a list of [Features](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html) which are mapping the topology needed to render in the chart. + +Every [TopoJSON](https://github.com/topojson/topojson) definition object could be built with a different name spaces, therefore the node name to use as root of object must be provided by the developer. + + ```java +// gets the topoJSON map as string +String topoJsonText = MyResources.INSTANCE.topojsonEarth().getText(); +// creates a topoJSON object, needed for further computations +TopoJson world = GeoUtil.createTopoJson(topoJsonText); +// the node name in "objects" one where the topology +// are stored is "countries" +List features = GeoUtil.features(world, "countries"); +``` + +A [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html) contains the properties of the topology. + +Even in this case, the properties names are not standard. Every feature can have own property names. + +```java + // defines the property name "name" + private static final Key NAME = Key.create("name"); +... +// gets the topoJSON map as string +String topoJsonText = MyResources.INSTANCE.topojsonEarth().getText(); +// creates a topoJSON object, needed for further computations +TopoJson world = GeoUtil.createTopoJson(topoJsonText); +// the node name in "objects" one where the topology +// are stored is "countries" +List features = GeoUtil.features(world, "countries"); + +for (Feature feature: features) { + // gets the name of the country by NAME key instance + String countryName = feature.getStringProperty(NAME); + ... +} +``` + +### Labels + +Usually the labels to display for the geographic map chart are stored in the properties of a [Feature](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/Feature.html), for instance the name of the country, state, regions, provinces, cities and so on. As said above, the properties names are not fixed for all topologies and every topology can have own properties. + +To improve to the access of topology definitions and to help the labels creation, **Charba** provides methods, by [GeoUtil](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/geo/GeoUtil.html), which creates a [Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Labels.html) to set to the chart, as following: + +```java + // defines the property name "name" + private static final Key NAME = Key.create("name"); +... +// gets the topoJSON map as string +String topoJsonText = MyResources.INSTANCE.topojsonEarth().getText(); +// creates a topoJSON object, needed for further computations +TopoJson world = GeoUtil.createTopoJson(topoJsonText); +// the node name in "objects" one where the topology +// are stored is "countries" +List features = GeoUtil.features(world, "countries"); +// creates a labels object with all countries names. +Labels labels = GeoUtil.loadLabels(features, NAME); +// sets labels to chart +chart.getData().setLabels(labels); +``` + +The labels enables the tooltip to shows the property related to the topology that you are representing. + + diff --git a/versioned_docs/version-6.5/coloring/Colors.md b/versioned_docs/version-6.5/coloring/Colors.md new file mode 100644 index 000000000..348f703bc --- /dev/null +++ b/versioned_docs/version-6.5/coloring/Colors.md @@ -0,0 +1,178 @@ +--- +id: Colors +title: Colors +hide_title: true +sidebar_label: Colors and filling +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Coloring + +The colors on charts is very important because can make the difference to have an understandable result or not. + +Usually the colors are managed as string, following the syntax defined for CSS, but sometimes this is annoying because its' easier to have the name of the color. + +**Charba** provides: + + * [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) interface to manage colors + * [Color](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Color.html) entity to create and manage colors + * 3 enumerations with + * all [color names](./tables/HTMLColorsNames) defined for HTML, by enumeration [HtmlColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/HtmlColor.html) + * all [color names](./tables/GWTMaterialColors) defined for GWT Material, by enumeration [GwtMaterialColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GwtMaterialColor.html) + * first [31 color names](./tables/GoogleChartColors) defined for Google Charts, by enumeration [GoogleChartColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GoogleChartColor.html) + * all gradients defined by [UiGradients.com](https://uigradients.com), by enumeration [UiGradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/UiGradient.html) + +**Charba** is using [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) and colors as string in the methods where you must define a color. + +### Building colors + +Even if the usual method is to use strings which are representing colors, leveraging on colors structure of **Charba**, you can use color as objects, defining your base colors and play with transparency without creating a specific string every time. + +The [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) interface (and then all colors defined out of the box) has got a method which returns a another color instance, based from source one, as following: + +```java +// it can be a static reference +Color myColor = new Color(255,0,0); +// new color based on previous one, which is immutable. +IsColor myColorWithAlpha = myColor.alpha(0.2D); +// new Color darker from the previous one +IsColor myDarkerColor = myColor.darker(); +``` + +Another interesting utility is the [ColorBuilder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/ColorBuilder.html) which can create [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) instances by a string. + +```java +// parses color and creates new color. +// by HEX representation +IsColor myColorHex = ColorBuilder.parse("#FF0000"); +// by RGB representation +IsColor myColorRGB = ColorBuilder.parse("rgb(255, 0, 0)"); +// by RGBA representation +IsColor myColorRGBA = ColorBuilder.parse("rgba(255, 0, 0, 0.5)"); +// by HSL representation +IsColor myColorHSL = ColorBuilder.parse("hsl(100, 100%, 50%)"); +// by HSLA representation +IsColor myColorHSLA = ColorBuilder.parse("hsla(100, 100%, 50%, 0.5)"); +// by color names representation +IsColor myColorName = ColorBuilder.parse("red"); +``` + +The parser of [ColorBuilder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/ColorBuilder.html) is able to parse color string representation by HEX, RGB, RGBA, HSL and HSLA. + +The parser can also use HTML color names, defined in the [HtmlColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/HtmlColor.html) enumeration. + +### Default color palette + +If you don't have any preference for colors, you can use [Chart.JS](http://www.chartjs.org/) palette of seven brand colors: + + + +
+
+ +To use the to [Chart.JS](http://www.chartjs.org/) palette, you sould set `autoColors` option to `true`, as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().setAutoColors(true); + +// -------------------------------------- +// for specific chart instance +// -------------------------------------- +chart.getOptions().setAutoColors(true); +``` + +By default the auto colors option only works when you initialize the chart without any colors for the border or background specified. +If you want to force the auto colors to always color your datasets, for example when using dynamic datasets at runtime you will need to set the `autoColorsForceOverride` option to true: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().setAutoColorsForceOverride(true); + +// -------------------------------------- +// for specific chart instance +// -------------------------------------- +chart.getOptions().setAutoColorsForceOverride(true); +``` + +## Filling + +Both [line](../charts/ChartLine) and [radar](../charts/ChartRadar) charts support a `fill` option on the dataset object which can be used to create area between two datasets or a dataset and a boundary. + +### Modes + +**Charba** is providing an enumeration for fixed [filling modes](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Fill.html). + +On top of these, you can set other kind of filling mode, as following: + +| Mode | Type | Values | +| :--- | :--- | :--- | +| Absolute dataset index | int | `1`, `2`, `3`, ... | +| Relative dataset index | String | `"-1"`, `"-2"`, `"+1"`, ... | + + + +To get absolute dataset index, you can get it by `Fill.getFill(int)` and you get a IsFill mode that you can set to **Charba** configuration. + +To get relative dataset index, you can get it by `Fill.getFill(String)` and you get a IsFill mode that you can set to **Charba** configuration. + +Furthermore **Charba** configuration enables the possibility to set directly absolute or relative filling mode, by `setFill(int)` or `setFill(String)` methods. + +### Baseline + +By default, the filling of the datasets uses value equals to 0 of value axis to color the dataset above or below the line. + +You can set a different value, setting the fill options with the axis value you want to use, using a number or a [FillBaseline](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FillBaseline.html) instance. + +```java +```java +// creates the chart +LineChart chart = new LineChart(); +// creates the dataset +LineDataset dataset = chart.newDataset(); +// sets the filling baseline option by a number +// which is the value of value axis +dataset.setFillBaseline(20); +... +// creates the dataset +LineDataset datasetNew = new LineDataset(); +// sets the filling baseline option by a object +// which is the value of value axis +datasetNew.setFillBaseline(new FillBaseline(20)); +... +// sets the datasets to the chart +chart.getData().setDatasets(dataset, datasetNew); +``` + + + +#### Different colors base on baseline + +You can decide to have different filling colors above and below the baseline. + +You can set a different colors, setting the fill options with the your colors you want to use, using a [FillColors](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FillColors.html) instance. + +```java +```java +// creates the chart +LineChart chart = new LineChart(); +// creates the dataset +LineDataset dataset = chart.newDataset(); +// creates a fill colors instance +FillColors colors = new FillColors(); +colors.setFill(Fill.ORIGIN); +colors.setAboveColor(HtmlColor.GREEN); +colors.setBelowColor(HtmlColor.ORANGE); +// sets the filling colors option +dataset.setFillColors(colors); +... +... +// sets the dataset to the chart +chart.getData().setDatasets(dataset); +``` + + diff --git a/versioned_docs/version-6.5/coloring/Gradients.md b/versioned_docs/version-6.5/coloring/Gradients.md new file mode 100644 index 000000000..1ef60a31c --- /dev/null +++ b/versioned_docs/version-6.5/coloring/Gradients.md @@ -0,0 +1,99 @@ +--- +id: Gradients +title: Gradients +hide_title: true +sidebar_label: Gradients +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Gradients + +A gradient is a special type of image that consists of a progressive transition between two or more colors. + + + +The gradient data type is defined with one of the types listed below. + + * **Linear** where transitions colors progressively along an imaginary line. + * **Radial** where transitions colors progressively from a center point (origin). + +As with any interpolation involving colors, gradients are calculated in the alpha-premultiplied color space. This prevents unexpected shades of gray from appearing when both the color and the opacity are changing. + +**Charba** enables the usage of gradient providing some helpful configuration in order to enable you to do not use any dimensions or calculate them. + +The gradient is mapped in the [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html), which can configure both linear and radial gradients. + +A [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) can be created only by a [gradient builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientBuilder.html) in order to optimize the cache used for them. + +```java +// creates a dataset +LineDataset dataset = new LineDataset(); +// creates a gradient +// setting the 2 colors and their offset +Gradient gradient = GradientBuilder.create(GradientType.LINEAR, GradientScope.CHART). + addColorStop(0, HtmlColor.ORANGE).addColorStop(1, HtmlColor.PURPLE).build(); +// sets the gradient as background color of the dataset +dataset.setBackgroundColor(gradient); +// fills the dataset +dataset.setFill(Fill.origin); +``` + +## Types + +Every gradient must be created setting which type represents. The [gradient type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientType.html) must be passed to constructor of new gradient. If omitted, the default is **[linear](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientType.html#LINEAR)**. + +## Orientation + +The **Charba** gradient implementation doesn't provide you to define the imaginary line or the direction from center but provides you a predefined sets of value, which can be used to create the canvas gradient. + +The orientation values of the imaginary line or the direction from/to center are defined in an enumeration, [gradient orientation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientOrientation.html). + +| Name | Type | Description | +| :- | :- | :- | :- | +| TOP_DOWN | LINEAR | From top to bottom (vertical) | | +| BOTTOM_UP | LINEAR | From bottom to to (vertical) | | +| LEFT_RIGHT | LINEAR | From left to right (horizontal) | | +| RIGHT_LEFT | LINEAR | From right to left (horizontal) | | +| TOP_RIGHT | LINEAR | From top(left) to right(bottom) (diagonal) | | +| BOTTOM_LEFT | LINEAR | From bottom(right) to left(top) (diagonal) | | +| TOP_LEFT | LINEAR | From top(right) to left(bottom) (diagonal) | | +| BOTTOM_RIGHT | LINEAR | From bottom(left) to right(top) (diagonal) | | +| IN_OUT | RADIAL | From center to the borders | | +| OUT_IN | RADIAL | From borders to the center | | + +## Scope + +The **Charba** gradient implementation doesn't provide you to define the imaginary line or the direction from center but provides you a predefined sets of value, which can be used to create the canvas gradient. + +The dimension of the area to use to calculate the gradient are defined in an enumeration, [gradient scope](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientScope.html). + +| Name | Description | +| :- | :- | :- | +| CANVAS | Uses the whole dimension of canvas | | +| CHART | Uses the whole dimension of chart | | + +## Adding colors + + + +To complete a gradient configuration, you need to set a list of colors, adds a new color stop to the gradient, setting the offset, as value between 0 and 1 for where the color stop is located, and the color at the stop. + +The [gradient builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GradientBuilder.html) provides the methods to add colors, building the [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html), as following: + +```java +// creates a gradient +// setting the 2 colors and their offset +Gradient gradient = GradientBuilder.create(GradientType.LINEAR, GradientScope.CHART) + .addColorStop(0, HtmlColor.ORANGE) + .addColorStop(0.5, HtmlColor.YELLOW) + .addColorStop(1, HtmlColor.PURPLE).build(); +// creates a gradient +// setting the 2 colors directly +// with offset 0 and 1 +Gradient gradient = GradientBuilder.create(GradientType.RADIAL, GradientScope.CANVAS) + .addColorsStartStop(HtmlColor.ORANGE, HtmlColor.PURPLE).build(); +``` + +## Resizing + +**Charba** recalculates the gradients every time the dimension of chart or canvas occurs. In this way it maintains always the gradients even if the chart has got a different size comparing with it at creation time. diff --git a/versioned_docs/version-6.5/coloring/Patterns.md b/versioned_docs/version-6.5/coloring/Patterns.md new file mode 100644 index 000000000..ab3d7e408 --- /dev/null +++ b/versioned_docs/version-6.5/coloring/Patterns.md @@ -0,0 +1,183 @@ +--- +id: Patterns +title: Patterns +hide_title: true +sidebar_label: Patterns and tiles +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Patterns + +A pattern represents an opaque object, based on an image, that it can be used to fill or stroke properties of a dataset chart. + +Apart of the image, to create a pattern you could decide how to repeat the pattern's image. Possible values are: + + * **[repeat](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/Repetition.html#REPEAT)** (both directions) + * **[repeat-x](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/Repetition.html#REPEAT_X)** (horizontal only) + * **[repeat-y](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/Repetition.html#REPEAT_Y)** (vertical only) + * **[no-repeat](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/Repetition.html#NO_REPEAT)** (neither direction) + +If repetition is not specified creating a pattern, a value of **[repeat](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/Repetition.html#REPEAT)** will be used. + +A pattern is an alternative option to configure a dataset by [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) object, instead of using a color. + + + +A [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) can be created only by a [patter builder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/PatternBuilder.html) in order to optimize the cache used for them. + +For example, if you wanted to fill a dataset with a pattern from an image, you could do the following: + +```java +// creates a dataset +LineDataset dataset = new LineDataset(); +// converts a "ImageResource" in "Img" class +Img img = ImagesHelper.toImg(Images.INSTANCE.pattern()); +// creates a pattern by the image +Pattern pattern = PatternBuilder.create(img).build(); +// sets the pattern as background color of the dataset +dataset.setBackgroundColor(pattern); +// fills the dataset +dataset.setFill(Fill.origin); +``` + +where `Images.INSTANCE.pattern()` is a method of a [ClientBundle](http://www.gwtproject.org/javadoc/latest/com/google/gwt/resources/client/ClientBundle.html), where the image is inside the project and using the [ImagesHelper](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gwt/ImagesHelper.html) can be cast of a [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html), as following: + + +```java +public interface Images extends ClientBundle { + + Images INSTANCE = GWT.create(Images.class); + + @Source("/images/crossline-lines.png") + ImageResource pattern(); +} +``` + +To avoid to have patterns without loaded images, it's suggested to prefetch the images at starting of application, leveraging on GWT [Image](http://www.gwtproject.org/javadoc/latest/com/google/gwt/user/client/ui/Image.html#prefetch-com.google.gwt.safehtml.shared.SafeUri-) as following: + +```java +// loads images +Image.prefetch(Images.INSTANCE.pattern().getSafeUri()); +``` + +## Tiles + +**Charba** provides a tile builders which can easily generate canvas or **Charba** patterns with a set of shapes in order to use them in datasets, instead of colors. + + + +The main class to use this feature is [TilesFactory](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/TilesFactory.html) which provides a set of methods to get a tile as canvas pattern or as **Charba** pattern which can be used in the datasets. + +```java +// creates a dataset +DoughnutDataset dataset = chart.newDataset(); +// creates 4 tiles patterns for each data of the dataset +Pattern p1 = TilesFactory.createPattern(Shape.SQUARE, "#0000FF"); +Pattern p2 = TilesFactory.createPattern(Shape.VERTICAL_ZIGZAG, "#FFFFFF"); +Pattern p3 = TilesFactory.createPattern(Shape.DIAGONAL, "#FF0000"); +Pattern p4 = TilesFactory.createPattern(Shape.RING, "#OOFFOO"); +// sets the patterns as background color fo dataset +dataset.setBackgroundColor(p1, p2, p3, p4); +``` + +The tiles factory can also create canvas patterns to use wherever you want in your application: + +```java +// creates a DOM canvas pattern +CanvasPatternItem canvasPattern = TilesFactory.createTile(Shape.SQUARE, "#0000FF"); +``` + +The tiles factory has got a default configuration which can be updated in order that new configuration can be used for all tiles. + +The complete configuration items are described by following table: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| shape | [Shape](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/Shape.html) | Shape.SQUARE | the shape to apply on tile +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(100, 100, 100, 0.7) -          | the background color of tile +| shapeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(255, 255, 255, 0.8) -          | the shape color on tile +| size | int | 20 | the size of the tile (always a square). The minimum size for a tile is **10**. +| lineCap | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.ROUND | determines the shape used to draw the end points of lines +| lineJoin | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.ROUND | determines the shape used to join two line segments where they meet + +This is the **[list of shapes](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/Shape.html)**, available out-of-the-box: + + * back slashed line + * box + * cross + * cross dash + * dash + * diagonal + * diamond + * diamond box + * disc + * dot + * dot dash + * double diagonal + * empty star + * inverted diagonal + * inverted double diagonal + * inverted triangle + * line + * plus + * ring + * slashed line + * solid + * star + * square + * triangle + * weave + * zigzag + * vertical line + * vertical zigzag + +### Image shape + +[ImageShape](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/ImageShape.html) enables to use an image and apply (scaling it) to the tile. The vantage is that we can decide the background of the image if it has got a transparent background. + +```java +ImageShape imageShape = new ImageShape(ImagesHelper.toImg(Images.INSTANCE.myImage())); +... +Pattern pattern = TilesFactory.createPattern(imageShape, "#990099"); +... +``` + + + +### Character shape + +[CharacterShape](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/CharacterShape.html) enables to use a character (ONLY 1 otherwise you will get an exception) and apply to tile. + +```java +// creates a custom shape +CharacterShape charShape = new CharacterShape("m"); +// creates a tile by the custom shape +Pattern pattern = TilesFactory.createPattern(charShape, "#990099"); +``` + + + +### Point style shape + +It is also possible to use [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) as shape for a tile. + +```java +// creates a shape by a point style +Pattern pattern = TilesFactory.createPattern(PointStyle.CIRCLE, "#990099"); +``` + + + +### Builder + +**Charba** provides a [TilesBuilder](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/tiles/TilesBuilder.html) to create tiles using the **set** methods in sequence and get a [pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) or [CanvasPatternItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/CanvasPatternItem.html) at the end of configuration. + +```java +// creates a CHARBA pattern +Pattern pattern = TilesBuilder.create().setShape(Shape.EMPTY_STAR).setBackgroundColor("#990099").asPattern(); +// creates a canvas pattern +CanvasPatternItem canvasPattern = TilesBuilder.create() + .setShape(Shape.EMPTY_STAR) + .setBackgroundColor("#990099") + .asTile(); +``` diff --git a/versioned_docs/version-6.5/coloring/tables/GWTMaterialColors.md b/versioned_docs/version-6.5/coloring/tables/GWTMaterialColors.md new file mode 100644 index 000000000..fa477aad4 --- /dev/null +++ b/versioned_docs/version-6.5/coloring/tables/GWTMaterialColors.md @@ -0,0 +1,277 @@ +--- +id: GWTMaterialColors +title: GWT Material color table +hide_title: true +sidebar_label: GWT Material +--- +## GWT Material color table + +The GWT Material colors are provided by an enumeration, [GwtMaterialColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GwtMaterialColor.html). + +Here an example how to use it: + +```java +// sets default color +Defaults.get().getGlobal().setColor(GwtMaterialColor.RED); +``` + +| Name | Hex | RGB | Color | +| :--- | :--- | :--- | :---- | +| AMBER | #ffc107 | rgb(255,193,7) |                   | +| AMBER_ACCENT_1 | #ffe57f | rgb(255,229,127) |                   | +| AMBER_ACCENT_2 | #ffd740 | rgb(255,215,64) |                   | +| AMBER_ACCENT_3 | #ffc400 | rgb(255,196,0) |                   | +| AMBER_ACCENT_4 | #ffab00 | rgb(255,171,0) |                   | +| AMBER_DARKEN_1 | #ffb300 | rgb(255,179,0) |                   | +| AMBER_DARKEN_2 | #ffa000 | rgb(255,160,0) |                   | +| AMBER_DARKEN_3 | #ff8f00 | rgb(255,143,0) |                   | +| AMBER_DARKEN_4 | #ff6f00 | rgb(255,111,0) |                   | +| AMBER_LIGHTEN_1 | #ffca28 | rgb(255,202,40) |                   | +| AMBER_LIGHTEN_2 | #ffd54f | rgb(255,213,79) |                   | +| AMBER_LIGHTEN_3 | #ffe082 | rgb(255,224,130) |                   | +| AMBER_LIGHTEN_4 | #ffecb3 | rgb(255,236,179) |                   | +| AMBER_LIGHTEN_5 | #fff8e1 | rgb(255,248,225) |                   | +| BLACK | #000000 | rgb(0,0,0) |                   | +| BLUE | #2196f3 | rgb(33,150,243) |                   | +| BLUE_ACCENT_1 | #82b1ff | rgb(130,177,255) |                   | +| BLUE_ACCENT_2 | #448aff | rgb(68,138,255) |                   | +| BLUE_ACCENT_3 | #2979ff | rgb(41,121,255) |                   | +| BLUE_ACCENT_4 | #2962ff | rgb(41,98,255) |                   | +| BLUE_DARKEN_1 | #1e88e5 | rgb(30,136,229) |                   | +| BLUE_DARKEN_2 | #1976d2 | rgb(25,118,210) |                   | +| BLUE_DARKEN_3 | #1565c0 | rgb(21,101,192) |                   | +| BLUE_DARKEN_4 | #0d47a1 | rgb(13,71,161) |                   | +| BLUE_GREY | #607d8b | rgb(96,125,139) |                   | +| BLUE_GREY_DARKEN_1 | #546e7a | rgb(84,110,122) |                   | +| BLUE_GREY_DARKEN_2 | #455a64 | rgb(69,90,100) |                   | +| BLUE_GREY_DARKEN_3 | #37474f | rgb(55,71,79) |                   | +| BLUE_GREY_DARKEN_4 | #263238 | rgb(38,50,56) |                   | +| BLUE_GREY_LIGHTEN_1 | #78909c | rgb(120,144,156) |                   | +| BLUE_GREY_LIGHTEN_2 | #90a4ae | rgb(144,164,174) |                   | +| BLUE_GREY_LIGHTEN_3 | #b0bec5 | rgb(176,190,197) |                   | +| BLUE_GREY_LIGHTEN_4 | #cfd8dc | rgb(207,216,220) |                   | +| BLUE_GREY_LIGHTEN_5 | #eceff1 | rgb(236,239,241) |                   | +| BLUE_LIGHTEN_1 | #42a5f5 | rgb(66,165,245) |                   | +| BLUE_LIGHTEN_2 | #64b5f6 | rgb(100,181,246) |                   | +| BLUE_LIGHTEN_3 | #90caf9 | rgb(144,202,249) |                   | +| BLUE_LIGHTEN_4 | #bbdefb | rgb(187,222,251) |                   | +| BLUE_LIGHTEN_5 | #e3f2fd | rgb(227,242,253) |                   | +| BROWN | #795548 | rgb(121,85,72) |                   | +| BROWN_DARKEN_1 | #6d4c41 | rgb(109,76,65) |                   | +| BROWN_DARKEN_2 | #5d4037 | rgb(93,64,55) |                   | +| BROWN_DARKEN_3 | #4e342e | rgb(78,52,46) |                   | +| BROWN_DARKEN_4 | #3e2723 | rgb(62,39,35) |                   | +| BROWN_LIGHTEN_1 | #8d6e63 | rgb(141,110,99) |                   | +| BROWN_LIGHTEN_2 | #a1887f | rgb(161,136,127) |                   | +| BROWN_LIGHTEN_3 | #bcaaa4 | rgb(188,170,164) |                   | +| BROWN_LIGHTEN_4 | #d7ccc8 | rgb(215,204,200) |                   | +| BROWN_LIGHTEN_5 | #efebe9 | rgb(239,235,233) |                   | +| CYAN | #00bcd4 | rgb(0,188,212) |                   | +| CYAN_ACCENT_1 | #84ffff | rgb(132,255,255) |                   | +| CYAN_ACCENT_2 | #18ffff | rgb(24,255,255) |                   | +| CYAN_ACCENT_3 | #00e5ff | rgb(0,229,255) |                   | +| CYAN_ACCENT_4 | #00b8d4 | rgb(0,184,212) |                   | +| CYAN_DARKEN_1 | #00acc1 | rgb(0,172,193) |                   | +| CYAN_DARKEN_2 | #0097a7 | rgb(0,151,167) |                   | +| CYAN_DARKEN_3 | #00838f | rgb(0,131,143) |                   | +| CYAN_DARKEN_4 | #006064 | rgb(0,96,100) |                   | +| CYAN_LIGHTEN_1 | #26c6da | rgb(38,198,218) |                   | +| CYAN_LIGHTEN_2 | #4dd0e1 | rgb(77,208,225) |                   | +| CYAN_LIGHTEN_3 | #80deea | rgb(128,222,234) |                   | +| CYAN_LIGHTEN_4 | #b2ebf2 | rgb(178,235,242) |                   | +| CYAN_LIGHTEN_5 | #e0f7fa | rgb(224,247,250) |                   | +| DEEP_ORANGE | #ff5722 | rgb(255,87,34) |                   | +| DEEP_ORANGE_ACCENT_1 | #ff9e80 | rgb(255,158,128) |                   | +| DEEP_ORANGE_ACCENT_2 | #ff6e40 | rgb(255,110,64) |                   | +| DEEP_ORANGE_ACCENT_3 | #ff3d00 | rgb(255,61,0) |                   | +| DEEP_ORANGE_ACCENT_4 | #dd2c00 | rgb(221,44,0) |                   | +| DEEP_ORANGE_DARKEN_1 | #f4511e | rgb(244,81,30) |                   | +| DEEP_ORANGE_DARKEN_2 | #e64a19 | rgb(230,74,25) |                   | +| DEEP_ORANGE_DARKEN_3 | #d84315 | rgb(216,67,21) |                   | +| DEEP_ORANGE_DARKEN_4 | #bf360c | rgb(191,54,12) |                   | +| DEEP_ORANGE_LIGHTEN_1 | #ff7043 | rgb(255,112,67) |                   | +| DEEP_ORANGE_LIGHTEN_2 | #ff8a65 | rgb(255,138,101) |                   | +| DEEP_ORANGE_LIGHTEN_3 | #ffab91 | rgb(255,171,145) |                   | +| DEEP_ORANGE_LIGHTEN_4 | #ffccbc | rgb(255,204,188) |                   | +| DEEP_ORANGE_LIGHTEN_5 | #fbe9e7 | rgb(251,233,231) |                   | +| DEEP_PURPLE | #673ab7 | rgb(103,58,183) |                   | +| DEEP_PURPLE_ACCENT_1 | #b388ff | rgb(179,136,255) |                   | +| DEEP_PURPLE_ACCENT_2 | #7c4dff | rgb(124,77,255) |                   | +| DEEP_PURPLE_ACCENT_3 | #651fff | rgb(101,31,255) |                   | +| DEEP_PURPLE_ACCENT_4 | #6200ea | rgb(98,0,234) |                   | +| DEEP_PURPLE_DARKEN_1 | #5e35b1 | rgb(94,53,177) |                   | +| DEEP_PURPLE_DARKEN_2 | #512da8 | rgb(81,45,168) |                   | +| DEEP_PURPLE_DARKEN_3 | #4527a0 | rgb(69,39,160) |                   | +| DEEP_PURPLE_DARKEN_4 | #311b92 | rgb(49,27,146) |                   | +| DEEP_PURPLE_LIGHTEN_1 | #7e57c2 | rgb(126,87,194) |                   | +| DEEP_PURPLE_LIGHTEN_2 | #9575cd | rgb(149,117,205) |                   | +| DEEP_PURPLE_LIGHTEN_3 | #b39ddb | rgb(179,157,219) |                   | +| DEEP_PURPLE_LIGHTEN_4 | #d1c4e9 | rgb(209,196,233) |                   | +| DEEP_PURPLE_LIGHTEN_5 | #ede7f6 | rgb(237,231,246) |                   | +| GREEN | #4caf50 | rgb(76,175,80) |                   | +| GREEN_ACCENT_1 | #b9f6ca | rgb(185,246,202) |                   | +| GREEN_ACCENT_2 | #69f0ae | rgb(105,240,174) |                   | +| GREEN_ACCENT_3 | #00e676 | rgb(0,230,118) |                   | +| GREEN_ACCENT_4 | #00c853 | rgb(0,200,83) |                   | +| GREEN_DARKEN_1 | #43a047 | rgb(67,160,71) |                   | +| GREEN_DARKEN_2 | #388e3c | rgb(56,142,60) |                   | +| GREEN_DARKEN_3 | #2e7d32 | rgb(46,125,50) |                   | +| GREEN_DARKEN_4 | #1b5e20 | rgb(27,94,32) |                   | +| GREEN_LIGHTEN_1 | #66bb6a | rgb(102,187,106) |                   | +| GREEN_LIGHTEN_2 | #81c784 | rgb(129,199,132) |                   | +| GREEN_LIGHTEN_3 | #a5d6a7 | rgb(165,214,167) |                   | +| GREEN_LIGHTEN_4 | #c8e6c9 | rgb(200,230,201) |                   | +| GREEN_LIGHTEN_5 | #e8f5e9 | rgb(232,245,233) |                   | +| GREY | #9e9e9e | rgb(158,158,158) |                   | +| GREY_DARKEN_1 | #757575 | rgb(117,117,117) |                   | +| GREY_DARKEN_2 | #616161 | rgb(97,97,97) |                   | +| GREY_DARKEN_3 | #424242 | rgb(66,66,66) |                   | +| GREY_DARKEN_4 | #212121 | rgb(33,33,33) |                   | +| GREY_LIGHTEN_1 | #bdbdbd | rgb(189,189,189) |                   | +| GREY_LIGHTEN_2 | #e0e0e0 | rgb(224,224,224) |                   | +| GREY_LIGHTEN_3 | #eeeeee | rgb(238,238,238) |                   | +| GREY_LIGHTEN_4 | #f5f5f5 | rgb(245,245,245) |                   | +| GREY_LIGHTEN_5 | #fafafa | rgb(250,250,250) |                   | +| INDIGO | #3f51b5 | rgb(63,81,181) |                   | +| INDIGO_ACCENT_1 | #8c9eff | rgb(140,158,255) |                   | +| INDIGO_ACCENT_2 | #536dfe | rgb(83,109,254) |                   | +| INDIGO_ACCENT_3 | #3d5afe | rgb(61,90,254) |                   | +| INDIGO_ACCENT_4 | #304ffe | rgb(48,79,254) |                   | +| INDIGO_DARKEN_1 | #3949ab | rgb(57,73,171) |                   | +| INDIGO_DARKEN_2 | #303f9f | rgb(48,63,159) |                   | +| INDIGO_DARKEN_3 | #283593 | rgb(40,53,147) |                   | +| INDIGO_DARKEN_4 | #1a237e | rgb(26,35,126) |                   | +| INDIGO_LIGHTEN_1 | #5c6bc0 | rgb(92,107,192) |                   | +| INDIGO_LIGHTEN_2 | #7986cb | rgb(121,134,203) |                   | +| INDIGO_LIGHTEN_3 | #9fa8da | rgb(159,168,218) |                   | +| INDIGO_LIGHTEN_4 | #c5cae9 | rgb(197,202,233) |                   | +| INDIGO_LIGHTEN_5 | #e8eaf6 | rgb(232,234,246) |                   | +| LIGHT_BLUE | #03a9f4 | rgb(3,169,244) |                   | +| LIGHT_BLUE_ACCENT_1 | #80d8ff | rgb(128,216,255) |                   | +| LIGHT_BLUE_ACCENT_2 | #40c4ff | rgb(64,196,255) |                   | +| LIGHT_BLUE_ACCENT_3 | #00b0ff | rgb(0,176,255) |                   | +| LIGHT_BLUE_ACCENT_4 | #0091ea | rgb(0,145,234) |                   | +| LIGHT_BLUE_DARKEN_1 | #039be5 | rgb(3,155,229) |                   | +| LIGHT_BLUE_DARKEN_2 | #0288d1 | rgb(2,136,209) |                   | +| LIGHT_BLUE_DARKEN_3 | #0277bd | rgb(2,119,189) |                   | +| LIGHT_BLUE_DARKEN_4 | #01579b | rgb(1,87,155) |                   | +| LIGHT_BLUE_LIGHTEN_1 | #29b6f6 | rgb(41,182,246) |                   | +| LIGHT_BLUE_LIGHTEN_2 | #4fc3f7 | rgb(79,195,247) |                   | +| LIGHT_BLUE_LIGHTEN_3 | #81d4fa | rgb(129,212,250) |                   | +| LIGHT_BLUE_LIGHTEN_4 | #b3e5fc | rgb(179,229,252) |                   | +| LIGHT_BLUE_LIGHTEN_5 | #e1f5fe | rgb(225,245,254) |                   | +| LIGHT_GREEN | #8bc34a | rgb(139,195,74) |                   | +| LIGHT_GREEN_ACCENT_1 | #ccff90 | rgb(204,255,144) |                   | +| LIGHT_GREEN_ACCENT_2 | #b2ff59 | rgb(178,255,89) |                   | +| LIGHT_GREEN_ACCENT_3 | #76ff03 | rgb(118,255,3) |                   | +| LIGHT_GREEN_ACCENT_4 | #64dd17 | rgb(100,221,23) |                   | +| LIGHT_GREEN_DARKEN_1 | #7cb342 | rgb(124,179,66) |                   | +| LIGHT_GREEN_DARKEN_2 | #689f38 | rgb(104,159,56) |                   | +| LIGHT_GREEN_DARKEN_3 | #558b2f | rgb(85,139,47) |                   | +| LIGHT_GREEN_DARKEN_4 | #33691e | rgb(51,105,30) |                   | +| LIGHT_GREEN_LIGHTEN_1 | #9ccc65 | rgb(156,204,101) |                   | +| LIGHT_GREEN_LIGHTEN_2 | #aed581 | rgb(174,213,129) |                   | +| LIGHT_GREEN_LIGHTEN_3 | #c5e1a5 | rgb(197,225,165) |                   | +| LIGHT_GREEN_LIGHTEN_4 | #dcedc8 | rgb(220,237,200) |                   | +| LIGHT_GREEN_LIGHTEN_5 | #f1f8e9 | rgb(241,248,233) |                   | +| LIME | #cddc39 | rgb(205,220,57) |                   | +| LIME_ACCENT_1 | #f4ff81 | rgb(244,255,129) |                   | +| LIME_ACCENT_2 | #eeff41 | rgb(238,255,65) |                   | +| LIME_ACCENT_3 | #c6ff00 | rgb(198,255,0) |                   | +| LIME_ACCENT_4 | #aeea00 | rgb(174,234,0) |                   | +| LIME_DARKEN_1 | #c0ca33 | rgb(192,202,51) |                   | +| LIME_DARKEN_2 | #afb42b | rgb(175,180,43) |                   | +| LIME_DARKEN_3 | #9e9d24 | rgb(158,157,36) |                   | +| LIME_DARKEN_4 | #827717 | rgb(130,119,23) |                   | +| LIME_LIGHTEN_1 | #d4e157 | rgb(212,225,87) |                   | +| LIME_LIGHTEN_2 | #dce775 | rgb(220,231,117) |                   | +| LIME_LIGHTEN_3 | #e6ee9c | rgb(230,238,156) |                   | +| LIME_LIGHTEN_4 | #f0f4c3 | rgb(240,244,195) |                   | +| LIME_LIGHTEN_5 | #f9fbe7 | rgb(249,251,231) |                   | +| ORANGE | #ff9800 | rgb(255,152,0) |                   | +| ORANGE_ACCENT_1 | #ffd180 | rgb(255,209,128) |                   | +| ORANGE_ACCENT_2 | #ffab40 | rgb(255,171,64) |                   | +| ORANGE_ACCENT_3 | #ff9100 | rgb(255,145,0) |                   | +| ORANGE_ACCENT_4 | #ff6d00 | rgb(255,109,0) |                   | +| ORANGE_DARKEN_1 | #fb8c00 | rgb(251,140,0) |                   | +| ORANGE_DARKEN_2 | #f57c00 | rgb(245,124,0) |                   | +| ORANGE_DARKEN_3 | #ef6c00 | rgb(239,108,0) |                   | +| ORANGE_DARKEN_4 | #e65100 | rgb(230,81,0) |                   | +| ORANGE_LIGHTEN_1 | #ffa726 | rgb(255,167,38) |                   | +| ORANGE_LIGHTEN_2 | #ffb74d | rgb(255,183,77) |                   | +| ORANGE_LIGHTEN_3 | #ffcc80 | rgb(255,204,128) |                   | +| ORANGE_LIGHTEN_4 | #ffe0b2 | rgb(255,224,178) |                   | +| ORANGE_LIGHTEN_5 | #fff3e0 | rgb(255,243,224) |                   | +| PINK | #e91e63 | rgb(233,30,99) |                   | +| PINK_ACCENT_1 | #ff80ab | rgb(255,128,171) |                   | +| PINK_ACCENT_2 | #ff4081 | rgb(255,64,129) |                   | +| PINK_ACCENT_3 | #f50057 | rgb(245,0,87) |                   | +| PINK_ACCENT_4 | #c51162 | rgb(197,17,98) |                   | +| PINK_DARKEN_1 | #d81b60 | rgb(216,27,96) |                   | +| PINK_DARKEN_2 | #c2185b | rgb(194,24,91) |                   | +| PINK_DARKEN_3 | #ad1457 | rgb(173,20,87) |                   | +| PINK_DARKEN_4 | #880e4f | rgb(136,14,79) |                   | +| PINK_LIGHTEN_1 | #ec407a | rgb(236,64,122) |                   | +| PINK_LIGHTEN_2 | #f06292 | rgb(240,98,146) |                   | +| PINK_LIGHTEN_3 | #f48fb1 | rgb(244,143,177) |                   | +| PINK_LIGHTEN_4 | #f8bbd0 | rgb(248,187,208) |                   | +| PINK_LIGHTEN_5 | #fce4ec | rgb(252,228,236) |                   | +| PURPLE | #9c27b0 | rgb(156,39,176) |                   | +| PURPLE_ACCENT_1 | #ea80fc | rgb(234,128,252) |                   | +| PURPLE_ACCENT_2 | #e040fb | rgb(224,64,251) |                   | +| PURPLE_ACCENT_3 | #d500f9 | rgb(213,0,249) |                   | +| PURPLE_ACCENT_4 | #aa00ff | rgb(170,0,255) |                   | +| PURPLE_DARKEN_1 | #8e24aa | rgb(142,36,170) |                   | +| PURPLE_DARKEN_2 | #7b1fa2 | rgb(123,31,162) |                   | +| PURPLE_DARKEN_3 | #6a1b9a | rgb(106,27,154) |                   | +| PURPLE_DARKEN_4 | #4a148c | rgb(74,20,140) |                   | +| PURPLE_LIGHTEN_1 | #ab47bc | rgb(171,71,188) |                   | +| PURPLE_LIGHTEN_2 | #ba68c8 | rgb(186,104,200) |                   | +| PURPLE_LIGHTEN_3 | #ce93d8 | rgb(206,147,216) |                   | +| PURPLE_LIGHTEN_4 | #e1bee7 | rgb(225,190,231) |                   | +| PURPLE_LIGHTEN_5 | #f3e5f5 | rgb(243,229,245) |                   | +| RED | #f44336 | rgb(244,67,54) |                   | +| RED_ACCENT_1 | #ff8a80 | rgb(255,138,128) |                   | +| RED_ACCENT_2 | #ff5252 | rgb(255,82,82) |                   | +| RED_ACCENT_3 | #ff1744 | rgb(255,23,68) |                   | +| RED_ACCENT_4 | #d50000 | rgb(213,0,0) |                   | +| RED_DARKEN_1 | #e53935 | rgb(229,57,53) |                   | +| RED_DARKEN_2 | #d32f2f | rgb(211,47,47) |                   | +| RED_DARKEN_3 | #c62828 | rgb(198,40,40) |                   | +| RED_DARKEN_4 | #b71c1c | rgb(183,28,28) |                   | +| RED_LIGHTEN_1 | #ef5350 | rgb(239,83,80) |                   | +| RED_LIGHTEN_2 | #e57373 | rgb(229,115,115) |                   | +| RED_LIGHTEN_3 | #ef9a9a | rgb(239,154,154) |                   | +| RED_LIGHTEN_4 | #ffcdd2 | rgb(255,205,210) |                   | +| RED_LIGHTEN_5 | #ffebee | rgb(255,235,238) |                   | +| TEAL | #009688 | rgb(0,150,136) |                   | +| TEAL_ACCENT_1 | #a7ffeb | rgb(167,255,235) |                   | +| TEAL_ACCENT_2 | #64ffda | rgb(100,255,218) |                   | +| TEAL_ACCENT_3 | #1de9b6 | rgb(29,233,182) |                   | +| TEAL_ACCENT_4 | #00bfa5 | rgb(0,191,165) |                   | +| TEAL_DARKEN_1 | #00897b | rgb(0,137,123) |                   | +| TEAL_DARKEN_2 | #00796b | rgb(0,121,107) |                   | +| TEAL_DARKEN_3 | #00695c | rgb(0,105,92) |                   | +| TEAL_DARKEN_4 | #004d40 | rgb(0,77,64) |                   | +| TEAL_LIGHTEN_1 | #26a69a | rgb(38,166,154) |                   | +| TEAL_LIGHTEN_2 | #4db6ac | rgb(77,182,172) |                   | +| TEAL_LIGHTEN_3 | #80cbc4 | rgb(128,203,196) |                   | +| TEAL_LIGHTEN_4 | #b2dfdb | rgb(178,223,219) |                   | +| TEAL_LIGHTEN_5 | #e0f2f1 | rgb(224,242,241) |                   | +| WHITE | #ffffff | rgb(255,255,255) |                   | +| YELLOW | #ffeb3b | rgb(255,235,59) |                   | +| YELLOW_ACCENT_1 | #ffff8d | rgb(255,255,141) |                   | +| YELLOW_ACCENT_2 | #ffff00 | rgb(255,255,0) |                   | +| YELLOW_ACCENT_3 | #ffea00 | rgb(255,234,0) |                   | +| YELLOW_ACCENT_4 | #ffd600 | rgb(255,214,0) |                   | +| YELLOW_DARKEN_1 | #fdd835 | rgb(253,216,53) |                   | +| YELLOW_DARKEN_2 | #fbc02d | rgb(251,192,45) |                   | +| YELLOW_DARKEN_3 | #f9a825 | rgb(249,168,37) |                   | +| YELLOW_DARKEN_4 | #f57f17 | rgb(245,127,23) |                   | +| YELLOW_LIGHTEN_1 | #ffee58 | rgb(255,238,88) |                   | +| YELLOW_LIGHTEN_2 | #fff176 | rgb(255,241,118) |                   | +| YELLOW_LIGHTEN_3 | #fff59d | rgb(255,245,157) |                   | +| YELLOW_LIGHTEN_4 | #fff9c4 | rgb(255,249,196) |                   | +| YELLOW_LIGHTEN_5 | #fffde7 | rgb(255,253,231) |                   | + + diff --git a/versioned_docs/version-6.5/coloring/tables/GoogleChartColors.md b/versioned_docs/version-6.5/coloring/tables/GoogleChartColors.md new file mode 100644 index 000000000..169b2bd33 --- /dev/null +++ b/versioned_docs/version-6.5/coloring/tables/GoogleChartColors.md @@ -0,0 +1,51 @@ +--- +id: GoogleChartColors +title: Google Chart color table +hide_title: true +sidebar_label: Google Chart +--- + +## Google Chart color table + +The Google Chart colors are provided by an enumeration, [GoogleChartColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/GoogleChartColor.html). + +Here an example how to use it: + +```java +// sets default color +Defaults.get().getGlobal().setColor(GoogleChartColor.COLOR_00); +``` + +| Name | Hex | RGB | Color | +| :--- | :--- | :--- | :---- | +| COLOR_00 | #3366cc | rgb(51,102,204) |                   | +| COLOR_01 | #dc3912 | rgb(220,57,18) |                   | +| COLOR_02 | #ff9900 | rgb(255,153,0) |                   | +| COLOR_03 | #109618 | rgb(16,150,24) |                   | +| COLOR_04 | #990099 | rgb(153,0,153) |                   | +| COLOR_05 | #0099c6 | rgb(0,153,198) |                   | +| COLOR_06 | #dd4477 | rgb(221,68,119) |                   | +| COLOR_07 | #66aa00 | rgb(102,170,0) |                   | +| COLOR_08 | #b82e2e | rgb(184,46,46) |                   | +| COLOR_09 | #316395 | rgb(49,99,149) |                   | +| COLOR_10 | #994499 | rgb(153,68,153) |                   | +| COLOR_11 | #22aa99 | rgb(34,170,153) |                   | +| COLOR_12 | #aaaa11 | rgb(170,170,17) |                   | +| COLOR_13 | #6633cc | rgb(102,51,204) |                   | +| COLOR_14 | #e67300 | rgb(230,115,0) |                   | +| COLOR_15 | #8b0707 | rgb(139,7,7) |                   | +| COLOR_16 | #651067 | rgb(101,16,103) |                   | +| COLOR_17 | #329262 | rgb(50,146,98) |                   | +| COLOR_18 | #5574a6 | rgb(85,116,166) |                   | +| COLOR_19 | #3b3eac | rgb(59,62,172) |                   | +| COLOR_20 | #b77322 | rgb(183,115,34) |                   | +| COLOR_21 | #16d620 | rgb(22,214,32) |                   | +| COLOR_22 | #b91383 | rgb(185,19,131) |                   | +| COLOR_23 | #f4359e | rgb(244,53,158) |                   | +| COLOR_24 | #9c5935 | rgb(156,89,53) |                   | +| COLOR_25 | #a9c413 | rgb(169,196,19) |                   | +| COLOR_26 | #2a778d | rgb(42,119,141) |                   | +| COLOR_27 | #668d1c | rgb(102,141,28) |                   | +| COLOR_28 | #bea413 | rgb(190,164,19) |                   | +| COLOR_29 | #0c5922 | rgb(12,89,34) |                   | +| COLOR_30 | #743411 | rgb(116,52,17) |                   | diff --git a/versioned_docs/version-6.5/coloring/tables/HTMLColorsNames.md b/versioned_docs/version-6.5/coloring/tables/HTMLColorsNames.md new file mode 100644 index 000000000..1bf0ed312 --- /dev/null +++ b/versioned_docs/version-6.5/coloring/tables/HTMLColorsNames.md @@ -0,0 +1,168 @@ +--- +id: HTMLColorsNames +title: HTML color names table +hide_title: true +sidebar_label: HTML color names +--- +## HTML color names table + +The HTML color names are provided by an enumeration, [HtmlColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/HtmlColor.html). + +Here an example how to use it: + +```java +// sets default color +Defaults.get().getGlobal().setColor(HtmlColor.WHITE); +``` + +| Name | Hex | RGB | Color | +| :--- | :--- | :--- | :---- | +| ALICE_BLUE | #f0f8ff | rgb(240,248,255) |                   | +| ANTIQUE_WHITE | #faebd7 | rgb(250,235,215) |                   | +| AQUA | #00ffff | rgb(0,255,255) |                   | +| AQUAMARINE | #7fffd4 | rgb(127,255,212) |                   | +| AZURE | #f0ffff | rgb(240,255,255) |                   | +| BEIGE | #f5f5dc | rgb(245,245,220) |                   | +| BISQUE | #ffe4c4 | rgb(255,228,196) |                   | +| BLACK | #000000 | rgb(0,0,0) |                   | +| BLANCHED_ALMOND | #ffebcd | rgb(255,235,205) |                   | +| BLUE | #0000ff | rgb(0,0,255) |                   | +| BLUE_VIOLET | #8a2be2 | rgb(138,43,226) |                   | +| BROWN | #a52a2a | rgb(165,42,42) |                   | +| BURLY_WOOD | #deb887 | rgb(222,184,135) |                   | +| CADET_BLUE | #5f9ea0 | rgb(95,158,160) |                   | +| CHARTREUSE | #7fff00 | rgb(127,255,0) |                   | +| CHOCOLATE | #d2691e | rgb(210,105,30) |                   | +| CORAL | #ff7f50 | rgb(255,127,80) |                   | +| CORNFLOWER_BLUE | #6495ed | rgb(100,149,237) |                   | +| CORNSILK | #fff8dc | rgb(255,248,220) |                   | +| CRIMSON | #dc143c | rgb(220,20,60) |                   | +| CYAN | #00ffff | rgb(0,255,255) |                   | +| DARK_BLUE | #00008b | rgb(0,0,139) |                   | +| DARK_CYAN | #008b8b | rgb(0,139,139) |                   | +| DARK_GOLDEN_ROD | #b8860b | rgb(184,134,11) |                   | +| DARK_GRAY | #a9a9a9 | rgb(169,169,169) |                   | +| DARK_GREEN | #006400 | rgb(0,100,0) |                   | +| DARK_GREY | #a9a9a9 | rgb(169,169,169) |                   | +| DARK_KHAKI | #bdb76b | rgb(189,183,107) |                   | +| DARK_MAGENTA | #8b008b | rgb(139,0,139) |                   | +| DARK_OLIVE_GREEN | #556b2f | rgb(85,107,47) |                   | +| DARK_ORANGE | #ff8c00 | rgb(255,140,0) |                   | +| DARK_ORCHID | #9932cc | rgb(153,50,204) |                   | +| DARK_RED | #8b0000 | rgb(139,0,0) |                   | +| DARK_SALMON | #e9967a | rgb(233,150,122) |                   | +| DARK_SEA_GREEN | #8fbc8f | rgb(143,188,143) |                   | +| DARK_SLATE_BLUE | #483d8b | rgb(72,61,139) |                   | +| DARK_SLATE_GRAY | #2f4f4f | rgb(47,79,79) |                   | +| DARK_SLATE_GREY | #2f4f4f | rgb(47,79,79) |                   | +| DARK_TURQUOISE | #00ced1 | rgb(0,206,209) |                   | +| DARK_VIOLET | #9400d3 | rgb(148,0,211) |                   | +| DEEP_PINK | #ff1493 | rgb(255,20,147) |                   | +| DEEP_SKY_BLUE | #00bfff | rgb(0,191,255) |                   | +| DIM_GRAY | #696969 | rgb(105,105,105) |                   | +| DIM_GREY | #696969 | rgb(105,105,105) |                   | +| DODGER_BLUE | #1e90ff | rgb(30,144,255) |                   | +| FIRE_BRICK | #b22222 | rgb(178,34,34) |                   | +| FLORAL_WHITE | #fffaf0 | rgb(255,250,240) |                   | +| FOREST_GREEN | #228b22 | rgb(34,139,34) |                   | +| FUCHSIA | #ff00ff | rgb(255,0,255) |                   | +| GAINSBORO | #dcdcdc | rgb(220,220,220) |                   | +| GHOST_WHITE | #f8f8ff | rgb(248,248,255) |                   | +| GOLD | #ffd700 | rgb(255,215,0) |                   | +| GOLDEN_ROD | #daa520 | rgb(218,165,32) |                   | +| GRAY | #808080 | rgb(128,128,128) |                   | +| GREEN | #008000 | rgb(0,128,0) |                   | +| GREEN_YELLOW | #adff2f | rgb(173,255,47) |                   | +| GREY | #808080 | rgb(128,128,128) |                   | +| HONEY_DEW | #f0fff0 | rgb(240,255,240) |                   | +| HOT_PINK | #ff69b4 | rgb(255,105,180) |                   | +| INDIAN_RED | #cd5c5c | rgb(205,92,92) |                   | +| INDIGO | #4b0082 | rgb(75,0,130) |                   | +| IVORY | #fffff0 | rgb(255,255,240) |                   | +| KHAKI | #f0e68c | rgb(240,230,140) |                   | +| LAVENDER | #e6e6fa | rgb(230,230,250) |                   | +| LAVENDER_BLUSH | #fff0f5 | rgb(255,240,245) |                   | +| LAWN_GREEN | #7cfc00 | rgb(124,252,0) |                   | +| LEMON_CHIFFON | #fffacd | rgb(255,250,205) |                   | +| LIGHT_BLUE | #add8e6 | rgb(173,216,230) |                   | +| LIGHT_CORAL | #f08080 | rgb(240,128,128) |                   | +| LIGHT_CYAN | #e0ffff | rgb(224,255,255) |                   | +| LIGHT_GOLDEN_ROD_YELLOW | #fafad2 | rgb(250,250,210) |                   | +| LIGHT_GRAY | #d3d3d3 | rgb(211,211,211) |                   | +| LIGHT_GREEN | #90ee90 | rgb(144,238,144) |                   | +| LIGHT_GREY | #d3d3d3 | rgb(211,211,211) |                   | +| LIGHT_PINK | #ffb6c1 | rgb(255,182,193) |                   | +| LIGHT_SALMON | #ffa07a | rgb(255,160,122) |                   | +| LIGHT_SEA_GREEN | #20b2aa | rgb(32,178,170) |                   | +| LIGHT_SKY_BLUE | #87cefa | rgb(135,206,250) |                   | +| LIGHT_SLATE_GRAY | #778899 | rgb(119,136,153) |                   | +| LIGHT_SLATE_GREY | #778899 | rgb(119,136,153) |                   | +| LIGHT_STEEL_BLUE | #b0c4de | rgb(176,196,222) |                   | +| LIGHT_YELLOW | #ffffe0 | rgb(255,255,224) |                   | +| LIME | #00ff00 | rgb(0,255,0) |                   | +| LIME_GREEN | #32cd32 | rgb(50,205,50) |                   | +| LINEN | #faf0e6 | rgb(250,240,230) |                   | +| MAGENTA | #ff00ff | rgb(255,0,255) |                   | +| MAROON | #800000 | rgb(128,0,0) |                   | +| MEDIUM_AQUA_MARINE | #66cdaa | rgb(102,205,170) |                   | +| MEDIUM_BLUE | #0000cd | rgb(0,0,205) |                   | +| MEDIUM_ORCHID | #ba55d3 | rgb(186,85,211) |                   | +| MEDIUM_PURPLE | #9370db | rgb(147,112,219) |                   | +| MEDIUM_SEA_GREEN | #3cb371 | rgb(60,179,113) |                   | +| MEDIUM_SLATE_BLUE | #7b68ee | rgb(123,104,238) |                   | +| MEDIUM_SPRING_GREEN | #00fa9a | rgb(0,250,154) |                   | +| MEDIUM_TURQUOISE | #48d1cc | rgb(72,209,204) |                   | +| MEDIUM_VIOLET_RED | #c71585 | rgb(199,21,133) |                   | +| MIDNIGHT_BLUE | #191970 | rgb(25,25,112) |                   | +| MINT_CREAM | #f5fffa | rgb(245,255,250) |                   | +| MISTY_ROSE | #ffe4e1 | rgb(255,228,225) |                   | +| MOCCASIN | #ffe4b5 | rgb(255,228,181) |                   | +| NAVAJO_WHITE | #ffdead | rgb(255,222,173) |                   | +| NAVY | #000080 | rgb(0,0,128) |                   | +| OLD_LACE | #fdf5e6 | rgb(253,245,230) |                   | +| OLIVE | #808000 | rgb(128,128,0) |                   | +| OLIVE_DRAB | #6b8e23 | rgb(107,142,35) |                   | +| ORANGE | #ffa500 | rgb(255,165,0) |                   | +| ORANGE_RED | #ff4500 | rgb(255,69,0) |                   | +| ORCHID | #da70d6 | rgb(218,112,214) |                   | +| PALE_GOLDEN_ROD | #eee8aa | rgb(238,232,170) |                   | +| PALE_GREEN | #98fb98 | rgb(152,251,152) |                   | +| PALE_TURQUOISE | #afeeee | rgb(175,238,238) |                   | +| PALE_VIOLET_RED | #db7093 | rgb(219,112,147) |                   | +| PAPAYA_WHIP | #ffefd5 | rgb(255,239,213) |                   | +| PEACH_PUFF | #ffdab9 | rgb(255,218,185) |                   | +| PERU | #cd853f | rgb(205,133,63) |                   | +| PINK | #ffc0cb | rgb(255,192,203) |                   | +| PLUM | #dda0dd | rgb(221,160,221) |                   | +| POWDER_BLUE | #b0e0e6 | rgb(176,224,230) |                   | +| PURPLE | #800080 | rgb(128,0,128) |                   | +| REBECCA_PURPLE | #663399 | rgb(102,51,153) |                   | +| RED | #ff0000 | rgb(255,0,0) |                   | +| ROSY_BROWN | #bc8f8f | rgb(188,143,143) |                   | +| ROYAL_BLUE | #4169e1 | rgb(65,105,225) |                   | +| SADDLE_BROWN | #8b4513 | rgb(139,69,19) |                   | +| SALMON | #fa8072 | rgb(250,128,114) |                   | +| SANDY_BROWN | #f4a460 | rgb(244,164,96) |                   | +| SEA_GREEN | #2e8b57 | rgb(46,139,87) |                   | +| SEA_SHELL | #fff5ee | rgb(255,245,238) |                   | +| SIENNA | #a0522d | rgb(160,82,45) |                   | +| SILVER | #c0c0c0 | rgb(192,192,192) |                   | +| SKY_BLUE | #87ceeb | rgb(135,206,235) |                   | +| SLATE_BLUE | #6a5acd | rgb(106,90,205) |                   | +| SLATE_GRAY | #708090 | rgb(112,128,144) |                   | +| SLATE_GREY | #708090 | rgb(112,128,144) |                   | +| SNOW | #fffafa | rgb(255,250,250) |                   | +| SPRING_GREEN | #00ff7f | rgb(0,255,127) |                   | +| STEEL_BLUE | #4682b4 | rgb(70,130,180) |                   | +| TAN | #d2b48c | rgb(210,180,140) |                   | +| TEAL | #008080 | rgb(0,128,128) |                   | +| THISTLE | #d8bfd8 | rgb(216,191,216) |                   | +| TOMATO | #ff6347 | rgb(255,99,71) |                   | +| TRANSPARENT | #ffffff | rgb(255,255,255) |                   | +| TURQUOISE | #40e0d0 | rgb(64,224,208) |                   | +| VIOLET | #ee82ee | rgb(238,130,238) |                   | +| WHEAT | #f5deb3 | rgb(245,222,179) |                   | +| WHITE | #ffffff | rgb(255,255,255) |                   | +| WHITE_SMOKE | #f5f5f5 | rgb(245,245,245) |                   | +| YELLOW | #ffff00 | rgb(255,255,0) |                   | +| YELLOW_GREEN | #9acd32 | rgb(154,205,50) |                   | diff --git a/versioned_docs/version-6.5/configuration/Animation.md b/versioned_docs/version-6.5/configuration/Animation.md new file mode 100644 index 000000000..15f553ecb --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Animation.md @@ -0,0 +1,282 @@ +--- +id: Animation +title: Animation +hide_title: true +sidebar_label: Animation +--- +## Animating charts + +[Chart.JS](http://www.chartjs.org/) animates charts out of the box and **Charba** does not change this behavior. A number of options are provided to configure how the animation looks and how long it takes. + +The animation configuration consists in 3 different elements: + + 1. **[Animation](#animation)** to configure the common animation options. + 2. **[Animations](#animations)** to configure the common animation options for a specific sets of element(like bar, point, arc and line) properties. + 3. **[Transitions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Transitions.html)** to configure the animation and animations options for a specific update mode. + +## Animation + +[Animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animation.html) is used to configure the base options to animate the chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets duration option to the animation of the chart +chart.getOptions().getAnimation().setDuration(2000); + +int duration = chart.getOptions().getAnimation().getDuration(); +``` + +The default values are set in global defaults options, see [default global animation options](../defaults/DefaultsCharts#animation). + +The following animation options are available. + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| animateRotate | boolean | - | If `true`, the chart will animate in with a rotation animation. +| animateScale | boolean | - | If `true`, will animate scaling the chart from the center outwards. +| delay | int | [Yes](#scriptable) | Delay in milliseconds before starting the animations. +| duration | int | [Yes](#scriptable) | The number of milliseconds an animation takes. +| easing | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) | [Yes](#scriptable) | Easing function to use.
See [Robert Penner's easing equations](http://robertpenner.com/easing/) for more details. +| loop | boolean | [Yes](#scriptable) | If set to `true`, the animations loop endlessly. + +### Scriptable + +Scriptable options at animation level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](ScriptableOptions) section. + +```java +// creates chart +BarChart chart = new BarChart(); +// gets options +BarOptions options = chart.getOptions(); +// sets the animation option by a callback +options.getAnimation().setDuration(new DurationCallback() { + + @Override + public Integer invoke(DatasetContext context) { + // logic + return duration; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| delay | [DelayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DelayCallback.html) | double +| duration | [DurationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DurationCallback.html) | double +| easing | [EasingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/EasingCallback.html) | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) +| loop | [LoopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/LoopCallback.html) | boolean + +## Animations + +[Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animations.html) options configures which element properties are animated and how. + +The animations element is a [container of configurations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html) which can be stored and retrieved by a [key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html). + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// creates my animations key +Key key = Key.create("myKey"); +// creates and gets an animation configuration item by my key +AnimationCollection animationCollection = chart.getOptions().getAnimations().create(key); +// sets type +animationCollection.setType(AnimationType.NUMBER); +// sets properties +animationCollection.setProperties(Key.create("borderWidth")); +// sets and gets duration option to the animation configuration +animationCollection.setDuration(2000); + +int duration = animationCollection.getDuration(); +``` + +The default values are set in global defaults options, see [default global animations options](../defaults/DefaultsCharts#animations). + +The following options are available in [animation collection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html) object: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| delay | int | [Yes](#scriptable) | Delay in milliseconds before starting the animations. +| duration | int | [Yes](#scriptable) | The number of milliseconds an animation takes. +| easing | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) | [Yes](#scriptable) | Easing function to use.
See [Robert Penner's easing equations](http://robertpenner.com/easing/) for more details. +| from | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Start value for the animation. +| interpolator | [NativeInterpolator](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/NativeInterpolator.html) | - | Enables a custom interpolation during the animations. Only coding in java script for performance reasons. +| loop | boolean | [Yes](#scriptable) | If set to `true`, the animations loop endlessly. +| properties | String[] - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html)[] | The properties of elements to use to animate. +| type | [AnimationType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AnimationType.html) | Type of property, determines the interpolator used. +| to | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | End value for the animation. + +### Default animations + +[Chart.JS](http://www.chartjs.org/) provides a default configuration for every specific [animation type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AnimationType.html): + +| AnimationType | DefaultAnimationCollectionKey | Properties +| :- | :- | :- +| NUMBERS | [NUMBERS](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultAnimationCollectionKey.html) | DefaultAnimationPropertyKey.X,
DefaultAnimationPropertyKey.Y,
DefaultAnimationPropertyKey.BORDER_WIDTH,
DefaultAnimationPropertyKey.RADIUS,
DefaultAnimationPropertyKey.TENSION +| COLORS | [COLORS](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultAnimationCollectionKey.html) | DefaultAnimationPropertyKey.COLOR, DefaultAnimationPropertyKey.BORDER_COLOR, DefaultAnimationPropertyKey.BACKGROUND_COLOR +| BOOLEAN | [VISIBLE](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultAnimationCollectionKey.html) | DefaultAnimationPropertyKey.VISIBLE + +:::info +These default animations are overridden by most of the charts default configuration. +::: + +### Scriptable animations + +Scriptable options at animations level accept a callback which is called for each of the underlying data values. See more details in [Configuring charts](ScriptableOptions) section. + +```java +// creates chart +BarChart chart = new BarChart(); +// gets options +BarOptions options = chart.getOptions(); +// creates animations configuration +AnimationCollection animationCollection = options.getAnimations().create(DefaultAnimationCollectionKey.NUMBERS); +// sets the animation option by a callback +animationCollection.setFrom(new FromCallback() { + + @Override + public Double invoke(DatasetContext context) { + // logic + return from; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| delay | [DelayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DelayCallback.html) | double +| duration | [DurationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DurationCallback.html) | double +| easing | [EasingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/EasingCallback.html) | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) +| from | [FromCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FromCallback.html) | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| loop | [LoopCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/LoopCallback.html) | boolean +| to | [ToCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/toCallback.html) | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) + +## Transitions + +The [transitions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Transitions.html) are a set of animation configuration related to a specific update mode. + +Every [transition animation configuration](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationTransition.html) contains an instance of [Animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animation.html) and one of [Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animations.html) to configure the animation for a specific mode. + +```java +// creates a custom mode +TransitionMode mode = TransitionMode.create("myMode"); +// creates an animation transitions configuration for my mode +AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode); + +// gets animation and animations elements +Animation animation = animationMode.getAnimation(); + +Animations animations = animationMode.getAnimations(); +``` + +The default values are set in global defaults options, see [default global transitions options](../defaults/DefaultsCharts#transitions). + +The defaults modes are mapped in the [DefaultTransitionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultTransitionMode.html) enumeration and they are: + + * **ACTIVE** uses the animation configuration when an element is hovering + * **HIDE** uses the animation configuration when a dataset is hidden (by using legend or [hide](../charts/Api#hide) method). + * **RESET** uses the animation configuration when an element is resetting. + * **RESIZE** uses the animation configuration when an element is resizing. + * **SHOW** uses the animation configuration when a dataset is shown (by using legend or [show](../charts/Api#show) method). + +```java +// gets animation transitions element +Transitions transitions = chart.getOptions().getTransitions(); +// creates an animation transitions configuration for "show" +AnimationTransition animationMode = transitions.create(DefaultTransitionMode.SHOW); +// changes animation configuration setting duration to 10 seconds +animationMode.getAnimation().setDuration(10000); +// updates the chart using "show" mode +chart.update(DefaultTransitionMode.SHOW); +``` + +A custom transition can be used by passing it to [update](../charts/Api#update) or [reconfigure](../charts/Api#reconfigure) methods of the chart. + +```java +// creates a custom mode +TransitionMode mode = TransitionMode.create("myMode"); +// creates an animation transitions configuration for my mode +AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode); +// changes animation configuration setting duration to 10 seconds +animationMode.getAnimation().setDuration(10000); +// updates the chart using my mode +chart.update(mode); +``` + +## Disabling animation + +To disable an animation configuration, the animation node must be set to `false`, with the exception for animation transitions which can be disabled by setting the `duration` to `0`. + +```java +// ---------------------------------------- +// disables all animations +// ---------------------------------------- +chart.getOptions().setAnimationEnabled(false); +// ---------------------------------------- +// disables animation defined by the collection of 'colors' properties +// ---------------------------------------- +chart.getOptions().getAnimations().setEnabled(DefaultAnimationCollectionKey.COLORS, false); +// ---------------------------------------- +// disables the animation for 'active' mode +// ---------------------------------------- +// gets animation transitions element +Transitions transitions = chart.getOptions().getTransitions(); +// creates an animation transitions configuration for "active" +AnimationTransition animationMode = transitions.create(DefaultTransitionMode.ACTIVE); +// changes animation configuration setting duration to 0 seconds +animationMode.getAnimation().setDuration(0); +``` + +## Events + +A chart can emits events during the animation phases, when it's the animation is progressing and completed. + +### Progressing + +The progress event is thrown on each step of an animation. To catch the event and manage it, you can add a [AnimationProgressEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AnimationProgressEventHandler.html) instance to the chart options, as following: + +```java +chart.addHandler(new AnimationProgressEventHandler(){ + + /** + * Invoked when chart animation is progressing. + * + * @param event animation event + */ + @Override + public void onProgress(AnimationProgressEvent event){ + AnitmationItem item = event.getItem(); + // logic + } + +}, AnimationProgressEvent.TYPE); +``` + +The event provides the [animation item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AnimationItem.html) object with all information about animation status. + +### Completed + +The complete event is thrown at the end of an animation. To catch the event and manage it, you can add a [AnimationCompleteEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AnimationCompleteEventHandler.html) instance to the chart options, as following: + +```java +chart.addHandler(new AnimationCompleteEventHandler(){ + + /** + * Invoked when chart animation is complete. + * + * @param event animation event + */ + @Override + public void onComplete(AnimationCompleteEvent event){ + AnitmationItem item = event.getItem(); + // logic + } + +}, AnimationCompleteEvent.TYPE); +``` + +The event provides the [animation item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/AnimationItem.html) object with all information about animation status. diff --git a/versioned_docs/version-6.5/configuration/Commons.md b/versioned_docs/version-6.5/configuration/Commons.md new file mode 100644 index 000000000..bb8825120 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Commons.md @@ -0,0 +1,203 @@ +--- +id: Commons +title: Common configuration +hide_title: true +sidebar_label: Common options +--- +## Common options + +The configuration is used to change how the chart behaves. There are properties to control styling, fonts, the legend, etc. + +These sections describe general configuration options that can apply elsewhere to the charts. + +* **Responsive** defines responsive chart options that apply to all charts. +* **Pixel ratio** defines the physical display pixel ratio. +* **Locale** defines the language tag to use for internationalization. +* **Font** defines the graphical representation of text to use in the chart. + +To change the chart options, **Charba** is providing the method `getOptions` in all charts classes. + +## Responsive + +When it comes to change the chart size based on the window size, a major limitation is that the chart canvas *render* size can **not** be expressed with relative values, contrary to the *display* size. +Furthermore, these sizes are independent from each other and thus the canvas *render* size does not adjust automatically based on the *display* size, making the rendering inaccurate. + +The following examples **do not work** without setting `maintainAspectRatio` to `false`, because, setting to `false`, the chart will maintain the provided dimensions: + +```java +// invalid values, the canvas of chart doesn't resize +chart.setWidth("80vh"); +chart.setHeight("80vh"); +// in order to use the passed dimensions +chart.getOptions().setMaintainAspectRatio(false); +``` + +Leveraging on [Chart.JS](http://www.chartjs.org/) capabilities, **Charba** provides options to enable responsiveness and control the resize behavior of charts by detecting when the canvas *display* size changes and update the *render* size accordingly. + +To change and apply own properties, you can invoke the **set** methods, both at chart and global level, as following: + +```java +// chart +chart.getOptions().setResponsive(true); +boolean responsive = chart.getOptions().isResponsive(); +// global +Defaults.get().getGlobal().setResponsive(true); +boolean globalResponsive = Defaults.get().getGlobal().isResponsive(); +``` + +The default values are set in global defaults options, see [default global chart options](../defaults/DefaultsCharts). + +Table with options: + +| Name | Type | Description +| :- | :- | :- +| aspectRatio | double | Canvas aspect ratio (i.e. width / height, a value of 1 representing a square canvas).

Note: *this option is ignored if the height is explicitly defined either as attribute or via the style*. +| maintainAspectRatio | boolean | Maintain the original canvas aspect ratio (width / height) when resizing. +| responsive | boolean | Resizes the chart canvas when its container does. +| resizeDelay | int | Delay the resize update by give amount of milliseconds. This can ease the resize process by debouncing update of the elements. + +### Printing + +CSS media queries allow changing styles when printing a page. The CSS applied from these media queries may cause charts to need to resize. However, the resize won't happen automatically. To support resizing charts when printing, one needs to invoke the following statement after the **Charba** setup: + +```java +JsWindowHelper.enableResizeOnBeforePrint(); +``` + +## Device pixel ratio + +By default the chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g. Retina displays). + +For applications where a chart will be converted to a bitmap, or printed to a higher DPI medium it can be desirable to render the chart at a higher resolution than the default. + +Setting `devicePixelRatio` property to a value other than 1 will force the canvas size to be scaled by that amount, relative to the container size. There should be no visible difference on screen; the difference will only be visible when the image is zoomed or printed. + +To change and apply own property value, you can invoke the **set** methods, both at chart and global level, as following: + +```java +// chart +chart.getOptions().setDevicePixelRatio(2D); +double devicePixelRatio = chart.getOptions().getDevicePixelRatio(); +// global +Defaults.get().getGlobal().setDevicePixelRatio(2D); +double globalDevicePixelRatio = Defaults.get().getGlobal().getDevicePixelRatio(); +``` + +The default value is set in global defaults options, see [default global chart options](../defaults/DefaultsCharts). + +Table with options: + +| Name | Type | Description +| :- | :- | :- +| devicePixelRatio | double | Override the window's default devicePixelRatio. + +## Locale + +For applications where the numbers of ticks on scales must be formatted accordingly with a language sensitive number formatting, you can enable this kind of formatting by setting the locale option. + +The locale is a [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) object which represents a string that is a [Unicode BCP 47 locale identifier](https://www.unicode.org/reports/tr35/tr35.html#BCP_47_Conformance). + +A Unicode BCP 47 locale identifier consists of + + 1. a language code, + 2. (optionally) a script code, + 3. (optionally) a region (or country) code, + 4. (optionally) one or more variant codes, and + 5. (optionally) one or more extension sequences, + +with all present components separated by hyphens. + +```java +// chart +chart.getOptions().setLocale(CLocale.US); +CLocale locale = chart.getOptions().getLocale(); +// global +Defaults.get().getGlobal().setLocale(CLocale.US); +CLocale globalLocale = Defaults.get().getGlobal().getLocale(); +``` + +The default value is set in global defaults options, see [default global chart options](../defaults/DefaultsCharts). + +Table with options: + +| Name | Type | Description +| :- | :- | :- +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | A string with a BCP 47 language tag.
See [INTL locale](../intl/Locale#locale). + +## Colors + +There are chart settings that can change colors on the chart, related to their use case. The colors settings will be consume from the other elements of chart only if they don't have any other specific default, related to the element itself. The default values are set in [default global options](../defaults/DefaultsCharts). + +To change and apply own property value, you can invoke the **set** methods, as following: + +```java +// chart +chart.getOptions().setColor(HtmlColor.RED); +HtmlColor color = chart.getOptions().getColor(); +// global +Defaults.get().getGlobal().setColor(HtmlColor.RED); +HtmlColor color = Defaults.get().getGlobal().getColor(); +``` + +Table with options: + +| Name | Type | Description +| :- | :- | :- +| autoColors | boolean | `true` if the chart will cycle through a palette of seven [Chart.JS](http://www.chartjs.org/) brand colors. See [color](../coloring/Colors#default-color-palette) section. +| autoColorsForceOverride | boolean | `true` if you want to force the auto colors to always color your datasets, for example when using dynamic datasets at runtime. See [color](../coloring/Colors#default-color-palette) section. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | The default background color to use in the chart. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | The default border color to use in the chart. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | The default font color to use in the chart. + +## Font + +There are chart settings that can change all fonts on the chart. The font settings will be consume from the other elements of chart only if they don't have any other specific default, related to the element itself. The default values are set in global defaults options, see [default global font options](../defaults/DefaultsCharts#font). + +To change and apply own property value, you can invoke the **set** methods, as following: + +```java +// sets font size at chart level +chart.getOptions().getFont().setSize(16); +// gets the size +int size = chart.getOptions().getFont().getSize(); +``` + +| Name | Type | Description +| :- | :- | :- +| family | String | Font family for all text. +| size | int | Font size (in px) for text. +| style | [FontStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/FontStyle.html) | Font style +| weight | [Weight](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Weight.html) | Default font weight (boldness).
See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). +| lineHeight | double - String | Height of an individual line of text.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height). + +## Padding + +Many elements use the padding to apply space around the element itself. + +The [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) provides all **set** and **get** methods to manage the configuration, as following: + +```java +// creates a radial axis +RadialAxis axis = new RadialAxis(chart); +// enables point labels +axis.getPointLabels().setDisplay(true); +// set the same padding size to all directions +axis.getPointLabels().getBackdropPadding().setTop(5); + +int top = axis.getPointLabels().getBackdropPadding().getTop(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| bottom | int | The padding bottom in pixel. +| left | int | The padding left in pixel. +| right | int | The padding right in pixel. +| top | int | The padding top in pixel. + +The [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) provides the methods to: + + * set the same value to all dimensions, by `set(int)`. + * set the same value to X dimensions (left and right), by `setX(int)`. + * set the same value to Y dimensions (top and bottom), by `setY(int)`. diff --git a/versioned_docs/version-6.5/configuration/Datasets.md b/versioned_docs/version-6.5/configuration/Datasets.md new file mode 100644 index 000000000..eb0242284 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Datasets.md @@ -0,0 +1,36 @@ +--- +id: Datasets +title: Datasets +hide_title: true +sidebar_label: Datasets +--- +## Datasets + +The datasets options are managing the set options which will affect the datasets management. + +The datasets configuration is passed using the [Datasets](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Datasets.html) object in the chart options and mapped to [TypedDataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/TypedDataset.html). + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets showLine option to line datasets +chart.getOptions().getDatasets().get(ChartType.LINE).setShowLine(true); + +boolean showLine = chart.getOptions().getDatasets().get(ChartType.LINE).isShowLine(); +``` + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| animation | [Animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animation.html) | See [animation configuration](Animation#animation) section for more details. +| animations | [Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animations.html) | See [animation configuration](Animation#animations) section for more details. +| barPercentage | double | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| categoryPercentage | double | Percent (0-1) of the available width each category should be within the sample width. +| barThickness | int | Manually set width of each bar in pixels.
If set to [DefaultDatasets.FLEX_BAR_THICKNESS](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/defaults/globals/DefaultDatasets.html#FLEX_BAR_THICKNESS), it computes "optimal" sample widths that globally arrange bars side by side.
If not set (default), bars are equally sized based on the smallest interval. +| grouped | boolean | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| maxBarThickness | int | Set this to ensure that bars are not sized thicker than this. +| minBarLength | int | Set this to ensure that bars have a minimum length in pixels. +| showLine | boolean | If `true`, the line is drawn for dataset. +| transitions | [Transitions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Transitions.html) | See [animation configuration](Animation#transitions) section for more details. + diff --git a/versioned_docs/version-6.5/configuration/Elements.md b/versioned_docs/version-6.5/configuration/Elements.md new file mode 100644 index 000000000..85cf3d870 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Elements.md @@ -0,0 +1,317 @@ +--- +id: Elements +title: Elements +hide_title: true +sidebar_label: Elements +--- +## Elements + +The [elements](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Elements.html) allows the user to configure the different type of shapes which are used to draw the datasets. + +Options can be configured for four different types of elements: **[arc](#arc)**, **[lines](#line)**, **[points](#point)**, and **[bar](#bar)**. + +The [elements](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Elements.html) configuration is nested in the global configuration as following: + +```java +// gets elements node +Elements elements = chart.getOptions().getElements(); +``` + +### Point + +Point element is used to represent the points in a line chart or a bubble chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets border width and background color for the point +chart.getOptions().getElements().getPoint().setBorderWidth(2); +chart.getOptions().getElements().getPoint().setBackgroundColor("red"); + +int borderWidth = chart.getOptions().getElements().getPoint().getBorderWidth(); +IsColor backgroundColor = chart.getOptions().getElements().getPoint().getBackgroundColor(); +``` + +The defaults values are set in global defaults options, see [default global elements point options](../defaults/DefaultsCharts#point). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#point-scriptable-options) | Point fill color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#point-scriptable-options) | Point stroke color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderWidth | int | [Yes](#point-scriptable-options) | Point stroke width. +| hitRadius | int | [Yes](#point-scriptable-options) | Extra radius added to point radius for hit detection. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#point-scriptable-options) | Point fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#point-scriptable-options) | Point stroke color when hovered. +| hoverBorderWidth | int | [Yes](#point-scriptable-options) | Stroke width when hovered. +| hoverRadius | int | [Yes](#point-scriptable-options) | Point radius when hovered. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | [Yes](#point-scriptable-options) | Point style. +| radius | int | [Yes](#point-scriptable-options) | Point radius. +| rotation | double | [Yes](#point-scriptable-options) | The point rotation (in degrees). + +#### Point scriptable options + +Scriptable options at point element level accept a callback which is called for each of the underlying data values. See more details in [scriptable options](ScriptableOptions) section. + +```java +// gets point element configuration instance +Point point = chart.getOptions().getElements().getPoint(); +// sets the option by a callback +point.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hitRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| radius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DatasetContext> | double +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DatasetContext> | double + +### Line + +Line element is used to represent the line in a line chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets border width and background color for the line +chart.getOptions().getElements().getLine().setBorderWidth(5); +chart.getOptions().getElements().getLine().setBackgroundColor("red"); + +int borderWidth = chart.getOptions().getElements().getLine().getBorderWidth(); +IsColor backgroundColor = chart.getOptions().getElements().getLine().getBackgroundColor(); +``` + +The defaults values are set in global defaults options, see [default global elements line options](../defaults/DefaultsCharts#line). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#line-scriptable-options) | Line fill color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | [Yes](#line-scriptable-options) | Determines the shape used to draw the end points of lines.
See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#line-scriptable-options) | Line stroke color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderDash | int[] | [Yes](#line-scriptable-options) |The line dash pattern used when stroking lines. It uses an array of values that specify alternating lengths of lines and gaps which describe the pattern.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | [Yes](#line-scriptable-options) | Line dash offset.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#line-scriptable-options) | The shape used to join two line segments where they meet.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#line-scriptable-options) | Line stroke width. +| capBezierPoints | boolean | - | Set `true` to keep Bezier control inside the chart, `false` for no restriction. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | [Yes](#line-scriptable-options) | Interpolation mode to apply. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | [Yes](#line-scriptable-options) | How to fill the area under the line.
See [Filling modes](../coloring/Colors#filling-modes) +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#line-scriptable-options) | Line fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#line-scriptable-options) | Line stroke color when hovered. +| hoverBorderWidth | int | [Yes](#line-scriptable-options) | Stroke width when hovered. +| stepped | boolean - [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | [Yes](#line-scriptable-options) | If the line is shown as a stepped line. +| tension | double | - | Bezier curve tension (`0` for no Bezier curves). + +#### Line scriptable options + +Scriptable options at line element level accept a callback which is called for each of the underlying data values. See more details in [scriptable options](ScriptableOptions) section. + +```java +// gets line element configuration instance +Line line = chart.getOptions().getElements().getLine(); +// sets the option by a callback +line.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<DatasetContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<DatasetContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<DatasetContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| cubicInterpolationMode | [CubicInterpolationModeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CubicInterpolationModeCallback.html) | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FillCallback.html) | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| stepped | [SteppedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SteppedCallback.html) | [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) + +### Arc + +Arc element is used in the polar area, doughnut and pie charts. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets border width and background color for the arc +chart.getOptions().getElements().getArc().setBorderWidth(5); +chart.getOptions().getElements().getArc().setBackgroundColor(HtmlColor.RED); + +int borderWidth = chart.getOptions().getElements().getArc().getBorderWidth(); +IsColor backgroundColor = chart.getOptions().getElements().getArc().getBackgroundColor(); +``` + +The defaults values are set in global defaults options, see [default global elements arc options](../defaults/DefaultsCharts#arc). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| angle | double | [Yes](#arc-scriptable-options) | Arc angle to cover, for polar chart only. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#arc-scriptable-options) | Arc fill color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderAlign | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) | [Yes](#arc-scriptable-options) | Arc stroke alignment. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#arc-scriptable-options) | Arc stroke color. +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#arc-scriptable-options) | Arc line join style. The default is JoinStyle.ROUND when `borderAlign` is BorderAlign.INNER.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | [Yes](#arc-scriptable-options) | Arc stroke width. +| borderRadius | int | [Yes](#arc-scriptable-options) | The arc border radius (in pixels). +| circular | boolean | - | If the arc is curved. If `false` the arc will be flat. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#arc-scriptable-options) | Arc fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#arc-scriptable-options) | Arc stroke color when hovered. +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | [Yes](#arc-scriptable-options) | Arc line join style when hovered.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | [Yes](#arc-scriptable-options) | Stroke width when hovered. +| hoverOffset | int | [Yes](#arc-scriptable-options) | The offset of the arc (in pixels) when hovered. +| offset | int | [Yes](#arc-scriptable-options) | The offset of the arc (in pixels). +| spacing | int | - | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. + +#### Arc scriptable options + +Scriptable options at arc element level accept a callback which is called for each of the underlying data values. See more details in [scriptable options](ScriptableOptions) section. + +```java +// gets arc element configuration instance +Arc arc = chart.getOptions().getElements().getArc(); +// sets the option by a callback +arc.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| angle | [AngleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/AngleCallback.html) | double +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderAlign | [BorderAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderAlignCallback.html) | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html) | int +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<DatasetContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverOffset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int +| offset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DatasetContext> | int + +### Bar + +Bar element is used to represent the bars in a bar chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets border width and background color for the bar +chart.getOptions().getElements().getBar().setBorderWidth(5); +chart.getOptions().getElements().getBar().setBackgroundColor(HtmlColor.RED); + +int borderWidth = chart.getOptions().getElements().getBar().getBorderWidth(); +IsColor backgroundColor = chart.getOptions().getElements().getBar().getBackgroundColor(); +``` + +The defaults values are set in global defaults options, see [default global elements arc options](../defaults/DefaultsCharts#bar). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| autoInflateAmount | boolean | - | If `true`, the amount of pixels to inflate the bar rectangles, when drawing, is automatically calculating. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#bar-scriptable-options) | Bar fill color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| base | double | - | Base value for the bar in data units along the value axis. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#bar-scriptable-options) | Bar stroke color.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderRadius | int | [Yes](#bar-scriptable-options) | The bar border radius (in pixels). +| borderSkipped | boolean - [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) | [Yes](#bar-scriptable-options) | The edge to skip when drawing bar. +| borderWidth | int | [Yes](#bar-scriptable-options) | The bar border width (in pixels). +| enableBorderRadius| boolean | [Yes](#bar-scriptable-options) | If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#bar-scriptable-options) | Bar fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#bar-scriptable-options) | Bar stroke color when hovered. +| hoverBorderWidth | int | [Yes](#bar-scriptable-options) | Stroke width when hovered. +| hoverBorderRadius | int | [Yes](#bar-scriptable-options) | The bar border radius (in pixels) when hovered. +| inflateAmount | int | [Yes](#bar-scriptable-options) | The amount of pixels to inflate the bar rectangles, when drawing. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | [Yes](#bar-scriptable-options) | Point style for legend. + +#### Bar scriptable options + +Scriptable options at bar element level accept a callback which is called for each of the underlying data values. See more details in [scriptable options](ScriptableOptions) section. + +```java +// gets bar element configuration instance +Bar bar = chart.getOptions().getElements().getBar(); +// sets the option by a callback +bar.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // logic + return color; + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| borderSkipped | [BorderSkippedCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderSkippedCallback.html) | [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html) | int +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| enableBorderRadius | [EnableBorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/EnableBorderRadiusCallback.html) | boolean +| hoverBackgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DatasetContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [Gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) +| hoverBorderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DatasetContext> | int +| hoverBorderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html) | int +| inflateAmount | [InflateAmountCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/InflateAmountCallback.html) | int**(1)** +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<DatasetContext> | boolean - [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) + +**(1)**To enable `autoInflateAmount` by the inflate amount callback, the value to return must be `Undefined.INTEGER`. + +```java +Bar bar = chart.getOptions().getElements().getBar(); +// sets the option by a callback +bar.setInflateAmount(new InflateAmountCallback(){ + + @Override + public int invoke(DatasetContext context){ + // logic + return Undefined.INTEGER; // auto inflate amount + } +}); +``` diff --git a/versioned_docs/version-6.5/configuration/FillerAndDecimation.md b/versioned_docs/version-6.5/configuration/FillerAndDecimation.md new file mode 100644 index 000000000..ff56ab27a --- /dev/null +++ b/versioned_docs/version-6.5/configuration/FillerAndDecimation.md @@ -0,0 +1,70 @@ +--- +id: FillerAndDecimation +title: Filler and decimation +hide_title: true +sidebar_label: Decimation and filler +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Decimation + +The decimation element can be used with line charts to automatically decimate data at the start of the chart life cycle. + +Before enabling it, review the [requirements](#requirements) to ensure that it will work with the chart you want to create. + +The [decimation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Decimation.html) configuration is nested in the chart configuration as following: + +```java +// sets the sample at chart level +chart.getOptions().getDecimation().setSamples(1000); + +double samples = Dchart.getOptions().getDecimation().getSamples(); +``` +The defaults values are set in global defaults options, see [default global decimation options](../defaults/DefaultsCharts#decimation). + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| enabled | boolean | If `true`, the data decimation is enabled. +| algorithm | [DecimationAlgorithm](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DecimationAlgorithm.html) | Decimation algorithm to use. +| samples | double | If the `DecimationAlgorithm.LTTB` is used, this is the number of samples in the output dataset. Defaults to the canvas width to pick 1 sample per pixel. +| threshold | double | If the number of samples in the current axis range is above this value, the decimation will be triggered.
Defaults to 4 times the canvas width.
The number of point after decimation can be higher than the `threshold` value. + +### Algorithms + +The available decimation algorithms to use for data are the following: + +* `DecimationAlgorithm.MIN_MAX`: it will preserve peaks in your data but could require up to 4 points for each pixel. This type of decimation would work well for a very noisy signal where you need to see data peaks. +* `DecimationAlgorithm.LTTB` (Largest Triangle Three Bucket): it reduces the number of data points significantly. This is most useful for showing trends in data using only a few data points. + +### Requirements + +To use the decimation, the following requirements must be met: + +1. The dataset must have an [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) of `IndexAxis.X`. +2. The dataset must be a [line](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/LineDataset.html). +3. The dataset must not need any parsing for instance having `parsing` option set to `false`. +4. The X axis for the dataset must be either a [linear](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLinearAxis.html) or [time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeAxis.html) axis. + +## Filler + +Filler element configures the engine which is in charge to manage the filling of the datasets, by the property `fill`. See [here](../coloring/Colors#filling) how filling a dataset. + +The [filler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Filler.html) configuration is nested in the chart configuration as following: + +```java +// disables the propagation at chart level +Dchart.getOptions().getFiller().setPropagate(false); + +boolean propagate = chart.getOptions().getFiller().isPropagate(); +``` + +The defaults values are set in global defaults options, see [default global filler options](../defaults/DefaultsCharts#filler). + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| propagate | boolean | If `true`, the fill area will be recursively extended to the visible target defined by the fill value of hidden data set targets. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DrawTime.html) | Filler draw time. diff --git a/versioned_docs/version-6.5/configuration/Interaction.md b/versioned_docs/version-6.5/configuration/Interaction.md new file mode 100644 index 000000000..a82f96bb9 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Interaction.md @@ -0,0 +1,463 @@ +--- +id: Interaction +title: Interaction +hide_title: true +sidebar_label: Interaction +--- +## Interaction + +The interaction configuration defines how a user can interact with the chart via events or tooltips. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets interaction mode +chart.getOptions().getInteraction().setMode(DefaultInteractionMode.NEAREST); + +IsInteractionMode mode = chart.getOptions().getInteraction().getMode(); +``` + +The defaults values are set in global defaults options, see [default global interaction options](../defaults/DefaultsCharts#interaction). + +Table with options: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| axis | [InteractionAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/InteractionAxis.html) | InteractionAxis.X | Define which directions are used in calculating distances. +| intersect | boolean | `true` | if `true`, the hover mode only applies when the mouse position intersects an item on the chart. +| includeInvisible | boolean | `false` | if `true`, the invisible points that are outside of the chart area will also be included when evaluating interactions. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) | DefaultInteractionMode.NERAEST | Sets which elements managed by event or tooltip. + +## Hover + +The hover configuration, to configure interaction with the chart via hover, is passed to a chart by: + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets interaction mode +chart.getOptions().getHover().setMode(DefaultInteractionMode.NEAREST); + +IsInteractionMode mode = chart.getOptions().getHover().getMode(); +``` + +The defaults values are set in global defaults options, see [default global hover options](../defaults/DefaultsCharts#hover). + +Table with options: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| axis | [InteractionAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/InteractionAxis.html) | InteractionAxis.X | Define which directions are used in calculating distances. +| intersect | boolean | `true` | if `true`, the hover mode only applies when the mouse position intersects an item on the chart. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) | DefaultInteractionMode.NERAEST | Sets which elements will be hovered. + +### Custom interaction modes + +When configuring the interaction with the chart via interaction, hover or tooltip, a number of different modes are available. + +Possible [interaction modes](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultInteractionMode.html) out-of the box are: + + * `DefaultInteractionMode.POINT`, it will find all of the items that intersect the point. + * `DefaultInteractionMode.NEAREST`, it will get the item that is nearest to the point.T he nearest item is determined based on the distance to the center of the chart item (point, bar). If 2 or more items are at the same distance, the one with the smallest area is used. + * `DefaultInteractionMode.INDEX`, it will find all items at the same index. If the intersect setting is `true`, the first intersecting item is used to determine the index in the data. If intersect `false` the nearest item, in the `x` direction, is used to determine the index. + * `DefaultInteractionMode.DATASET`, it will find all items in the same dataset. If the intersect setting is `true`, the first intersecting item is used to determine the index in the data. If intersect `false` the nearest item is used to determine the index. + * `DefaultInteractionMode.X`, it will find all items that would intersect based on the X coordinate of the position only. Note that this only applies to cartesian charts. + * `DefaultInteractionMode.Y`, it will find all items that would intersect based on the Y coordinate of the position. Note that this only applies to cartesian charts. + +New modes can be defined by adding a custom implementation, by a [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) and [Interactioner](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/interaction/Interactioner.html) which can provide the items from the chart based on own logic. + +By the [Interactions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/interaction/Interactions.html) singleton, you could register and unregister custom interaction mode. + +```java +// creates my interaction mode +final AbstractInteractioner myMode = new AbstractInteractioner("myMode") { + + /** + * Returns items which must be managed by CHART.JS event or hovering handler and by tooltips. + * + * @param chart the chart we are returning items from + * @param event the event we are find things at + * @param options options to use + * @param useFinalPosition use final element position (animation target) + * @return items that are found + */ + public List invoke(IsChart chart, ChartEventContext event, InteractionOptions options, boolean useFinalPosition){ + // your logic + } +}; +// registers new interaction mode +Interactions.get().register(myMode): +.... +// sets new interaction mode to chart options +chart.getOptions().getTooltips().setMode(myMode.getMode()); +// or by string +chart.getOptions().getTooltips().setMode("myMode"); +``` + +Because the interaction mode is activated when every event is caught by the chart, sometimes the performance of a custom interaction mode could affect the chart interaction. + +To address it, you can also register a custom interaction mode written in JavaScript, passing the code to [Interactions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/interaction/Interactions.html): + +```java +// creates my tooltip position +final Interactioner myMode = Interactions.get().createNativeInteractioner("myMode", " // your logic in JS; ... return anArray; "); +// registers new interaction mode +Interactions.get().register(myMode): +.... +// sets new interaction mode to chart options +chart.getOptions().getTooltips().setMode(myMode.getMode()); +// or by string +chart.getOptions().getTooltips().setMode("myMode"); +``` + +The native interaction mode will receive 4 JavaScript arguments: + + 1. `chart` - the chart we are returning items from + 2. `event` - the event we are find things at + 3. `options` - interaction options to use + 4. `useFinalPosition` - use final element position (animation target) + +## Chart events + +You can set which events must be caught and how to manage them by event handlers. + +```java +// sets and gets the catchable events +chart.getOptions().setEvents(DefaultEvent.CLICK, DefaultEvent.MOUSEMOVE); + +Set events = chart.getOptions().getEvents(); +``` + +You can create your events that CHART.JS can catch and pass to your own [plugin](../plugins/): + +```java +// creates new event +IsEvent mouseout = IsEvent.create("mouseout"); + +// sets and gets the catchable events +chart.getOptions().setEvents(DefaultEvent.CLICK, DefaultEvent.MOUSEMOVE, mouseout); + +Set events = chart.getOptions().getEvents(); +``` + +The default value is set in global defaults options, see [default global chart options](../defaults/DefaultsCharts). + +Table with options: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | DefaultEvent.MOUSEMOVE, DefaultEvent.MOUSEOUT, DefaultEvent.CLICK, DefaultEvent.TOUCHSTART, DefaultEvent.TOUCHMOVE | The events option defines the browser events that the chart should listen to. + +### Clicking + +The click event is thrown if the browser event type is `mouseup` or `click`. To catch the event and manage it, you can add a [ChartClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/ChartClickEventHandler.html) instance to the chart options, as following: + +```java +// adds click event handler +chart.addHandler(new ChartClickEventHandler(){ + + /** + * Invoked when the user clicks on the chart. + * + * @param event chart click event + */ + @Override + public void onClick(ChartClickEvent event){ + // logic + } + +}, ChartClickEvent.TYPE); +``` + +### Hovering + +The hover event is thrown when any of the events fire on the chart. To catch the event and manage it, you can add a [ChartHoverEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/ChartHoverEvent.html) instance to the chart options, as following: + +```java +// adds hover event handler +chart.addHandler(new ChartHoverEventHandler(){ + + /** + * Invoked when the user hovers on the chart. + * + * @param event chart hover event + */ + @Override + public void onHover(ChartHoverEvent event){ + // logic + } + +}, ChartHoverEvent.TYPE); +``` + +### Resizing + +The resize event is thrown when the chart has been resized. To catch the event and manage it, you can add a [ChartResizeEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/ChartClickEventHandler.html) instance to the chart options, as following: + +```java +// adds resize event handler +chart.addHandler(new ChartResizeEventHandler(){ + + /** + * Invoked when the chart has been resized. + * + * @param event chart resize event + */ + @Override + public void onResize(ChartResizeEvent event){ + // logic + } + +}, ChartResizeEvent.TYPE); +``` + +### Selecting a dataset + +When a [click](#clicking) event is fired hovering a dataset element, you can add a [DatasetSelectionEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/DatasetSelectionEventHandler.html) instance to the chart options and considering it how a dataset selection, as following: + +```java +// adds dataset selection event handler +chart.addHandler(new DatasetSelectionEventHandler(){ + + /** + * Invoked when the user clicks on the chart to select a dataset. + * + * @param event chart dataset selection event + */ + @Override + public void onSelect(DatasetSelectionEvent event){ + // logic + } +}, DatasetSelectionEvent.TYPE); +``` + +The dataset selection [event](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/DatasetSelectionEvent.html) contains the selected dataset [reference](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DatasetReference.html) with all info about the selected dataset and item. + +## Title events + +There are 3 different kinds of events that you can catch from the chart title: + + 1. `click`, when you click on the title + 1. `enter`, when you enter on title element, hovering it. + 1. `leave`, when you leave from title element. + +### Clicking + +The click event is throw if the event type is `mouseup` or `click`. When the event is fired hovering the title element, you can add a [TitleClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/TitleClickEventHandler.html) instance to the chart options, as following: + +```java +// adds title click event handler +chart.addHandler(new TitleClickEventHandler(){ + + /** + * Invoked when the user clicks on the chart title. + * + * @param event title click event + */ + @Override + public onClick(TitleClickEvent event){ + // logic + } +}, TitleClickEvent.TYPE); +``` + +### Entering + +The enter event is throw if the event type is `mousemove` and you start hovering the title element. To catch the event and manage it, you can add a [TitleEnterEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/TitleEnterEventHandler.html) instance to the chart options, as following: + +```java +// adds title enter event handler +chart.addHandler(new TitleHoverEventHandler(){ + + /** + * Invoked when the user enters on the chart title. + * + * @param event title enter event + */ + @Override + public void onEnter(TitleEnterEvent event) { + // logic + } +}, TitleEnterEvent.TYPE); +``` + +### Leaving + +The leave event is throw if the event type is `mousemove` and you end hovering the title element. To catch the event and manage it, you can add a [TitleLeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/TitleLeaveEventHandler.html) instance to the chart options, as following: + +```java +// adds title leave event handler +chart.addHandler(new TitleLeaveEventHandler(){ + + /** + * Invoked when the user leaves on the chart title. + * + * @param event title leave event + */ + @Override + public void onLeave(TitleLeaveEvent event) { + // logic + } +}, TitleLeaveEvent.TYPE); +``` + +## Subtitle events + +There are 3 different kinds of events that you can catch from the chart subtitle: + + 1. `click`, when you click on the subtitle + 1. `enter`, when you enter on subtitle element, hovering it. + 1. `leave`, when you leave from subtitle element. + +### Clicking + +The click event is throw if the event type is `mouseup` or `click`. When the event is fired hovering the subtitle element, you can add a [SubtitleClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/SubtitleClickEventHandler.html) instance to the chart options, as following: + +```java +// adds subtitle click event handler +chart.addHandler(new SubtitleClickEventHandler(){ + + /** + * Invoked when the user clicks on the chart subtitle. + * + * @param event subtitle click event + */ + @Override + public onClick(SubtitleClickEvent event){ + // logic + } +}, SubtitleClickEvent.TYPE); +``` + +### Entering + +The enter event is throw if the event type is `mousemove` and you start hovering the subtitle element. To catch the event and manage it, you can add a [SubtitleEnterEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/SubtitleEnterEventHandler.html) instance to the chart options, as following: + +```java +// adds subtitle enter event handler +chart.addHandler(new SubtitleHoverEventHandler(){ + + /** + * Invoked when the user enters on the chart subtitle. + * + * @param event subtitle enter event + */ + @Override + public void onEnter(SubtitleEnterEvent event) { + // logic + } +}, SubtitleEnterEvent.TYPE); +``` + +### Leaving + +The leave event is throw if the event type is `mousemove` and you end hovering the subtitle element. To catch the event and manage it, you can add a [SubtitleLeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/SubtitleLeaveEventHandler.html) instance to the chart options, as following: + +```java +// adds subtitle leave event handler +chart.addHandler(new SubtitleLeaveEventHandler(){ + + /** + * Invoked when the user leaves on the chart subtitle. + * + * @param event subtitle leave event + */ + @Override + public void onLeave(SubtitleLeaveEvent event) { + // logic + } +}, SubtitleLeaveEvent.TYPE); +``` + +## Axes events + +There are 4 different kinds of events that you can catch from the chart axis: + + 1. `click`, when you click on the axis + 1. `enter`, when you enter on axis element, hovering it. + 1. `hover`, when you are hovering on the axis + 1. `leave`, when you leave from axis element. + +The axis event contain the selected scale [item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleItem.html) with all info about the selected scale. + +Due to charts can be created with specific axes, the axis event can provide the [axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Axis.html) configurations if there are, enabling you to get the instance used to configure the chart. + +### Clicking + +The click event is throw if the event type is `mouseup` or `click`. When the event is fired hovering an axis element, you can add a [AxisClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AxisClickEventHandler.html) instance to the chart options, as following: + +```java +// adds axis click event handler +chart.addHandler(new AxisClickEventHandler(){ + + /** + * Invoked when the user clicks on the chart axis. + * + * @param event axis click event + */ + @Override + public onClick(AxisClickEvent event){ + // logic + } +}, AxisClickEvent.TYPE); +``` + +### Entering + +The enter event is throw if the event type is `mousemove` and you start hovering the axis element. To catch the event and manage it, you can add a [AxisEnterEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AxisEnterEventHandler.html) instance to the chart options, as following: + +```java +// adds axis enter event handler +chart.addHandler(new AxisEnterEventHandler(){ + + /** + * Invoked when the user is entering on the chart axis. + * + * @param event axis enter event + */ + @Override + public void onEnter(AxisEnterEvent event) { + // logic + } +}, AxisEnterEvent.TYPE); +``` + +### Hovering + +The enter event is throw if the event type is `mousemove` and you are hovering the axis element. To catch the event and manage it, you can add a [AxisHoverEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AxisHoverEventHandler.html) instance to the chart options, as following: + +```java +// adds axis hover event handler +chart.addHandler(new AxisHoverEventHandler(){ + + /** + * Invoked when the user is hovering on the chart axis. + * + * @param event axis hover event + */ + @Override + public void onHover(AxisHoverEvent event) { + // logic + } +}, AxisHoverEvent.TYPE); +``` + +### Leaving + +The leave event is throw if the event type is `mousemove` and you end hovering the axis element. To catch the event and manage it, you can add a [AxisLeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/AxisLeaveEventHandler.html) instance to the chart options, as following: + +```java +// adds axis leave event handler +chart.addHandler(new AxisLeaveEventHandler(){ + + /** + * Invoked when the user is leaving on the chart axis. + * + * @param event axis leave event + */ + @Override + public void onLeave(AxisLeaveEvent event) { + // logic + } +}, AxisLeaveEvent.TYPE); +``` diff --git a/versioned_docs/version-6.5/configuration/Layout.md b/versioned_docs/version-6.5/configuration/Layout.md new file mode 100644 index 000000000..edfd64707 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Layout.md @@ -0,0 +1,64 @@ +--- +id: Layout +title: Layout +hide_title: true +sidebar_label: Layout +--- +## Layout + +The layout component enables the padding configuration to add to a chart. + +The [layout](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Layout.html) configuration is nested in the configuration using + +```java +// get layout +Layout layout = chart.getOptions().getLayout(); +// get padding +Padding padding = chart.getOptions().getLayout().getPadding(); + +// sets top and bottom options to padding of chart +chart.getOptions().getLayout().getPadding().setTop(10); +chart.getOptions().getLayout().getPadding().setBottom(10); +// to set same padding value to all sides of the chart +chart.getOptions().getLayout().getPadding().set(10); + +int paddingTop = chart.getOptions().getLayout().getPadding().getTop(); +``` + +The default values are set in global defaults options, see [default global layout options](../defaults/DefaultsCharts#layout). + +The following layout options are available. + +| Name | Type | Description +| :- | :- | :- +| autoPadding | boolean | If `true`, apply automatic padding so visible elements are completely drawn. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | To set specific padding for specific sides. + +See [padding documentation](Commons#padding) for more details. + +## Scriptable + +Padding also accepts a callback which is called at runtime and that takes the context as single argument, see [here](ScriptableOptions#chart-context) the details, which is representing contextual information and chart instance. + +The padding element can be set as a [callback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html), providing a [padding item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) instance, as following: + +```java +// get layout +Layout layout = chart.getOptions().getLayout(); +// sets callback +layout.setPadding(new PaddingCallback(){ + + @Override + public PaddingItem invoke(ChartContext context){ + PaddingItem padding = new PaddingItem(); + // your logic + return padding; + } +}); +``` + +The following option can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<ChartContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) diff --git a/versioned_docs/version-6.5/configuration/Legend.md b/versioned_docs/version-6.5/configuration/Legend.md new file mode 100644 index 000000000..5fd6ff59e --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Legend.md @@ -0,0 +1,277 @@ +--- +id: Legend +title: Legend +hide_title: true +sidebar_label: Legend +--- +## Legend + +With a chart, a legend is an area of a chart describing each of the data sets of the chart. + +The chart legend displays data about the data sets that area appearing on the chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets position option to the legend of the chart +chart.getOptions().getLegend().setPosition(Position.BOTTOM); + +Position position = chart.getOptions().getLegend().getPosition(); +``` + +The default values are set in global defaults options, see [default global legend options](../defaults/DefaultsCharts#legend). + +The following legend options are available. + +| Name | Type | Description +| :- | :- | :- +| align | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) | Alignment of the legend. +| display | boolean | If `true`, the legend is shown. +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | The events option defines the browser events that the legend should listen to. +| fullSize | boolean | Marks that this box should take the full width/height of the canvas (moving other boxes). +| maxHeight | int | Maximum height of the legend, in pixels. +| maxWidth | int | Maximum width of the legend, in pixels. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | Position of the legend. +| reverse | boolean | Legend will show data sets in reverse order. +| rtl | boolean | Set `true` for rendering the legends from right to left. +| textDirection | [TextDirection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextDirection.html) | This will force the text direction on the canvas for rendering the legend, regardless of the CSS specified on the canvas. + +## Events + +A chart legend can emits events during its life cycle, when the user clicks, hovers or leaves the legend. + +### Clicking + +The click event is thrown when a `click` event is registered on a label item. To catch the event and manage it, you can add a [LegendClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendClickEventHandler.html) instance to the chart options, as following: + +```java +chart.addHandler(new LegendClickEventHandler(){ + + /** + * Invoked when the user clicks on the chart legend. + * + * @param event legend click event + */ + @Override + public void onClick(LegendClickEvent event){ + // logic + } + +}, LegendClickEvent.TYPE); +``` + +The event provides the [legend item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendItem.html) object with all information about the clicked item. + +When a [LegendClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendClickEventHandler.html) instance, the default behavior of the chart (enable and disable datasets) is not performed. To invoke it, you can use [invokeLegendOnClick](../defaults/#methods) method of `Defaults` object. + +### Hovering + +The hover event is thrown when a `mousemove` event is registered on top of a label item. To catch the event and manage it, you can add a [LegendHoverEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendHoverEventHandler.html) instance to the chart options, as following: + +```java +chart.addHandler(new LegendHoverEventHandler(){ + + /** + * Invoked when the user hovers on the chart legend. + * + * @param event legend hover event + */ + @Override + public void onHover(LegendHoverEvent event){ + // logic + } + +}, LegendHoverEvent.TYPE); +``` + +The event provides the [legend item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendItem.html) object with all information about the hovered item. + +When a [LegendHoverEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendHoverEventHandler.html) instance, the default behavior of the chart is not performed. To invoke it, you can use [invokeLegendOnHover](../defaults/#methods) method of `Defaults` object. + +### Leaving + +The leave event is thrown when a `mouseout` event is registered on top of a label item. To catch the event and manage it, you can add a [LegendLeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendLeaveEventHandler.html) instance to the chart options, as following: + +```java +chart.addHandler(new LegendleaveEventHandler(){ + + /** + * Invoked when the user leaves on the chart legend. + * + * @param event legend leave event + */ + @Override + public void onLeave(LegendLeaveEvent event){ + // logic + } + +}, LegendLeaveEvent.TYPE); +``` + +The event provides the [legend item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendItem.html) object with all information about the left item. + +When a [LegendLeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/LegendLeaveEventHandler.html) instance, the default behavior of the chart is not performed. To invoke it, you can use [invokeLegendOnLeave](../defaults/#methods) method of `Defaults` object. + +## Legend labels + +The chart legend title can configure the title visible on legend element. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets and gets the padding and usePointStyle options for +// the labels of legend +chart.getOptions().getLegend().getLegendLabels().setPadding(5); +chart.getOptions().getLegend().getLegendLabels().setUsePointStyle(true); + +boolean usePointStyle = chart.getOptions().getLegend().getLegendLabels().isUsePointStyle(); +int padding = chart.getOptions().getLegend().getLegendLabels().getPadding(); +``` + +The default values are set in global defaults options, see [default global legend labels options](../defaults/DefaultsCharts#legend-labels). + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| borderRadius | int | Override the borderRadius to use. +| boxWidth | int | Width of colored box. +| boxHeight | int | Height of the colored box. +| color | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | The color of the legend text label.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font family of legend text label.
See [Font](../defaults/DefaultsCharts#font). +| padding | int | Padding between rows of colored boxes. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | This style of point is used for the legend. Only used if `usePointStyle` is `true`. +| pointStyleWidth | double | If `usePointStyle` is `true`, the width of the point style used for the legend. +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | Horizontal alignment of the label text. +| useBorderRadius | boolean | Label border radius will match corresponding border radius. +| usePointStyle | boolean | Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). + +### Callbacks + +A chart legend labels can be configured at runtime, providing some interfaces for a specific purpose. + +#### `filter` callback + +Allows filtering of legend items. + +To apply a filter callback, you can set a [LegendFilterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/LegendFilterCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getLegend().getLabels().setFilterCallback(new LegendFilterCallback(){ + + /** + * Allows filtering of legend items. + * + * @param chart chart instance + * @param item item to be filtered + * @return false to remove the item + * from the container, otherwise true. + */ + @Override + public boolean onFilter(IsChart chart, LegendItem item){ + // logic + return true; + } + +}); +``` + +The callback uses [LegendItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendItem.html) to enable filtering. + +#### `itemSort` callback + +Allows sorting of legend items. + +To apply a item sort callback, you can set a [LegendItemSortCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/LegendItemSortCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getLegend().getLabels().setItemSortCallback(new LegendItemSortCallback(){ + + /** + * Allows sorting of legend items. + * + * @param chart chart instance + * @param item1 the first object to be compared. + * @param item2 the second object to be compared. + * @return a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. + */ + @Override + public int onItemSort(IsChart chart, LegendItem item1, LegendItem item2){ + // logic + return 0; + } + +}); +``` + +The callback uses [LegendItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendItem.html) to enable filtering. + +#### `generateLabels` callback + +Generates legend label items for each thing in the legend. Default implementation returns the text and styling for the color box. + +To apply a custom callback, you can set a [legend labels callback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/LegendLabelsCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getLegend().getLegendLabels().setLabelsCallback(new LegendLabelsCallback(){ + + /** + * Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box. + * + * @param chart chart instance + * @param defaultLabels list of labels created by CHART.JS using the out of the box generate labels callback. + * @return a list of legend items. if null, uses the default implementation + */ + @Override + List generateLegendLabels(IsChart chart, List defaultLabels){ + // logic + return legendItemListInstance; + } + +}); +``` + +The callback gets the list of legend items, as argument, that [Chart.JS](http://www.chartjs.org/) have been calculated as default. + +This helps the implementation of the callback because you can change ONLY what you need to update. + +The callback returns a list of [label items](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/LegendLabelItem.html), which the properties to be applied. + +## Legend title + +The chart legend labels can configure the labels visible on legend element. + +To change and apply own properties, you can invoke the **set** methods, as following: + +```java +// sets text to the title of legend +chart.getOptions().getLegend().getTitle().setText("This is my legend title"); +// sets padding to the title of legend and enables it +chart.getOptions().getLegend().getTitle().getPadding().set(5); +chart.getOptions().getLegend().getTitle().setDisplay(true); + +Padding padding = chart.getOptions().getLegend().getTitle().getPadding(); +boolean display = chart.getOptions().getLegend().getTitle().isDisplay(); +``` + +The default values are set in global defaults options, see [default global legend title options](../defaults/DefaultsCharts#legend-title). + +The following are the attributes that you can set: + +| Name | Type | | Description +| :- | :- | :- +| display | boolean | If `true`, the legend title is shown. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | Number of pixels to add above and below the title text.
See [padding documentation](Commons#padding) for more details. +| color | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | The color of the legend text title.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font family of legend text title.
See [Font](../defaults/DefaultsCharts#font). + +## AtLeastOneDatasetHandler event handler + +**Charba** provides a common implementation for legend click event handler to enable the control about how many data sets are hidden, in order to have at least 1 data set visible and avoid to have an empty chart. + +To apply the event handler, you can set to the chart, as following: + +```java +// adds handler +chart.addHandler(new AtLeastOneDatasetHandler(), LegendClickEvent.TYPE); +``` diff --git a/versioned_docs/version-6.5/configuration/ScriptableOptions.md b/versioned_docs/version-6.5/configuration/ScriptableOptions.md new file mode 100644 index 000000000..10ab631a0 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/ScriptableOptions.md @@ -0,0 +1,313 @@ +--- +id: ScriptableOptions +title: Scriptable Options +hide_title: true +sidebar_label: Scriptable Options +--- +## Scriptable options + +Scriptable options are configuration items which can be configured at runtime, based on a callback which is called for each of the underlying data values and that takes a context representing contextual information. + +All scriptable options callbacks can accept only 1 argument, the context, which can be different depending on the chart element which is triggering the callback. + +Here is an example: + +```java +// creates datasets instance from chart +LineDataset dataset = chart.newDataset(); +// sets callback for scriptable options +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + return HtmlColor.PINK; + } + +}); +``` + +## Options Context + +The option context is used to give contextual information when resolving options. It applies to all scriptable options and their callbacks. + +The object is preserved, so it can be used to store and pass information between calls. + +There are the following different types of context objects, to be consumed on scriptable options on chart elements (plugins excluded): + + * [chart context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ChartContext.html) used for scriptable options that apply at chart configuration level. + * [dataset context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DatasetContext.html) used for scriptable options that apply at dataset or data configuration level. + * [scale context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleContext.html) used for scriptable options that apply at scale or ticks level. + +Apart for the options stored by the user in the context (attributes), all other options must be considered as read-only properties. + +### Chart context + +The [chart context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ChartContext.html) is used for scriptable options set in the chart configuration and is providing all necessary information about the chart in order to apply own logic. + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can only be `ContextType.CHART`. +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. + +### Custom attributes + +You can set custom attributes in the context. When the context is persistent, this could be very helpful because can store attributes needed in the logic of the scriptable options. + +| Name | Type | Description +| :- | :- | :- +| [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html) instance | boolean - double - int - String | The key could not be the same of the existing context properties and can set custom attributes. + +```java +// creates datasets instance from chart +BarDataset dataset = chart.newDataset(); +// sets callback for scriptable options +dataset.setBackgroundColor(new ColorCallback(){ + + private final Key myKey = Key.create("myKey"); + + @Override + public IsColor invoke(DatasetContext context){ + // ------------------------------- + // sets and gets boolean attribute + // ------------------------------- + context.setAttribute(myKey, true); + boolean myKeyAsBoolean = context.getAttribute(myKey, false); + // ------------------------------- + // sets and gets double attribute + // ------------------------------- + context.setAttribute(myKey, 0D); + double myKeyAsDouble = context.getAttribute(myKey, Double.NaN); + // ------------------------------- + // sets and gets int attribute + // ------------------------------- + context.setAttribute(myKey, 1); + double myKeyAsInt = context.getAttribute(myKey, Integer.MIN_VALUE); + // ------------------------------- + // sets and gets string attribute + // ------------------------------- + context.setAttribute(myKey, "myString"); + String myKeyAsString = context.getAttribute(myKey, null); + + // logic + } + +}); +``` + +### Dataset context + +The [dataset context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DatasetContext.html) is used for data set scriptable options which are providing all necessary information to get the data and data set links in order to apply own logic. + +Here is an example: + +```java +// creates datasets instance from chart +BarDataset dataset = chart.newDataset(); +// sets callback for scriptable options +dataset.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DatasetContext context){ + // gets chart from context + IsChart chart = context.getChart(); + // gets data by indexes provided by context + Dataset dataset = chart.getData().getDatasets().get(context.getDatasetIndex()); + Double value = dataset.getData().get(context.getDataIndex()); + // my logic + if (value >= 85D){ + return HtmlColor.RED; + } else if (value >= 60D){ + return HtmlColor.ORANGE; + } + return HtmlColor.GREEN; + } + +}); +``` + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| active | boolean | Whether the associated element is hovered. +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| dataIndex | int | The index of the current data. +| element | [ChartElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ChartElement.html) | The element (point, arc, bar, etc.) for this data +| datasetIndex | int | The index of the current data set. +| datasetItem | [DatasetItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DatasetItem.html) | The data set information for this data +| mode | [TransitionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/TransitionMode.html) | The update mode, brought by conte +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be `ContextType.DATASET` or `ContextType.DATA`. + +The following matrix will report which properties are available based on the context type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameContextType.DATASETContextType.DATA
activeAvailableAvailable
attributesAvailableAvailable
chartAvailableAvailable
dataIndexNOAvailable
datasetElementNOAvailable
datasetIndexAvailableAvailable
datasetItemAvailableAvailable
modeAvailableAvailable
+ +### Scale context + +The [scale context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ScaleContext.html) is used for scales and ticks scriptable options which are providing all necessary information to get the scale and ticks links in order to apply own logic. + +Here is an example: + +```java +// creates an axis +RadialAxis axis = new RadialAxis(chart); +// sets callback for scriptable options +axis.getPointLabels().setColor(new ColorCallback(){ + + @Override + public Object invoke(ScaleContext context){ + // my logic + return context.getIndex() % 2 == 0 ? HtmlColor.RED : HtmlColor.BLACK; + } +}); +``` + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| axis | [Axis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Axis.html) | Axis instance. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| index | int | The index of the current tick or the label (wfor [point labels](../axes/PointLabels#scriptable) callback). +| label | String | the label that is shown on the perimeter of the scale. Only for [point labels](../axes/PointLabels#scriptable) callback. +| scale | [ScaleItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleItem.html) | The scale associated to this context. +| tick | [ScaleTickItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleTickItem.html)| The tick associated to this context. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be `ContextType.SCALE`, `ContextType.TICK` or `ContextType.POINT_LABEL`. + +The following matrix will report which properties are available based on the context type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameContextType.SCALEContextType.TICKContextType.POINT_LABEL
attributesAvailableAvailableAvailable
axisAvailableAvailableAvailable
chartAvailableAvailableAvailable
indexNOAvailableAvailable
scaleAvailableAvailableAvailable
tickNOAvailableNO
labelNONOAvailable
+ +## Advanced usage of scriptable options + +There are use cases where the scriptable options callbacks are called several hundreds because are related to the amount of data set on datasets of the charts. + +When you are in above use case and you need the best performance, you can set a scriptable options by a [native java script callback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/NativeCallback.html). + +A [native java script callback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/NativeCallback.html) is built with java script code in order to be execute directly from [Chart.JS](http://www.chartjs.org/). + +```java +// creates a callback +// using java script code and default "context" variable name +// for scriptable context +NativeCallback from = NativeCallback.create("return context.index === 0 ? context.chart.scales.y.getPixelForValue(100) : context.chart.getDatasetMeta(context.datasetIndex).data[context.index - 1].getProps(['y'], true).y;"); + +// creates a callback +// using java script code and my "ctx" variable name +// for scriptable context +NativeCallback loop = NativeCallback.create("ctx", "return ctx.active"); + +Animations animations = chart.getOptions().getAnimations(); +AnimationCollection y = animations.create(DefaultAnimationPropertyKey.Y); +y.setFrom(from); +y.setLoop(loop); + +``` diff --git a/versioned_docs/version-6.5/configuration/Subtitle.md b/versioned_docs/version-6.5/configuration/Subtitle.md new file mode 100644 index 000000000..d10e7464b --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Subtitle.md @@ -0,0 +1,68 @@ +--- +id: Subtitle +title: Subtitle +hide_title: true +sidebar_label: Subtitle +--- + +## Subtitle + +A subtitle is a second title placed under the main title, by default. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets the text of subtitle +chart.getOptions().getSubtitle().setText("My subtitle of chart"); +// enables the subtitle and setting to use red color for text +chart.getOptions().getSubtitle().setDisplay(true); +chart.getOptions().getSubtitle().setColor("red"); + +IsColor color = chart.getOptions().getSubtitle().getColor(); +boolean display = chart.getOptions().getSubtitle().isDisplay(); +``` + +The defaults values are set in global defaults options, see [default global title options](../defaults/DefaultsCharts#subtitle). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) | [Yes](#scriptable) | Alignment of the subtitle. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Color of text of the subtitle.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | [Yes](#scriptable) | If `true`, the subtitle is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#scriptable) | Font of subtitle text. The default value is the global font with the style set to FontStyle.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| fullSize | boolean | [Yes](#scriptable) | Marks that this box should take the full width/height of the canvas (moving other boxes). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | [Yes](#scriptable) | Number of pixels to add above and below the subtitle text.
See [padding documentation](Commons#padding) for more details. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | [Yes](#scriptable) | Position of subtitle. + +## Scriptable + +Subtitle also accepts a callback, for some of above attributes, which is called at runtime and that takes the context as single argument, see [here](ScriptableOptions#chart-context) the details, which is representing contextual information and chart instance. + +```java +// get subtitle +Subtitle subtitle = chart.getOptions().getSubtitle(); +// sets callback +subtitle.setPadding(new PaddingCallback(){ + + @Override + public PaddingItem invoke(ChartContext context){ + PaddingItem padding = new PaddingItem(); + // your logic + return padding; + } +}); +``` + +The following option can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| align | [ElementAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ElementAlignCallback.html)<ChartContext> | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ChartContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<ChartContext> | boolean +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ChartContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| fullSize | [FullSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FullSizeCallback.html)<ChartContext> | boolean +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<ChartContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| position | [PositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PositionCallback.html)<ChartContext> | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) diff --git a/versioned_docs/version-6.5/configuration/Title.md b/versioned_docs/version-6.5/configuration/Title.md new file mode 100644 index 000000000..8fb70e811 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Title.md @@ -0,0 +1,68 @@ +--- +id: Title +title: Title +hide_title: true +sidebar_label: Title +--- + +## Title + +A title is a name or words used to describe a chart. + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// sets the text of title +chart.getOptions().getTitle().setText("My title of chart"); +// enables the title and setting to use red color for text +chart.getOptions().getTitle().setDisplay(true); +chart.getOptions().getTitle().setColor("red"); + +IsColor color = chart.getOptions().getTitle().getColor(); +boolean display = chart.getOptions().getTitle().isDisplay(); +``` + +The defaults values are set in global defaults options, see [default global title options](../defaults/DefaultsCharts#title). + +The following are the attributes that you can set: + +| Name | Type | Scriptable | Description +| :- | :- | :- | :- +| align | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) | [Yes](#scriptable) | Alignment of the title. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [Yes](#scriptable) | Color of text of the title.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| display | boolean | [Yes](#scriptable) | If `true`, the title is shown. +| font | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | [Yes](#scriptable) | Font of title text. The default value is the global font with the style set to FontStyle.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| fullSize | boolean | [Yes](#scriptable) | Marks that this box should take the full width/height of the canvas (moving other boxes). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | [Yes](#scriptable) | Number of pixels to add above and below the title text.
See [padding documentation](Commons#padding) for more details. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | [Yes](#scriptable) | Position of title. + +## Scriptable + +Title also accepts a callback, for some of above attributes, which is called at runtime and that takes the context as single argument, see [here](ScriptableOptions#chart-context) the details, which is representing contextual information and chart instance. + +```java +// get title +Title title = chart.getOptions().getTitle(); +// sets callback +title.setPadding(new PaddingCallback(){ + + @Override + public PaddingItem invoke(ChartContext context){ + PaddingItem padding = new PaddingItem(); + // your logic + return padding; + } +}); +``` + +The following option can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| align | [ElementAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ElementAlignCallback.html)<ChartContext> | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<ChartContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<ChartContext> | boolean +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<ChartContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| fullSize | [FullSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FullSizeCallback.html)<ChartContext> | boolean +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<ChartContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| position | [PositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PositionCallback.html)<ChartContext> | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) diff --git a/versioned_docs/version-6.5/configuration/Tooltip.md b/versioned_docs/version-6.5/configuration/Tooltip.md new file mode 100644 index 000000000..1fb1417f2 --- /dev/null +++ b/versioned_docs/version-6.5/configuration/Tooltip.md @@ -0,0 +1,553 @@ +--- +id: Tooltip +title: Tooltip +hide_title: true +sidebar_label: Tooltip +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Tooltip + +A tooltip is a text description near an object. The tooltip is displayed when the user hovers the mouse cursor over the object. + +Tooltips are helpful for new users because they enable the user to learn about each icon or object by hovering their mouse over them. + + + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// enables tooltip, setting the interaction mode +chart.getOptions().getTooltips().setEnabled(true); +chart.getOptions().getTooltips().setMode(DefaultInteractionMode.AVERAGE); + +boolean enabled = chart.getOptions().getTooltips().isEnabled(); +IsInteractionMode mode = chart.getOptions().getTooltips().getMode(); +``` + +The default values are set in global defaults options, see [default global tooltip options](../defaults/DefaultsCharts#tooltip). + +The following are the attributes that you can set: + +| Name | Type | Description +| :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Background color of the tooltips. +| bodyColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color of body text. +| bodyFont | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font of body text. The default value is the global font with the style set to FontStyle.NORMAL.
See [Font](../defaults/DefaultsCharts#font). +| bodyAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | Alignment of body element of the tooltips. +| bodySpacing | int | Spacing to add to top and bottom of each tooltip item. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color of the border. +| borderWidth | int | Size of the border. +| boxWidth | int | Width of the color box if `displayColors` is `true`. +| boxHeight | int | Height of the color box if `displayColors` is `true`. +| caretPadding | int | Extra distance to move the end of the tooltip arrow away from the tooltip point. +| caretSize | int | Size, in px, of the tooltip arrow. +| cornerRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | Radius of tooltip corner curves. +| displayColors | boolean | If `true`, color boxes are shown in the tooltip. +| enabled | boolean | If `true`, the tooltips are enabled. +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | The events option defines the browser events that the tooltip should listen to. +| footerColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color of the footer. +| footerFont | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font of footer text. The default value is the global font with the style set to FontStyle.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| footerAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | Alignment of footer element of the tooltips. +| footerMarginTop | int | Margin to add before drawing the footer. +| footerSpacing | int | Spacing to add to top and bottom of each footer line. +| intersect | boolean | if `true`, the tooltip mode applies only when the mouse position intersects with an element. If `false`, the mode will be applied at all times. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DefaultInteractionMode.html) | Sets which elements appear in the tooltip. +| multiKeyBackground | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color to draw behind the colored boxes when multiple items are in the tooltip. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | The padding to add inside the tooltip.
See [padding documentation](Commons#padding) for more details. +| position | [TooltipPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipPosition.html) | The mode for positioning the tooltip. +| rtl | boolean | `true` for rendering the tooltips from right to left. +| textDirection | [TextDirection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextDirection.html) | This will force the text direction on the canvas for rendering the tooltips, regardless of the CSS specified on the canvas +| titleColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Color of the footer. +| titleFont | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) | Font of title text. The default value is the global font with the style set to FontStyle.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| titleAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | Alignment of title element of the tooltips. +| titleMarginBottom | int | Margin to add on bottom of title section. +| titleSpacing | int | Spacing to add to top and bottom of each title line. +| usePointStyle | boolean | Use the corresponding point style (from dataset options) instead of color boxes (size is based on the minimum value between box width and box height). +| xAlign | [TooltipAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipAlign.html) | Position of the tooltip caret in the X direction.
Can accept only TooltipAlign.LEFT, TooltipAlign.CENTER and TooltipAlign.RIGHT. +| yAlign | [TooltipAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipAlign.html) | Position of the tooltip caret in the Y direction.
Can accept only TooltipAlign.TOP, TooltipAlign.CENTER and TooltipAlign.BOTTOM. + +### Positioning + +Possible [tooltip position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipPosition.html) out-of the box are: + + * `TooltipPosition.AVERAGE`, it will place the tooltip at the average position of the items displayed in the tooltip. + * `TooltipPosition.NEAREST`, it will place the tooltip at the position of the element closest to the event position. + +New modes can be defined by adding a custom implementation, by a [TooltipPositioner](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/positioner/TooltipPositioner.html) which can provide the tooltip position based on own logic. + +By the [Positioner](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/positioner/Positioner.html) singleton, you could register and unregister custom positioners. + +```java +// creates my tooltip position +final CustomTooltipPosition myPosition = new CustomTooltipPosition("myPosition"); +// registers new tooltip positioner +Positioner.get().register(new TooltipPositioner(){ + + /** + * Returns the tooltip position + * which must be used in chart options. + * + * @return the tooltip position. + */ + @Override + public CustomTooltipPosition getName(){ + return myPosition; + } + + /** + * Applies own logic to returns the point where the tooltip must be showed. + * + * @param chart chart instance + * @param items list of dataset reference items + * @param eventPoint the point of event when the method has been invoked + * @return the point where the tooltip must be showed. + */ + @Override + public Point computePosition(IsChart chart, List items, Point eventPoint){ + ChartAreaNode area = chart.getNode().getChartArea(); + Point p = new Point(); + p.setX(area.getLeft()); + p.setY(area.getTop()); + return p; + }); +} +.... +// sets new tooltip position to chart options +chart.getOptions().getTooltips().setPosition(myPosition); +``` + +If the positioner will return `null` instead of a point, the tooltip will disappear. + +The [Positioner](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/positioner/Positioner.html) provides a method to get the position calculated by defined tooltip position. + +```java +// creates my tooltip position +final CustomTooltipPosition myPosition = new CustomTooltipPosition("myPosition"); +// registers new tooltip positioner +Positioner.get().register(new TooltipPositioner(){ + + /** + * Returns the tooltip position + * which must be used in chart options. + * + * @return the tooltip position. + */ + @Override + public CustomTooltipPosition getName(){ + return myPosition; + } + + /** + * Applies own logic to returns the point where the tooltip must be showed. + * + * @param chart chart instance + * @param items list of dataset reference items + * @param eventPoint the point of event when the method has been invoked + * @return the point where the tooltip must be showed. + */ + @Override + public Point computePosition(IsChart chart, List items, Point eventPoint){ + ChartAreaNode area = chart.getNode().getChartArea(); + Point p = new Point(); + p.setX(area.getLeft()); + Point average = Positioner.get().invokePositioner(TooltipPosition.AVERAGE, chart, items, eventPoint); + if (average != null) { + p.setY(average.getY()); + return p; + } + // hide tooltip + return null; + }); +} +.... +// sets new tooltip position to chart options +chart.getOptions().getTooltips().setPosition(myPosition); +``` + +:::caution +If you unregister a positioner and a chart still is configured with the custom tooltip position, **Charba** will throw an exception when the chart will be updated. +::: + +## Items callbacks + +A chart tooltips can be configured at runtime, providing some interfaces for a specific purpose. + +### Sorting + +The implementation of [TooltipItemSortCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipItemSortCallback.html) allows sorting of tooltip items. + +To apply the callback, you can set a instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().setItemSortCallback(new TooltipItemSortCallback(){ + + /** + * Allows sorting of tooltip items. + * + * @param chart chart instance + * @param item1 the first object to be compared. + * @param item2 the second object to be compared. + * @return a negative integer, zero, or a positive integer as the first argument + * is less than, equal to, or greater than the second. + */ + @Override + public int onItemSort(IsChart chart, TooltipItem item1, TooltipItem item2){ + // logic + return 0; + } + +}); +``` + +The callback uses a couple of [TooltipItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TooltipItem.html) to enable the sort. + +### Filtering + +The implementation of [TooltipFilterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipFilterCallback.html) allows filtering of tooltip items. + +To apply the callback, you can set a instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().setFilterCallback(new TooltipFilterCallback(){ + + /** + * Allows filtering of tooltip items. + * + * @param chart chart instance + * @param item item to be filtered + * @return false to remove the item + * from the container, otherwise true. + */ + @Override + public boolean onFilter(IsChart chart, TooltipItem item){ + // logic + return true; + } + +}); +``` + +The callback uses [TooltipItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TooltipItem.html) to enable filtering. + +## Elements callbacks + +There are a set of available callbacks to configure and customize own tooltips. The tooltip callbacks configuration is nested in the tooltip configuration. + +To simplify the implementation of all callbacks available in [Chart.JS](http://www.chartjs.org/), **Charba** splits the callbacks in 4 main ones, to manage every single element of a tooltip separately: + + * Title + * Body + * Footer + * Labels + + + +All callbacks must be set in a inner element of tooltip configuration, as following: + +```java +// gets the inner callbacks element +TooltipsCallbacks callbacks = chart.getOptions().getTooltips().getCallbacks(); +``` + +To invoke the default behavior of the chart, you can use [defaults](../defaults/#methods) methods of `Defaults` object. + +### Title + +The [TooltipTitleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipTitleCallback.html) is triggered for providing text of title. + +All methods must return a list of strings which are treated as multiple lines of text. + +This callback takes care about labels to apply to the title, all methods are implemented by own defaults in order that you can implement only the method where you are interested in: + +```java +public interface TooltipTitleCallback { + + /** + * Returns the text to render before the title. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onBeforeTitle(IsChart chart, List items){ + return Collections.emptyList(); + } + + /** + * Returns text to render as the title of the tooltip. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onTitle(IsChart chart, List items){ + return Defaults.get().invokeTooltipsCallbackOnTitle(chart, items); + } + + /** + * Returns text to render after the title. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onAfterTitle(IsChart chart, List items){ + return Collections.emptyList(); + } + +} +``` + +To apply the callback, you can set a [TooltipTitleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipTitleCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().getCallbacks().setTitleCallback(new TooltipTitleCallback){ + +// implementation + +}); +``` + +### Body + +The [TooltipBodyCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipBodyCallback.html) is triggered for providing text of body. + +All methods must return a list of strings which are treated as multiple lines of text. + +This callback takes care about labels to apply to the body, all methods are implemented by own defaults in order that you can implement only the method where you are interested in: + +```java +public interface TooltipBodyCallback { + + /** + * Returns text to render before the body section. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the body. + */ + default List onBeforeBody(IsChart chart, List items){ + return Collections.emptyList(); + } + + /** + * Returns text to render after the body section. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltips items + * @return a list of labels to apply to the body. + */ + default List onAfterBody(IsChart chart, List items){ + return Collections.emptyList(); + } +} +``` + +To apply the callback, you can set a [TooltipBodyCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipBodyCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().getCallbacks().setBodyCallback(new TooltipBodyCallback){ + +// implementation + +}); +``` + +### Footer + +The [TooltipFooterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipFooterCallback.html) is triggered for providing text of footer. + +All methods must return a list of strings which are treated as multiple lines of text. + +This callback takes care about labels to apply to the footer, all methods are implemented by own defaults in order that you can implement only the method where you are interested in: + +```java +public interface TooltipFooterCallback { + + /** + * Returns text to render before the footer section. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onBeforeFooter(IsChart chart, List items){ + return Collections.emptyList(); + } + + /** + * Returns text to render as the footer of the tooltip. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onFooter(IsChart chart, List items){ + return Collections.emptyList(); + } + + /** + * Text to render after the footer section. + * If returns null or empty list, it will be ignored. + * + * @param chart chart instance + * @param items list of all tooltip items + * @return a list of labels to apply to the title. + */ + default List onAfterFooter(IsChart chart, List items){ + return Collections.emptyList(); + } +} +``` + +To apply the callback, you can set a [TooltipFooterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipFooterCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().getCallbacks().setFooterCallback(new TooltipFooterCallback){ + +// implementation + +}); +``` + +### Label + +The [TooltipLabelCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipLabelCallback.html) is triggered for providing the text and colors that displays for a given data point. + +This callback takes care about labels and styles to apply to the tooltip items, all methods are implemented by own defaults in order that you can implement only the method where you are interested in: + +```java +public interface TooltipLabelCallback { + + /** + * Returns text to render before an individual label. + * This will be called for each item in the tooltip. + * If returns null or an empty list, it will be ignored. + * + * @param chart chart instance + * @param item tooltip item + * @return labels to be applied. + */ + default List onBeforeLabel(IsChart chart, TooltipItem item){ + return Collections.emptyList(); + } + + /** + * Returns text to render for an individual item in the tooltip. + * If returns null or an empty list, it will be ignored. + * + * @param chart chart instance + * @param item tooltip item + * @return labels to be applied. + */ + default List onLabel(IsChart chart, TooltipItem item){ + return Defaults.get().invokeTooltipsCallbackOnLabel(chart, item); + } + + /** + * Returns the colors and borders to render for the tooltip item. + * If returns null, it will be ignored. + * + * @param chart chart instance + * @param item tooltip item + * @return label color to be applied. + */ + default TooltipLabelColor onLabelColor(IsChart chart, TooltipItem item){ + return Defaults.get().invokeTooltipsCallbackOnLabelColor(chart, item); + } + + /** + * Returns the point style to use instead of color boxes if usePointStyle is true. + * Default implementation uses the point style from the dataset points. + * + * @param chart chart instance + * @param item tooltip item + * @return point style to be applied. + */ + default TooltipLabelPointStyle onLabelPointStyle(IsChart chart, TooltipItem item){ + return Defaults.get().invokeTooltipsCallbackOnLabelPointStyle(chart, item); + } + + /** + * Returns the colors for the text of the label for the tooltip item. + * If returns null, it will be ignored. + * + * @param chart chart instance + * @param item tooltip item + * @return label text color to be applied. + */ + default IsColor onLabelTextColor(IsChart chart, TooltipItem item){ + return chart.getOptions().getTooltips().getBodyColor(); + } + + /** + * Returns text to render after an individual label. + * If returns null or an empty list, it will be ignored. + * + * @param chart chart instance + * @param item tooltip item + * @return labels to be applied. + */ + default List onAfterLabel(IsChart chart, TooltipItem item){ + return Collections.emptyList(); + } +} +``` + +To apply the callback, you can set a [TooltipLabelCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipLabelCallback.html) instance to the chart options, as following: + +```java +chart.getOptions().getTooltips().getCallbacks().setLabelCallback(new TooltipLabelCallback){ + +// implementation + +}); +``` + +To set the color or borders of labels, there is [TooltipLabelColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TooltipLabelColor.html) class which enable the setting of colors and borders. + +To set the point style of labels, there is [TooltipLabelPointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TooltipLabelPointStyle.html) class which enable the setting of point style and the rotation to apply. + +## External rendering callback + +The implementation of [TooltipExternalCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TooltipExternalCallback.html) allows you to hook in the tooltip rendering process so that you can render the tooltip in own custom way. + + + + + + + +
+ + +Generally this is used to create an HTML tooltip and you can enable custom tooltips in the chart configuration as following: + +```java +chart.getOptions().getTooltips().setExternalCallback(new TooltipExternalCallback(){ + + /** + * External tooltips callback allows you to hook in the tooltip + * rendering process so that you can render the tooltip in your own + * custom way. + * + * @param chart chart instance + * @param model all info about tooltip to create own HTML tooltip. + */ + @Override + public onCustom(IsChart chart, TooltipModel model){ + // logic + } + +}); +``` + +The callback can use the [tooltip model](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/TooltipModel.html), with the complete model about the tooltip. diff --git a/versioned_docs/version-6.5/defaults/Defaults.md b/versioned_docs/version-6.5/defaults/Defaults.md new file mode 100644 index 000000000..cdc46a72e --- /dev/null +++ b/versioned_docs/version-6.5/defaults/Defaults.md @@ -0,0 +1,119 @@ +--- +id: Defaults +title: Defaults options +hide_title: true +sidebar_label: Using defaults +--- +## Using defaults + +The options are used to change how the chart behaves. There are properties to control styling, fonts, the legend, etc. + +This concept is allowing for changing options globally across chart types, using chart type defaults and scales defaults appropriately, avoiding the need to specify options for each instance, or the default for a particular chart type. + +**Charba** doesn't merge the options object but delegates [Chart.JS](http://www.chartjs.org/) to do it which merges the option object passed to the chart with the global configuration. + +In this way you can be as specific as you would like in your individual chart configuration, while still changing the defaults for all chart types where applicable. + +There are 4 main defaults entities that you can manage to configure your charts, at global level: + + 1. [Global](#global): global options, containing the configuration items which can be applied to all charts, whatever type of chart. Scale configuration is excluded. + 1. [Chart option](#charts-type): global options related to a specific type of chart, containing both options and scales configuration. + 1. [Scale](#scales): global options related to scale, containing the configuration items which can be applied to all charts (with scales), whatever type of chart. + 1. [Scale type](#scales-type): global options related to a specific [type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/AxisType.htmll) of scale which can be applied to all charts which are using that type of scale. + +**Charba** is providing a singleton [Defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html) which allows you to manage all defaults entities above mentioned. + +:::info +It's not possible to apply any callbacks or any events handlers at global level, but only on at chart instance one. +::: + +## Global + +To change the global options, **Charba** is providing the method `getGlobal` in the [Defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html) class. These options will be applied to all charts, whatever type of chart. + +With above method you can get all global configurations of [Chart.JS](http://www.chartjs.org/) and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().setResponsive(false); +Defaults.get().getGlobal().setMaintainAspectRatio(true); + +double circumference = Defaults.get().getGlobal().getCircumference(); +``` + +## Charts type + +To change the global options for a specific chart type, **Charba** is providing the method `getOptions` in the [Defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html) class. + +With this method you can get all global configurations for a specific chart of [Chart.JS](http://www.chartjs.org/) and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +The chart type are defined in a enumeration, [ChartType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/ChartType.html) but, by controllers, you can create your chart type, therefore the method will accept a [Type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Type.html) object. + +```java +// -------------------------------------- +// GLOBAL options for specific chart type +// -------------------------------------- +Defaults.get().getOptions(ChartType.LINE).setResponsive(false); +Defaults.get().getOptions(ChartType.LINE).setMaintainAspectRatio(true); + +double circumference = Defaults.get().getOptions(ChartType.LINE).getCircumference(); + +Defaults.get().getOptions(ChartType.LINE).getElements().getPoint().setPointStyle(PointStyle.RECT); +``` + +## Scales + +To change the global scale, **Charba** is providing the method `getScale` in the [defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html). + +With this method you can get all global configuration of [Chart.JS](http://www.chartjs.org/) for [scale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/GlobalScale.html) (common one, not related to chart type) and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().setStacked(true); +``` + +## Scales type + +To change the global scale for a specific scale type, **Charba** is providing the method `getScale` in the [Defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html) class, passing the [type](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/AxisType.html) of the scale. + +With this method you can get all global configurations for a specific type of scale and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +```java +// -------------------------------------- +// GLOBAL options for specific scale type +// -------------------------------------- +Defaults.get().getScale(ChartAxisType.LINEAR).setDisaply(false); +Defaults.get().getScale(ChartAxisType.LINEAR).setBeginAtZero(true); +``` + +## Methods + +The default singleton instance provides a set of helpful methods to invoke default behavior of [Chart.JS](http://www.chartjs.org/), helpful methods when a callback is implemented and you want to perform a normal behavior. + + +```java +public class MyLegendClickEventHandler implements LegendClickEventHandler { + + @Override + public void onClick(LegendClickEvent event){ + // invokes default click callback + Defaults.get().invokeLegendOnClick(event); + } +``` + +| Name | Scope | Description +| :- | :- | :- +| **invokeChartOnClick** | Chart | This method invokes the default `onClick` implementation on a chart, if there is. +| **invokeChartOnHover** | Chart | This method invokes the default `onHover` implementation on a chart, if there is. +| **generateLabels** | Legend | This method will provide the default legend items of a chart. +| **invokeLegendOnClick** | Legend | This method invokes the default `onClick` implementation on a legend of a chart, if there is. +| **invokeLegendOnHover** | Legend | This method invokes the default `onHover` implementation on a legend of a chart, if there is. +| **invokeLegendOnLeave** | Legend | This method invokes the default `onLeave` implementation on a legend of a chart, if there is. +| **invokeTooltipsCallbackOnTitle** | Tooltip | This method invokes the default implementation on a tooltip of a chart to get the title text of the tooltip. +| **invokeTooltipsCallbackOnLabel** | Tooltip | This method invokes the default implementation on a tooltip of a chart to get an individual item in the tooltip. +| **invokeTooltipsCallbackOnLabelColor** | Tooltip | This method invokes the default implementation on a tooltip of a chart to get the color of an individual item in the tooltip. +| **invokeTooltipsCallbackOnLabelPointStyle** | Tooltip | This method invokes the default implementation on a tooltip of a chart to get the point style of an individual item in the tooltip. diff --git a/versioned_docs/version-6.5/defaults/DefaultsCharts.md b/versioned_docs/version-6.5/defaults/DefaultsCharts.md new file mode 100644 index 000000000..97b6beb4e --- /dev/null +++ b/versioned_docs/version-6.5/defaults/DefaultsCharts.md @@ -0,0 +1,672 @@ +--- +id: DefaultsCharts +title: Defaults charts options +hide_title: true +sidebar_label: Charts +--- + +## Commons charts options + +To change the global options, **Charba** is providing the method `getGlobal` in the [Defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html) class. These options will be applied to all charts, whatever type of chart. + +With above method you can get all global configurations of [Chart.JS](http://www.chartjs.org/) and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().setResponsive(false); +Defaults.get().getGlobal().setMaintainAspectRatio(true); + +double circumference = Defaults.get().getGlobal().getCircumference(); +CLocale locale = Defaults.get().getGlobal().getLocale(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| aspectRatio | double | 2 | Canvas aspect ratio (i.e. width / height, a value of 1 representing a square canvas). +| autoColors | boolean | `true` | `true` if the chart will cycle through a palette of seven [Chart.JS](http://www.chartjs.org/) brand colors. See [color](../coloring/Colors#default-color-palette) section. +| autoColorsForceOverride | boolean | `false` | `true` if you want to force the auto colors to always color your datasets, for example when using dynamic datasets at runtime. See [color](../coloring/Colors#default-color-palette) section. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(0,0,0,0.1) -          | The default background color to use in the chart. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(0,0,0,0.1) -          | The default border color to use in the chart. +| circumference | double | 360 | The sweep to allow arcs to cover. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #666 -          | The default font color to use in the chart. +| cutoutPercentage | String | `null` | The percentage of the chart that is cut out of the middle. It's a string, ending with '%', as percentage of the chart radius.
See pie and doughnut chart configuration for defaults. +| cutout | double | `Undefined.DOUBLE` | The portion of the chart that is cut out of the middle, in pixels.
See pie and doughnut chart configuration for defaults. +| destroyOnDetach | boolean | `true` | `true` if the chart is configured to be destroyed on the detach from element. +| devicePixelRatio | double | [Window.getDevicePixelRatio()](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/utils/Window.html#getDevicePixelRatio--) | Default device pixel ratio. By default the chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio. +| drawOnAttach | boolean | `true` | `true` if the chart is configured to be draw on the attach of element +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | DefaultEvent.MOUSEMOVE,
DefaultEvent.MOUSEOUT,
DefaultEvent.CLICK,
DefaultEvent.TOUCHSTART,
DefaultEvent.TOUCHMOVE | The events option defines the browser events that the chart should listen to. +| indexAxis | [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) | IndexAxis.X | The base axis for the BAR dataset. Use 'y' for horizontal bar. +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | `CLocale.getDefaults()` | A string with a BCP 47 language tag.
See [INTL locale](../intl/Locale#locale). +| maintainAspectRatio | boolean | `true` | Maintain the original canvas aspect ratio (width / height) when resizing. +| radiusPercentage | String | `100%` | the outer radius of the chart. It's a string, ending with '%', as percentage of the maximum radius. +| radius | double | `Undefined.DOUBLE` | The outer radius of the chart, in pixels. +| resizeDelay | int | 0 | Delay the resize update by give amount of milliseconds. This can ease the resize process by debouncing update of the elements. +| responsive | boolean | `true` | Resizes the chart canvas when its container does. +| responsiveAnimationDuration | int | 0 | Duration in milliseconds it takes to animate to new size after a resize event. +| rotation | double | 0 | The starting angle to draw arcs from. +| showLine | boolean | `true` | If `false`, the lines between points are not drawn. +| skipNull | boolean | `true` | If `true`, null or undefined values will not be drawn +| spanGaps | boolean - double | `false` | If `true`, lines will be drawn between points with no or null data. If `false`, points with `NaN` data will create a break in the line. Can also be a number specifying the maximum gap length to span. The unit of the value depends on the scale used. + +The `options` element is the root node of several other elements you can set to configure the charts as you need. + +## Font + +There are special global settings that can change all fonts on all charts. The global font settings only apply when more specific options are not included in the configuration. + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getFont().setSize(16); + +int size = Defaults.get().getGlobal().getFont().getSize(); +``` + +| Name | Type | Default | Description +| :- | :- | :- | :- +| family | String | "'Helvetica Neue', 'Helvetica', 'Arial', sans-serif" | Font family for all text. +| size | int | 12 | Font size (in px) for text. +| style | [FontStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/FontStyle.html) | FontStyle.NORMAL | Font style for text. +| weight | [Weight](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Weight.html) | Weight.NORMAL | Font weight (boldness) for text.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). +| lineHeight | double - String | 1.2 | Height of an individual line of text.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height). + +## Interaction + +The interaction options are managing the ways how to act on the charts. + +The interaction configuration is passed using the [Hover](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Interaction.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getInteraction().setIntersect(true); + +boolean intersect = Defaults.get().getGlobal().getInteraction().isIntersect(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| axis | [InteractionAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/InteractionAxis.html) | InteractionAxis.X | Define which directions are used in calculating distances. +| intersect | boolean | `true` | if `true`, the hover mode only applies when the mouse position intersects an item on the chart. +| includeInvisible | boolean | `false` | if `true`, the invisible points that are outside of the chart area will also be included when evaluating interactions. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) | DefaultInteractionMode.NEAREST | Sets which elements managed by event or tooltip. + +## Hover + +The hover options are managing the ways how the datasets of the chart can change when hovered. + +The hover configuration is passed using the [Hover](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Hover.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getHover().setIntersect(true); + +boolean intersect = Defaults.get().getGlobal().getHover().isIntersect(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| axis | [InteractionAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/InteractionAxis.html) | InteractionAxis.X | Define which directions are used in calculating distances. +| intersect | boolean | `true` | if `true`, the hover mode only applies when the mouse position intersects an item on the chart. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) | DefaultInteractionMode.NEAREST | Sets which elements will be hovered. + +## Animation + +Animation is used to configure the base options to animate the chart. + +The hover configuration is passed using the [animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Animation.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getAnimation().setDuration(2000); + +int duration = Defaults.get().getGlobal().getAnimation().getDuration(); +``` + +The following animation options are available. + +| Name | Type | Defaults | Description +| :- | :- | :- | :- +| animateRotate | boolean | `true` | If `true`, the chart will animate in with a rotation animation. +| animateScale | boolean | `false` | If `true`, will animate scaling the chart from the center outwards. +| delay | int | Undefined.INTEGER | Delay in milliseconds before starting the animations. +| duration | int | 1000 | The number of milliseconds an animation takes. +| easing | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) | Easing.EASE_OUT_QUART | Easing function to use.
See [Robert Penner's easing equations](http://robertpenner.com/easing/) for more details. +| loop | boolean | `false` | If set to `true`, the animations loop endlessly. + +## Animations + +[Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Animations.html) options configures which element properties are animated and how. + +The animations element is a [container of configurations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html) which can be stored and retrieved by a [key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html). + +To get, change and apply own properties, you can invoke the **set** and **get** methods, as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +// creates my animations key +Key key = Key.create("myKey"); +// creates and gets an animation configuration item by my key +AnimationCollection animationCollection = Defaults.get().getGlobal().getAnimations().create(key); +// sets type +animationCollection.setType(AnimationType.NUMBER); +// sets properties +animationCollection.setProperties(Key.create("borderWidth")); +// sets and gets duration option to the animation configuration +animationCollection.setDuration(2000); + +int duration = animationCollection.getDuration(); + +``` + +The following options are available in [AnimationCollection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html). + +| Name | Type | Defaults | Description +| :- | :- | :- | :- +| delay | int | Undefined.INTEGER | Delay in milliseconds before starting the animations. +| duration | int | 1000 | The number of milliseconds an animation takes. +| easing | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) | Easing.EASE_OUT_QUART | Easing function to use.
See [Robert Penner's easing equations](http://robertpenner.com/easing/) for more details. +| interpolator | [NativeInterpolator](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/NativeInterpolator.html) | - | Enables a custom interpolation during the animations. Only coding in java script for performance reasons. +| loop | boolean | `false` | If set to `true`, the animations loop endlessly. +| properties | String[] - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html)[] | [] | The properties of elements to use to animate. +| type | [AnimationType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AnimationType.html) | AnimationType.NUMBER | Type of property, determines the interpolator used. +| from | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Undefined.BOOLEAN
Undefined.DOUBLE
`null` | Start value for the animation. +| to | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Undefined.BOOLEAN
Undefined.DOUBLE
`null` | End value for the animation. + +## Transitions + +The [transitions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Transitions.html) are a set of animation configuration related to a specific update mode. + +Every [transition animation configuration](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationTransition.html) contains an instance of [Animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Animation.html) and one of [Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Animations.html) to configure the animation for a specific mode. + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +// creates a custom mode +TransitionMode mode = TransitionMode.create("myMode"); +// creates an animation transitions configuration for my mode +AnimationTransition mode = Defaults.get().getGlobal().getTransitions().create(mode); + +// gets animation and animations elements +Animation animation = mode.getAnimation(); + +Animations animations = mode.getAnimations(); +``` + +## Legend + +The chart legend displays data about the datasets that area appearing on the chart. + +The legend configuration is passed using the [Legend](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Legend.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getLegend().setReverse(true); + +boolean reverse = Defaults.get().getGlobal().getLegend().isReverse(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| align | [LegendAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/LegendAlign.html) | LegendAlign.CENTER | Alignment of the legend. +| display | boolean | `true` | If `true`, the legend is shown. +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | `Defaults.get().getGlobal()`
`.getEvents()` | The events option defines the browser events that the legend should listen to. This overrides the options at chart level. +| fullSize | boolean | `true` | Marks that this box should take the full width/height of the canvas (moving other boxes). +| maxHeight | int | Undefined.INTEGER | Maximum height of the legend, in pixels. +| maxWidth | int | Undefined.INTEGER | Maximum width of the legend, in pixels. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | Position.TOP | Position of the legend. +| reverse | boolean | `false` | Legend will show datasets in reverse order. +| rtl | boolean | `false` | `true` for rendering the legends from right to left. +| textDirection | [TextDirection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextDirection.html) | TextDirection.LEFT_TO_RIGHT | This will force the text direction on the canvas for rendering the legend, regardless of the CSS specified on the canvas. + +### Legend labels + +The [Legend Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/LegendLabels.html) configuration is nested below the legend configuration using + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getLegend().getLegendLabels().setPadding(6); + +int padding = Defaults.get().getGlobal().getLegend().getLegendLabels().getPadding(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| borderRadius | int | 0 | Override the borderRadius to use. +| boxHeight | int | `getFont().getSize()` | Height of the colored box. +| boxWidth | int | 40 | Width of colored box. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of label.
See [default colors](DefaultsCharts#commons-charts-options). +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | `Defaults.get().getGlobal()`
`.getFont()` | Font of label.
See [Font](DefaultsCharts#font). +| padding | int | 10 | Padding between rows of colored boxes. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | PointStyle.CIRCLE | This style of point is used for the legend. Only used if `usePointStyle` is `true`. +| pointStyleWidth | double | Undefined.DOUBLE | If `usePointStyle` is `true`, the width of the point style used for the legend. +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.CENTER | Horizontal alignment of the label text. +| useBorderRadius | boolean | `false` | Label border radius will match corresponding border radius. +| usePointStyle | boolean | `false` | Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case). + +### Legend title + +The [legend title](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/LegendTitle.html) configuration is nested below the legend configuration using + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getLegend().getTitle().getPadding().set(6); + +Padding padding = Defaults.get().getGlobal().getLegend().getTitle().getPadding(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of text of title.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `false` | If `true`, the legend title is shown. +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | `Defaults.get().getGlobal()`
`.getFont()` | Font of text of title.
See [Font](DefaultsCharts#font). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 0 to all dimensions | Padding around the title.
See [padding documentation](../configuration/Commons#padding) for more details. + +## Tooltips + +The tooltips configuration is passed using the [tooltips](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Tooltips.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getTooltips().setCornerRadius(8); + +int cornerRadius = Defaults.get().getGlobal().getTooltips().getCornerRadius(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(0,0,0,0.8) -          | Background color of the tooltips. +| bodyColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #fff -          | Color of body text. +| bodyFont | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | See description | Font of body text. The default value is the global font with the style set to FontStyle.NORMAL.
See [Font](DefaultsCharts#font). +| bodyAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.LEFT | Alignment of body element of the tooltips. +| bodySpacing | int | 2 | Spacing to add to top and bottom of each tooltip item. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(0,0,0,0) -          | Color of the border. +| borderWidth | int | 0 | Size of the border. +| boxWidth | int | `getBodyFont().getSize()` | Width of the color box if `displayColors` is `true`. +| boxHeight | int | `getBodyFont().getSize()` | Height of the color box if `displayColors` is `true`. +| caretPadding | int | 2 | Extra distance to move the end of the tooltip arrow away from the tooltip point. +| caretSize | int | 5 | Size, in px, of the tooltip arrow. +| cornerRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 6 | Radius of tooltip corner curves. +| displayColors | boolean | `true` | If `true`, color boxes are shown in the tooltip. +| enabled | boolean | `true` | If `true`, the tooltips are enabled. +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | `Defaults.get().getGlobal()`
`.getEvents()` | The events option defines the browser events that the tooltip should listen to. This overrides the options at chart level. +| footerColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #fff -          | Color of the footer. +| footerFont | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | See description | Font of footer text. The default value is the global font with the style set to Weight.BOLD.
See [Font](DefaultsCharts#font). +| footerAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.LEFT | Alignment of footer element of the tooltips. +| footerMarginTop | int | 6 | Margin to add before drawing the footer. +| footerSpacing | int | 2 | Spacing to add to top and bottom of each footer line. +| intersect | boolean | `Defaults.get().getGlobal()`
`.getInteraction().isIntersect()` | if `true`, the tooltip mode applies only when the mouse position intersects with an element. If `false`, the mode will be applied at all times. +| mode | String - [IsInteractionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsInteractionMode.html) | `Defaults.get().getGlobal()`
`.getInteraction().getMode()` | Sets which elements appear in the tooltip. +| multiKeyBackground | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #fff -          | Color to draw behind the colored boxes when multiple items are in the tooltip. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 6 to all dimensions | The padding to add inside the tooltip.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [TooltipPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipPosition.html) | TooltipPosition.AVERAGE | The mode for positioning the tooltip. +| rtl | boolean | `false` | `true` for rendering the tooltips from right to left. +| textDirection | [TextDirection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextDirection.html) | TextDirection.LEFT_TO_RIGHT | This will force the text direction on the canvas for rendering the tooltips, regardless of the CSS specified on the canvas +| titleColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #fff -          | Color of the footer. +| titleFont | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | See description | Font of title text. The default value is the global font with the style set to Weight.BOLD.
See [Font](DefaultsCharts#font). +| titleAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.LEFT | Alignment of title element of the tooltips. +| titleMarginBottom | int | 6 | Margin to add on bottom of title section. +| titleSpacing | int | 2 | Spacing to add to top and bottom of each title line. +| usePointStyle | boolean | `false` | Use the corresponding point style (from dataset options) instead of color boxes (size is based on the minimum value between box width and box height). +| xAlign | [TooltipAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipAlign.html) | TooltipAlign.AUTO | Position of the tooltip caret in the X direction.
Can accept only TooltipAlign.LEFT, TooltipAlign.CENTER and TooltipAlign.RIGHT. +| yAlign | [TooltipAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TooltipAlign.html) | TooltipAlign.AUTO | Position of the tooltip caret in the Y direction.
Can accept only TooltipAlign.TOP, TooltipAlign.CENTER and TooltipAlign.BOTTOM. + +## Title + +The chart title defines text to draw at the top of the chart. + +The title configuration is passed using the [Title](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Title.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getTitle().getPadding().set(12); + +Padding padding = Defaults.get().getGlobal().getTitle().getPadding(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| align | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) | ElementAlign.CENTER | Alignment of the title. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of text of the title.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `false` | If `true`, the title is shown. +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | See description | Font of title text. The default value is the global font with the style set to Weight.BOLD.
See [Font](DefaultsCharts#font). +| fullSize | boolean | `true` | Marks that this box should take the full width/height of the canvas (moving other boxes). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 10 to all dimensions | Number of pixels to add above and below the title text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | Position.TOP | Position of title. + +## Subtitle + +The chart subtitle defines text to draw at the bottom of the chart title. + +The subtitle configuration is passed using the [Title](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Subtitle.html) object in the defaults one: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getSubtitle().getPadding().set(12); + +Padding padding = Defaults.get().getGlobal().getSubtitle().getPadding(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| align | [ElementAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ElementAlign.html) | ElementAlign.CENTER | Alignment of the subtitle. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of text of the subtitle.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `false` | If `true`, the title is shown. +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | See description | Font of subtitle text. The default value is the global font with the style set to Weight.NORMAL.
See [Font](DefaultsCharts#font). +| fullSize | boolean | `true` | Marks that this box should take the full width/height of the canvas (moving other boxes). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 0 to all dimensions | Number of pixels to add above and below the subtitle text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | Position.TOP | Position of subtitle. + +## Elements + +Options can be configured for four different types of elements: **[arc](#arc)**, **[lines](#line)**, **[points](#point)**, and **[bar](#bar)**. + +The [elements](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Elements.html) configuration is nested in the global configuration as following: + +```java +Defaults.get().getGlobal().getElements(); +``` + +### Point + +Point element is used to represent the points, like in a line or bubble charts. + +The [point](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Point.html) configuration is nested in the elements configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getElements().getPoint().setRadius(6); + +int radius = Defaults.get().getGlobal().getElements().getPoint().getRadius(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | Point fill color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | Point stroke color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderWidth | int | 1 | Point stroke width. +| hitRadius | int | 1 | Extra radius added to point radius for hit detection. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `backgroundColor` | Point fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `borderColor` | Point stroke color when hovered. +| hoverBorderWidth | int | See `borderWidth` | Stroke width when hovered. +| hoverRadius | int | 4 | Point radius when hovered. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | PointStyle.CIRCLE | Point style. +| radius | int | 3 | Point radius. +| rotation | double | 0 | The point rotation (in degrees). + +### Line + +Line element is used to represent the line, like in a line or radar charts. + +The [line](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Line.html) configuration is nested in the elements configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getElements().getLine().setTesion(0.4D); + +double tension = Defaults.get().getGlobal().getElements().getLine().getTesion(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | Line fill color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT | Determines the shape used to draw the end points of lines.
See [MDN](https://developer.mozilla.org/en/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | Line stroke color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderDash | int[] | [] | The line dash pattern used when stroking lines. It uses an array of values that specify alternating lengths of lines and gaps which describe the pattern.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0D | Line dash offset.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | The shape used to join two line segments where they meet.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | 3 | Line stroke width. +| capBezierPoints | boolean | `true` | Set true` to keep Bezier control inside the chart, `false` for no restriction. +| cubicInterpolationMode | [CubicInterpolationMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CubicInterpolationMode.html) | CubicInterpolationMode.DEFAULT | Interpolation mode to apply. +| fill | String - int - boolean - [IsFill](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsFill.html) | Fill.FALSE | How to fill the area under the line.
See [Filling modes](../coloring/Colors#filling-modes) +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `backgroundColor` | Line fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `borderColor` | Line stroke color when hovered. +| hoverBorderWidth | int | See `borderWidth` | Stroke width when hovered. +| stepped | boolean - [Stepped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Stepped.html) | Stepped.FALSE | If the line is shown as a stepped line. +| tension | double | 0 | Bezier curve tension (`0` for no Bezier curves). + +### Arc + +Arc element is used in the polar area, doughnut and pie charts. + +The [Arc](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Arc.html) configuration is nested in the elements configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getElements().getArc().setBorderWidth(4); + +int borderWidth = Defaults.get().getGlobal().getElements().getArc().getBorderWidth(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| angle | double | `Double.NaN` | Arc angle to cover, for polar chart only. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | Arc fill color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderAlign | [BorderAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderAlign.html) | BorderAlign.CENTER | Arc stroke alignment. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | #fff -          | Arc stroke color. +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.BEVEL | Arc line join style. The default is JoinStyle.ROUND when `borderAlign` is BorderAlign.INNER.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderRadius | int | 0 | The arc border radius (in pixels). +| borderWidth | int | 2 | Arc stroke width. +| circular | boolean | `true` | If the arc is curved. If `false` the arc will be flat. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `backgroundColor` | Arc fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `borderColor` | Arc stroke color when hovered. +| hoverBorderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.BEVEL | Arc line join style when hovered.
See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| hoverBorderWidth | int | See `borderWidth` | Stroke width when hovered. +| hoverOffset | int | See `offset` | The offset of the arc (in pixels) when hovered. +| offset | int | 0 | The offset of the arc (in pixels). +| spacing | int | 0 | Fixed arc offset (in pixels). Similar to `offset` but applies to all arcs. + +### Bar + +Bar element is used to represent the bars in a bar chart. + +The [bar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Bar.html) configuration is nested in the elements configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getElements().getBar().setBorderWidth(4); + +int borderWidth = Defaults.get().getGlobal().getElements().getBar().getBorderWidth(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| autoInflateAmount | boolean | `true` | If `true`, the amount of pixels to inflate the bar rectangles, when drawing, is automatically calculating. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | Bar fill color.
See [default colors](DefaultsCharts#commons-charts-options). +| base | double | Undefined.DOUBLE | Base value for the bar in data units along the value axis. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()`) | Bar stroke color.
See [default colors](DefaultsCharts#commons-charts-options). +| borderRadius | int | 0 | The bar border radius (in pixels). +| borderSkipped | boolean - [BorderSkipped](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/BorderSkipped.html) | BorderSkipped.START | The edge to skip when drawing bar. +| borderWidth | int | 0 | The bar border width (in pixels). +| enableBorderRadius| boolean | `true` | If `true`, it only shows the border radius of a bar when the bar is at the end of the stack. +| hoverBackgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `backgroundColor` | Bar fill color when hovered. +| hoverBorderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | See `borderColor` | Bar stroke color when hovered. +| hoverBorderWidth | int | See `borderWidth` | Stroke width when hovered. +| hoverBorderRadius | int | See `borderRadius` | The bar border radius (in pixels) when hovered. +| inflateAmount | int | Undefined.INTEGER | The amount of pixels to inflate the bar rectangles, when drawing. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | PointStyle.CIRCLE | Point style for legend. + +## Datasets + +The datasets options are managing the set options which will affect the datasets management. + +The [datasets](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Datasets.html) configuration is nested in the global configuration using: + +```java +// -------------------------------------- +// GLOBAL, for all charts of the same type +// -------------------------------------- +Defaults.get().getOptions(ChartType.LINE).getDatasets().get(ChartType.LINE).setShowLine(true); + +boolean globalShowLine = Defaults.get().getOptions(ChartType.LINE).getDatasets().get(ChartType.LINE).isShowLine(); +``` + +The datasets configuration is passed using the [Datasets](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Datasets.html) object in the chart options and mapped to [TypedDataset](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/TypedDataset.html). + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| animation | [Animation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animation.html) | - | See [animation options](#animation) section for more details. +| animations | [Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animations.html) | - | See [animation options](#animations) section for more details. +| barPercentage | double | 0.9 | Percent (0-1) of the available width each bar should be within the category width. 1.0 will take the whole category width and put the bars right next to each other. +| categoryPercentage | double | 0.8 | Percent (0-1) of the available width each category should be within the sample width. +| barThickness | int | 0 | Manually set width of each bar in pixels.
If set to [DefaultDatasets.FLEX_BAR_THICKNESS](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/defaults/globals/DefaultDatasets.html#FLEX_BAR_THICKNESS), it computes "optimal" sample widths that globally arrange bars side by side.
If not set (default), bars are equally sized based on the smallest interval. +| grouped | boolean | `true` | Should the bars be grouped on index axis.
When `true`, all the datasets at same index value will be placed next to each other centering on that index value.
When `false`, each bar is placed on its actual index-axis value. +| maxBarThickness | int | 0 | Set this to ensure that bars are not sized thicker than this. +| minBarLength | int | 0 | Set this to ensure that bars have a minimum length in pixels. +| showLine | boolean | `true` | If `true`, the line is drawn for dataset. +| transitions | [Transitions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Transitions.html) | - | See [animation options](#transitions) section for more details. + +## Layout + +Options can be configured for the the padding to add inside the chart. + +The [layout](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Layout.html) configuration is nested in the global configuration using: + +```java +// gets layout instance +Layout layout = Defaults.get().getGlobal().getLayout(); +``` + +The [padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) configuration is nested in the layout configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getLayout().getPadding().setTop(10); +// to set same padding value to all sides of the chart +Defaults.get().getGlobal().getLayout().getPadding().set(10); + +int paddingTop = Defaults.get().getGlobal().getLayout().getPadding().getTop(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| autoPadding | boolean | `true` | If `true`, apply automatic padding so visible elements are completely drawn. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | `0` on all sides | To set specific padding for specific sides. + +See [padding documentation](../configuration/Commons#padding) for more details. + +## Decimation + +The decimation element can be used with line charts to automatically decimate data at the start of the chart life cycle. + +Before enabling it, review the [requirements](#requirements) to ensure that it will work with the chart you want to create. + +The [decimation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Decimation.html) configuration is nested in the global configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getDecimation().setSamples(1000); + +double samples = Defaults.get().getGlobal().getDecimation().getSamples(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| enabled | boolean | `false` | If `true`, the data decimation is enabled. +| algorithm | [DecimationAlgorithm](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DecimationAlgorithm.html) | DecimationAlgorithm.MIN_MAX | Decimation algorithm to use. +| samples | double | Undefined.DOUBLE | If the `DecimationAlgorithm.LTTB` is used, this is the number of samples in the output dataset. Defaults to the canvas width to pick 1 sample per pixel. +| threshold | double | Undefined.DOUBLE | If the number of samples in the current axis range is above this value, the decimation will be triggered.
Defaults to 4 times the canvas width.
The number of point after decimation can be higher than the `threshold` value. + +### Algorithms + +The available decimation algorithms to use for data are the following: + +* `DecimationAlgorithm.MIN_MAX`: it will preserve peaks in your data but could require up to 4 points for each pixel. This type of decimation would work well for a very noisy signal where you need to see data peaks. +* `DecimationAlgorithm.LTTB` (Largest Triangle Three Bucket): it reduces the number of data points significantly. This is most useful for showing trends in data using only a few data points. + +### Requirements + +To use the decimation, the following requirements must be met: + +1. The dataset must have an [IndexAxis](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IndexAxis.html) of `IndexAxis.X`. +2. The dataset must be a [line](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/LineDataset.html). +3. The X axis for the dataset must be either a [linear](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianLinearAxis.html) or [time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/CartesianTimeAxis.html) axis. + +## Filler + +Filler element configures the engine which is in charge to manage the filling of the datasets, by the property `fill`. See [here](../coloring/Colors#filling) how filling a dataset. + +The [filler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Filler.html) configuration is nested in the global configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all charts (whatever type) +// -------------------------------------- +Defaults.get().getGlobal().getFiller().setPropagate(false); + +boolean propagate = Defaults.get().getGlobal().getFiller().isPropagate(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| propagate | boolean | `true` | If `true`, the fill area will be recursively extended to the visible target defined by the fill value of hidden data set targets. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/DrawTime.html) | DrawTime.BEFORE_DATASET_DRAW | Filler draw time. diff --git a/versioned_docs/version-6.5/defaults/DefaultsScales.md b/versioned_docs/version-6.5/defaults/DefaultsScales.md new file mode 100644 index 000000000..c2b85d309 --- /dev/null +++ b/versioned_docs/version-6.5/defaults/DefaultsScales.md @@ -0,0 +1,327 @@ +--- +id: DefaultsScales +title: Defaults scales options +hide_title: true +sidebar_label: Scales +--- + +## Commons scales options + +To change the global scale, **Charba** is providing the method `getScale` in the [defaults](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/Defaults.html). + +With this method you can get all global configuration of [Chart.JS](http://www.chartjs.org/) for [scale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/GlobalScale.html) (common one, not related to chart type) and you have got all `set` and `get` methods to change or retrieve the global configuration items. + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().setStacked(true); + +boolean stacked = Defaults.get().getScale().isStacked(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| alignToPixels | boolean | `false` | Align pixel values to device pixels. +| animate | boolean | `true` | If `true`, animate scaling the chart from the center. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(255,255,255,0) -          | The background color of scale area. +| beginAtZero | boolean | `false` | If `true`, scale will include 0 if it is not already included. +| bounds | [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) | Bounds.TICKS | Determines the scale bounds on time axis. +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | Display.TRUE | If `Display.TRUE`, the axis is shown. +| grace | int | 0 | Amount of pixels for added room in the scale range above and below data. +| graceAsPercentage | double | 0 | Sets a value, between 0 and 1, as percentage, for added room in the scale range above and below data. +| labels | [Labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/Labels.html) | empty `Labels` | The labels to display. +| max | double - String - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | See description | User defined maximum number for the scale, overrides maximum value from data.
As value, you can set a:
- `double` for linear, logarithmic and radial scales, with `Double.MAX_VALUE` as default;
- `Date` for time and time series scales, with `null` as default;
- `String` for category scales, with `null` as default. +| min | double - String - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | See description | User defined minimum number for the scale, overrides minimum value from data.
As value, you can set a:
- `double` for linear, logarithmic and radial scales, with `Double.MIN_VALUE` as default;
- `Date` for time and time series scales, with `null` as default;
- `String` for category scales, with `null` as default. +| offset | boolean | `false` | If `true`, extra space is added to the both edges and the axis is scaled to fit in the chart area. +| offsetAfterAutoskip | boolean | `false` | If `true`, bar chart offsets are computed with auto skipped ticks. +| position | [Position](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Position.html) | Position.TOP | Position of the axis. +| reverse | boolean | `false` | Reverses order of tick labels. +| singleStacked | boolean | `false` | If you might want to stack positive and negative values together. +| stack | String | Undefined.STRING | Sets the stack group. Axes at the same `position` with same `stack` are stacked. +| stacked | boolean | `false` | If the axis are stacked. +| stackWeight | double | 1 | Sets the weight of the scale in stack group. Used to determine the amount of allocated space for the scale within the group. +| startAngle | double | 0 | Starting angle to draw arcs for the first item in a data set. In degrees, 0 is at top. +| suggestedMax | double - String - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | See description | Adjustment used when calculating the maximum data value.
As value, you can set a:
- `double` for linear, logarithmic and radial scales, with `Double.MAX_VALUE` as default;
- `Date` for time and time series scales, with `null` as default;
- `String` for category scales, with `null` as default. +| suggestedMin | double - String - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | See description | Adjustment used when calculating the minimum data value.
As value, you can set a:
- `double` for linear, logarithmic and radial scales, with `Double.MIN_VALUE` as default;
- `Date` for time and time series scales, with `null` as default;
- `String` for category scales, with `null` as default. +| weight | double | 0 | The weight used to sort the axis. Higher weights are further away from the chart area. + +The [Bounds](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Bounds.html) controls the scale boundary strategy (bypassed by min/max time options): + + * `Bounds.DATA`: make sure data are fully visible, labels outside are removed. + * `Bounds.TICKS`: make sure ticks are fully visible, data outside are truncated. + +## Grid + +The grid configuration defines options for the lines that are run perpendicular to the axis. + +The [grid](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Grid.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getGrid().setCircular(true); + +boolean circular = Defaults.get().getScale().getGrid().isCircular(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| circular | boolean | `false` | If `true`, grid lines are circular (on radar chart only). +| color | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | The color of the grid lines. If specified as an array, the first color applies to the first grid line, the second to the second grid line and so on.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `true` | If `false`, do not display grid lines for this axis. +| drawOnChartArea | boolean | `true` | If `true`, draw lines on the chart area inside the axis lines. This is useful when there are multiple axes and you need to control which grid lines are drawn. +| drawTicks | boolean | `true` | If `true`, draw lines beside the ticks in the axis area beside the chart. +| lineWidth | int - int[] | 1 | Stroke width of grid lines. +| offset | boolean | `false` | If `true`, grid lines will be shifted to be between labels. This is set to `true` in the bar chart by default. +| tickBorderDash | int[] | See description | Length and spacing of the tick mark line. If not set, defaults to the grid line `borderDash` value. +| tickBorderDashOffset | double - double[] | See description | Offset for the line dash of the tick mark. If unset, defaults to the grid line `borderDashOffset` value +| tickColor | String - String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | See description | Color of the tick line. If unset, defaults to the grid line `color`. +| tickLength | int | 10 | Length in pixels that the grid lines will draw in the axis area. +| tickWidth | int - int[] | See description | Width of the tick mark in pixels. If unset, defaults to the grid line `lineWidth`. +| z | int | -1 | z-index of the grid line layer. Values less than or equals to 0 are drawn under datasets, greater than 0 on top. + +## Border + +The [border](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleBorder.html) defines options for the border that run perpendicular to the axis. + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getBorder().setDisplay(true); +Defaults.get().getScale().getBorder().setColor(HtmlColor.RED); + +boolean display = Defaults.get().getScale().getBorder().isDisplay(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| display | boolean | `true` | If `true`, draw border at the edge between the axis and the chart area. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | If set, used as the color of the border line. +| dash | int[] | [] | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| dashOffset | double | 0 | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| width | int | 1 | If set, used as the width of the border line. +| z | int | 0 | z-index of the border layer. Values less than or equals to 0 are drawn under datasets, greater than 0 on top. + +## Ticks + +The tick configuration defines options for the tick marks that are generated by the axis. + +The [ticks](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Ticks.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getTicks().setAutoSkip(false); + +boolean autoSkip = Defaults.get().getScale().getTicks().isAutoSkip(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| align | [TickAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickAlign.html) | TickAlign.CENTER | The tick alignment along the axis. +| autoSkip | boolean | `true` | If `true`, automatically calculates how many labels that can be shown and hides labels accordingly. Labels will be rotated up to `maxRotation` before skipping any. Turn `autoSkip` off to show all labels no matter what. +| autoSkipPadding | int | 3 | The padding between the ticks on the horizontal axis when autoSkip is enabled. +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(255,255,255,0.75) -          | Color of label backdrops. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 2 to all dimensions | The padding of label backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of ticks.
See [default colors](DefaultsCharts#commons-charts-options). +| count | int | UnefinedValues.INTEGER | The number of ticks to generate. If specified, this overrides the automatic generation. +| crossAlign | [CrossAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CrossAlign.html) | CrossAlign.NEAR | The tick alignment perpendicular to the axis. +| display | boolean | `true` | If `true`, the tick marks are shown. +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | `Defaults.get().getGlobal()`
`.getFont()` | Font of ticks.
See [Font](DefaultsCharts#font). +| includeBounds | boolean | `true` | If `true`, the defined `min` and `max` values should be presented as ticks even if they are not "nice". +| labelOffset | int | 0 | Distance in pixels to offset the label from the centre point of the tick (in the x-direction for the x-axis, and the y-direction for the y-axis).

Note: *This can cause labels at the edges to be cropped by the edge of the canvas*. +| maxRotation | int | 50 | The maximum rotation for tick labels when rotating to condense labels.

Note: *Rotation doesn't occur until necessary and only applicable to horizontal scales.* +| maxTicksLimit | int | 11 | Maximum number of ticks and gridlines to show. +| minRotation | int | 0 | The minimum rotation for tick labels. +| mirror | boolean | `false` | The flips tick labels around axis, displaying the labels inside the chart instead of outside.

Note: *Only applicable to vertical scales.* +| numberFormat | [NumberFormatOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/NumberFormatOptions.html) | | The number format options used by the default label formatter.
See [INTL number format](../intl/NumberFormat) documentation. +| padding | int | 0 | The padding between the tick label and the axis. +| precision | int | 0 | If defined and `stepSize` is not specified, the step size will be rounded to this many decimal places. +| sampleSize | int | Undefined.INTEGER | The number of ticks to examine when deciding how many labels will fit. Setting a smaller value will be faster, but may be less accurate when there is large variability in label length. +| showLabelBackdrop | boolean | `true` | If `true`, draw a background behind the tick labels +| source | [TickSource](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TickSource.html) | TickSource.AUTO | How ticks are generated on axis time. +| stepSize | double | `Double.MIN_VALUE` | User defined fixed step size for the scale. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | The color of the stroke around the text. +| textStrokeWidth | int | 0 | Stroke width around the text. +| z | int | 0 | z-index of tick layer. Useful when ticks are drawn on chart area. Values less than or equals to 0 are drawn under data sets, greater than 0 on top. + +### Major Tick + +The major tick configuration enables for the major tick marks that are generated by the axis. A major tick will affect auto-skipping and major will be defined on ticks in the scriptable options context, by [ScaleTickItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleTickItem.html) class and [isMajor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ScaleTickItem.html#isMajor--) method. + +The major ticks configuration is nested in the ticks configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getTicks().getMajor().setEnabled(true); + +boolean enabled = Defaults.get().getScale().getTicks().getMajor().isEnabled(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| enabled | boolean | `false` | If `true`, major ticks marks are generated. + +## Title + +The scale title configuration defines options for the title of the scale. Note that this only applies to cartesian axes. + +The [scale title](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleTitle.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getTitle().setColor(HtmlColor.RED); + +IsColor color = Defaults.get().getScale().getTitle().getColor(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| align | [ScaleTitleAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/ScaleTitleAlign.html) | ScaleLabelAlign.CENTER | Alignment of the scale label. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of scale label.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `false` | If `true`, the scale label is shown. +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | `Defaults.get().getGlobal()`
`.getFont()` | Font of scale label.
See [Font](DefaultsCharts#font). +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 4 to all dimensions | The padding of title. Only `top` and `bottom` are implemented.
See [padding documentation](../configuration/Commons#padding) for more details. + +## AngleLines + +The angle lines options are used to configure angled lines that are radiated from the center of the chart to the point labels. + +The [angle lines](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AngleLines.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getAngleLines().setLineWidth(2); + +int lineWidth = Defaults.get().getScale().getAngleLines().getLineWidth(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| borderDash | int[] | [] | Length and spacing of dashes on grid lines. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBorderColorAsString()` | Color of angled lines.
See [default colors](DefaultsCharts#commons-charts-options). +| display | boolean | `true` | If `true`, angle lines are shown. +| lineWidth | int | 1 | Width of angled lines. + +## PointLabels + +The point labels options are used to configure the point labels that are shown on the perimeter of the scale. + +The [point labels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/PointLabels.html) configuration is nested in the scale configuration as following + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getPointLabels().setColor(HtmlColor.RED); + +IsColor color = Defaults.get().getScale().getPointLabels().getColor(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| backdropColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getBackgroundColorAsString()` | Background color of the point label. +| backdropPadding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Padding.html) | 2 to all dimensions | The padding of label backdrop.
See [padding documentation](../configuration/Commons#padding) for more details. +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 0 | The border radius of the point label (in pixels). +| display | boolean - [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | `true` | If `true`, point labels are shown. When Display.AUTO, the label is hidden if it overlaps with another label. +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | Color of point labels.
See [default colors](DefaultsCharts#commons-charts-options). +| font | [Font](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Font.html) | `Defaults.get().getGlobal()`
`.getFont()` | Font of point labels.
See [Font](DefaultsCharts#font). +| padding | int | 5 | Padding between chart and point labels, in pixel. + +## Time + +The time options are used to configure the time axis. + +The [time](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Time.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getTime().setUnit(TimeUnit.DAY); + +TimeUnit unit = Defaults.get().getScale().getTime().getUnit(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| isoWeekday | [IsoWeekDay](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/IsoWeekDay.html) | IsoWeekDay.SUNDAY | The first day of the week. +| minUnit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | TimeUnit.MILLISECOND | The minimum display format to be used for a time unit. +| parser | String | `null` | Interpreted as a custom format to be used to parse the date. +| round | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | `null` | If defined, dates will be rounded to the start of this unit. +| stepSize | int | 1 | The number of units between grid lines. +| tooltipFormat | String | `null` | Format string to use for the tooltip. +| unit | [TimeUnit](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TimeUnit.html) | `null` | If defined, will force the unit to be a certain type. + +For more details, have a look how to configure a [cartesian time axis](../axes/CartesianTimeAxes). + +### Display formats + +The display formats are used to configure how different time units are formed in the strings for the axis tick marks. + +The [display formats](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/DisplayFormats.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +// changes the default format (of date adapter) of a time unit +Defaults.get().getScale().getTime().getDisplayFormats().setDisplayFormat(TimeUnit.HOUR, "hh:MM:00"); + +String displayFormat = Defaults.get().getScale().getTime().getDisplayFormats().getDisplayFormat(TimeUnit.HOUR); +``` + +## Adapters + +The adapters options are used to configure the adapter for external date library if that adapter needs or supports options. The options are leveraging in [INTL](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) framework + +The [adapters options](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/Adapters.html) configuration is nested in the scale configuration as following: + +```java +// -------------------------------------- +// GLOBAL, for all scales (whatever type) +// -------------------------------------- +Defaults.get().getScale().getAdapters().setLocale(CLocale.ITALY); + +CLocale locale = Defaults.get().getScale().getAdapters().getLocale(); +``` + +The following are the attributes that you can set: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| locale | [CLocale](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/CLocale.html) | `null` | Using locale specifying the language to use generating or interpreting strings. +| zone | [TimeZone](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/TimeZone.html) | `null` | Implementation recognizes the time zone names of the IANA time zone database. +| outputCalendar | [Calendar](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/Calendar.html) | `null` | The calendar type to use. +| numberingSystem | [NumberingSystem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/intl/enums/NumberingSystem.html) | `null` | The numbering system to use. + +For more details, have a look how to configure a [Luxon](../DateAdapters#Luxon) date adapters and the [locale](../intl/Locale) documentation. diff --git a/versioned_docs/version-6.5/extensions/Annotation.md b/versioned_docs/version-6.5/extensions/Annotation.md new file mode 100644 index 000000000..52ff65aba --- /dev/null +++ b/versioned_docs/version-6.5/extensions/Annotation.md @@ -0,0 +1,1677 @@ +--- +id: Annotation +title: Annotation plugin +hide_title: true +sidebar_label: Annotation +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Annotation plugin + +**Charba** provides out of the box the feature to enable [Annotation](https://github.com/chartjs/chartjs-plugin-annotation) which can add annotations on a chart instance. + +It can draw lines, boxes, points, labels, polygons and ellipses on the chart area. + +The annotation plugin work with line, bar, scatter and bubble charts that use linear, logarithmic, time or category scales. + + + +:::info +The annotation plugin will not work on any chart that does not have exactly two axes, including pie, radar and polar area charts. +::: + +## Activation + +The annotation plugin is injected directly in the document. + +The plugin ID is a constant everywhere available, `AnnotationPlugin.ID`, in [AnnotationPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationPlugin.html) entry point. + +This plugin registers itself globally, meaning that once injected, all charts will display annotations. In case you want it enabled only for a few charts, you can enable it as following: + +```java +// -------------------------------------- +// enabling the plugin without any parameter +// the plugin is NOT registered to all charts +// -------------------------------------- +AnnotationPlugin.enable(); + +// -------------------------------------- +// enabling the plugin with `true` parameter +// the plugin is registered to all charts +// -------------------------------------- +AnnotationPlugin.enable(true); +``` + +To activate the plugin in a specific chart, it's enough to provide the configuration options (see [below](#configuration)) or enabling it by: + +```java +// -------------------------------------- +// ENABLING the plugin to a chart instance +// storing a plugin options +// -------------------------------------- +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// sets default draw time +options.setDrawTime(DrawTime.BEFORE_DRAW); +// stores the plugin options directly by the options +options.store(chart); + +// -------------------------------------- +// ENABLING the plugin to a chart instance +// by a boolean using default plugin +// options +// -------------------------------------- +chart.getOptions().getPlugins().setEnabled(AnnotationPlugin.ID, true); +``` + +## Configuration + +The plugin options can be changed at 2 different levels and are evaluated with the following priority: + + * per chart by `chart.getOptions().getPlugins().setOptions` method + * or globally by `Defaults.get().getGlobal().getPlugins().setOptions` method + +The configuration [AnnotationOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptions.html) class is the entry point of plugin configuration. + +```java +// ------------------------- +// CONFIGURES the annotation +// by AnnotationId id +// ------------------------- +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +... // additional label configuration +// sets the line annotation to the options +options.setAnnotations(line); +// stores the plugin options directly by the options +options.store(); +``` + +You can also change the default for all charts instances, as following: + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +... // additional label configuration +// sets the line annotation to the options +options.setAnnotations(line); + +// -------------------------------------- +// STORING plugin options +// -------------------------------------- +// stores the plugin options by plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(AnnotationPlugin.ID, options); +// stores the plugin options without plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(options); +// stores the plugin options directly by the options +options.store(); +``` + +If you need to read the plugin options, there is the specific factory, [AnnotationOptionsFactory](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptionsFactory.html) as static reference inside the [AnnotationPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationPlugin.html) entry point which can be used to retrieve the options from chart as following: + +```java +// gets options reference +AnnotationOptions options; + +// -------------------------------------- +// GETTING plugin options from chart +// -------------------------------------- +if (chart.getOptions().getPlugin().hasOptions(AnnotationPlugin.ID)){ + // retrieves the plugin options by plugin ID + options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.ID, AnnotationPlugin.FACTORY); + //retrieves the plugin options without plugin ID + options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.FACTORY); +} +``` + +### Default element options + +Every annotation type is a chart element and the common options for a specific type can be configured by elements in the chart and global options: + + * per chart by `chart.getOptions().getElements().getElement(ElementFactory)` method + * or globally by `Defaults.get().getGlobal().getElements().getElement(ElementFactory)` method + +The annotation options are providing a [ElementFactory](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ElementFactory.html) instance in order to enable to get and change the options at annotation type level. + +```java +// ---------------------------------------------------- +// Setting option for all box annotations of the chart +// ---------------------------------------------------- +BoxAnnotation boxElement = chart.getOptions().getElements().getElement(BoxAnnotation.FACTORY); +// checks if consistent +if (boxElement != null) { + // set font family for all box labels of the chart + boxElement.getLabel().getFont().setFamily("courier"); +} +// ---------------------------------------------------- +// Setting option for all box annotations +// ---------------------------------------------------- +BoxAnnotation boxElement = Defaults.get().getGlobal().getElements().getElement(BoxAnnotation.FACTORY); +// checks if consistent +if (boxElement != null) { + // set font family for all box labels of all charts + boxElement.getLabel().getFont().setFamily("courier"); +} +``` + +:::caution +If the annotation plugin is not activated (see [Activation](#activation)), the annotation element options can not be set because the result will be always an inconsistent options instance. +::: + +## Identifier + +Every annotation configuration can be add to the [AnnotationOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptions.html), assigning a unique identifier. + +The identifier of a label configuration can be set by a string or by a specific class, [AnnotationId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationId.html). + +```java +// ------------------------- +// CONFIGURES the annotation +// by AnnotationId id +// ------------------------- +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates annotation id +AnnotationId annotationId = AnnotationId.create("myAnnotation1"); +// creates and adds a line annotation by "myAnnotation1" id +LineAnnotation line = new LineAnnotation(annotationId); +// configures the line annotation +line.setDrawTime(DrawTime.AFTER_DATASETS_DRAW); +line.setBorderColor(HtmlColor.BLACK); +line.setBorderWidth(5); +... // additional label configuration +// sets the line annotation to the options +options.setAnnotations(line); +// stores the plugin options directly by the options +options.store(); +``` + +:::caution +If the annotation id is not provided, a unique id for the annotation is created automatically, which can be retrieve by `getId()` method of the annotation. +::: + +You can access to the configured annotations configurations as following: + +```java +// ------------------------ +// GETS the configured +// annotations +// ------------------------ +// retrieves the plugin options by plugin ID +AnnotationOptions options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.FACTORY); +// gets all annotations configurations +List allAnnotations = options.getAnnotations(); +// gets "myAnnotation1" annotation configuration +AbstractAnnotation annotation1 = options.getAnnotation(AnnotationId.create("myAnnotation1")); +// gets "myAnnotation2" annotation configuration +AbstractAnnotation annotation2 = options.getAnnotation("myAnnotation2"); +``` + +## Options + +The configuration class [AnnotationOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptions.html) contains all properties needed to configure the plugin. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// sets default draw time +options.setDrawTime(DrawTime.BEFORE_DRAW); +``` + +The following options are available at the top level. They apply to all annotations unless they are overwritten on a per-annotation basis: + +| Name | Type | Default | Description +| :- | :- | :- | :- +| animations | [Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Animations.html) | - | See [animation options](#animations) section for more details. +| clip | boolean | `true` | If `true`, the annotations are clipped to the chart area. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.AFTER_DATASETS_DRAW | Defines when the annotations are drawn. This allows positioning of the annotation relative to the other elements of the graph. +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | `Defaults.get().getGlobal()`
`.getEvents()` | The events option defines the browser events that the plugin should listen to. This overrides the options at chart level. +| interaction | [Interaction](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/Interaction.html) | [see below](#interaction) | To configure which events trigger plugin interactions. + +### Animations + +[Animations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/Animations.html) options configures which element properties are animated and how. + +The animations element is a [container of configurations](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html) which can be stored and retrieved by a [key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html). + +The following options are available in [AnimationCollection](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/AnimationCollection.html). + +| Name | Type | Defaults | Description +| :- | :- | :- | :- +| delay | int | Undefined.INTEGER | Delay in milliseconds before starting the animations. +| duration | int | 1000 | The number of milliseconds an animation takes. +| easing | [Easing](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Easing.html) | Easing.EASE_OUT_QUART | Easing function to use.
See [Robert Penner's easing equations](http://robertpenner.com/easing/) for more details. +| interpolator | [NativeInterpolator](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/NativeInterpolator.html) | - | Enables a custom interpolation during the animations. Only coding in java script for performance reasons. +| loop | boolean | `false` | If set to `true`, the animations loop endlessly. +| properties | String[] - [Key](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/Key.html)[] | [] | The properties of elements to use to animate. +| type | [AnimationType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AnimationType.html) | AnimationType.NUMBER | Type of property, determines the interpolator used. +| from | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Undefined.BOOLEAN
Undefined.DOUBLE
`null` | Start value for the animation. +| to | boolean - double - String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | Undefined.BOOLEAN
Undefined.DOUBLE
`null` | End value for the animation. + +### Interaction + +Interaction uses the same format as [a chart instance](../configuration/interaction). + +:::caution +`DefaultInteractionMode.INDEX` and `DefaultInteractionMode.DATASET` modes are not supported by the plugin. If set, the plugin will use `DefaultInteractionMode.NEAREST` mode. + +`InteractionAxis.R` is not supported by the plugin. If set, the plugin will use `InteractionAxis.XY` mode. +::: + +### Draw time + +The [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) option for an annotation determines where in the chart life cycle the drawing occurs. Four potential options are available: + +| Option | Description +| :- | :- +| BEFORE_DRAW | Occurs before any drawing takes place +| BEFORE_DATASETS_DRAW | Occurs after drawing of axes, but before data sets +| AFTER_DATASETS_DRAW | Occurs after drawing of data sets but before items such as the tooltip +| AFTER_DRAW | After other drawing is completed. + +## Box + +Box annotations are used to draw rectangles on the chart area. This can be useful for highlighting different areas of a chart. + + + +Every plugin options can have an unlimited number of boxes annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +BoxAnnotation box = new BoxAnnotation(); +box.setDrawTime(DrawTime.BEFORE_DATASETS_DRAW); +box.setXScaleID(DefaultScaleId.X); +box.setYScaleID(DefaultScaleId.Y); +box.setXMin("January"); +box.setXMax("April"); +box.setBackgroundColor(GwtMaterialColor.YELLOW_LIGHTEN_3.alpha(0.3D)); +box.setBorderWidth(0); +// stores the annotation in the main options +options.setAnnotations(box); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#box-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#box-scriptable-options) | The fill color of the box.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#box-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT | [Yes](#box-scriptable-options) | Cap style of the border line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#box-scriptable-options) | The stroke color of the box.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderDash | int[]| [] | [Yes](#box-scriptable-options) | The length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#box-scriptable-options) | The offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#box-scriptable-options) | Border line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 0 | [Yes](#box-scriptable-options) | The radius in pixels of box rectangle. +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#box-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 1 | [Yes](#box-scriptable-options) | The stroke width of the box. +| display | boolean | `true` | [Yes](#box-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#box-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| rotation | double | 0 | [Yes](#box-scriptable-options) | The rotation of annotation, in degrees. +| shadowBlur | double | 0 | [Yes](#box-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#box-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#box-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#box-scriptable-options) | Right edge of the box in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#box-scriptable-options) | Left edge of the box in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#box-scriptable-options) | Top edge of the box in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#box-scriptable-options) | Bottom edge of the box in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| z | int | 0 | [Yes](#box-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +If one of the axes does not match an axis in the chart, the box will take the entire chart dimension. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction. + +#### Box scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +BoxAnnotation box = new BoxAnnotation(); +// sets callback for border width options +box.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(box); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<AnnotationContext> | int - - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +### Box label + +A box annotation can have a label to draw in the box. + +Every box annotation can have ONLY 1 label. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +BoxAnnotation box = new BoxAnnotation(); +// sets label configuration +box.getLabel().setDisplay(true); +box.getLabel().setContent("My threshold"); +// stores the annotation in the main options +options.setAnnotations(box); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| [color](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | #fff -          | [Yes](#box-label-scriptable-options) | The text color of the label. +| content | String - String[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | `null` | [Yes](#box-label-scriptable-options) | The content to show in the label. Provide an array to display values on a new line. +| display | boolean | `false` | [Yes](#box-label-scriptable-options) | Whether or not the label is shown. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | See description | - | Defines when the label is drawn.
Defaults to the box annotation draw time if unset. +| [font](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | See description | [Yes](#box-label-scriptable-options) | The text font of the label. The default value is the global font with the weight set to Weight.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| imageHeight | int - String | Undefined.INTEGER - `null` | [Yes](#box-label-scriptable-options) | Overrides the height of the image. Could be set in pixel by a number, or in percentage of current height of image by a string. If uset, uses the height of the image. It is used only when the content is an image. +| imageOpacity | double | 0 | [Yes](#box-label-scriptable-options) | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. It is used only when the content is an image or canvas element. +| imageWidth | int - String | Undefined.INTEGER - `null` | [Yes](#box-label-scriptable-options) | Overrides the width of the image. Could be set in pixel by a number, or in percentage of current width of image by a string. If unset, uses the width of the image. It is used only when the content is an image. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 6 | [Yes](#box-label-scriptable-options) | Number of pixels to add above and below the title text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) | See [position](#box-label-position) | [Yes](#box-label-scriptable-options) | Anchor position of label on box. +| rotation | double | 0 | [Yes](#line-label-scriptable-options) | The rotation of label, in degrees. +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.START | [Yes](#box-label-scriptable-options) | Horizontal alignment on the label content when is set as a multiple lines text. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#box-label-scriptable-options) | The stroke color of the text. +|textStrokeWidth | int | 0 | [Yes](#box-label-scriptable-options) | The stroke width of the text. +| xAdjust | double | 0 | [Yes](#box-label-scriptable-options) | Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right. +| yAdjust | double | 0 | [Yes](#box-label-scriptable-options) | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down. +| z | int | 0 | [Yes](#box-label-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +#### Box label position + +[AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) can define the `x` property for the horizontal alignment in the box. Similarly, the `y` property defines the vertical alignment in the box. + +Possible options for both properties are LabelPosition.START, LabelPosition.CENTER, LabelPosition.END, or a double, a value between 0 and 1, is representing the percentage on the size where the label will be located. + +Default is LabelPosition.CENTER. + +#### Box label scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +BoxAnnotation box = new BoxAnnotation(); +// sets callback for color options +box.getLabel().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(box); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| [color](#fonts-and-colors) | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| content | [ContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ContentCallback.html) | String - List<String> - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| [font](#fonts-and-colors) | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<AnnotationContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| imageHeight | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| imageOpacity | [ImageOpacityCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageOpacityCallback.html) | double +| imageWidth | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<AnnotationContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| position | [LabelAlignPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/LabelAlignPositionCallback.html) | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) +| textAlign | [TextAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TextAlignCallback.html)<AnnotationContext> | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) +| textStrokeColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +## Ellipse + +Ellipse annotations are used to draw ellipses on the chart area. This can be useful for highlighting different areas of a chart. + + + +Every plugin options can have an unlimited number of ellipses annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +EllipseAnnotation ellipse = new EllipseAnnotation(); +ellipse.setDrawTime(DrawTime.BEFORE_DATASETS_DRAW); +ellipse.setXScaleID(DefaultScaleId.X); +ellipse.setYScaleID(DefaultScaleId.Y); +ellipse.setXMin("February"); +ellipse.setXMax("April"); +ellipse.setYMin(10); +ellipse.setYMax(60); +ellipse.setBackgroundColor(GwtMaterialColor.INDIGO_LIGHTEN_3.alpha(0.3D)); +ellipse.setBorderWidth(4); +ellipse.setBorderColor(GwtMaterialColor.INDIGO_LIGHTEN_3); +ellipse.setBorderDash(3,3); +// stores the annotation in the main options +options.setAnnotations(ellipse); +``` + +If one of the axes does not match an axis in the chart, the ellipse will take the entire chart dimension. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the ellipse is expanded out to the edges in the respective direction. + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#ellipse-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#ellipse-scriptable-options) | The fill color of the ellipse.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#ellipse-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#ellipse-scriptable-options) | The stroke color of the ellipse.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderDash | int[]| [] | [Yes](#ellipse-scriptable-options) | The length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#ellipse-scriptable-options) | The offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#ellipse-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 1 | [Yes](#ellipse-scriptable-options) | The stroke width of the ellipse. +| display | boolean | `true` | [Yes](#ellipse-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#ellipse-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| rotation | double | 0 | [Yes](#ellipse-scriptable-options) | The rotation of annotation, in degrees. +| shadowBlur | double | 0 | [Yes](#ellipse-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#ellipse-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#ellipse-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` |[Yes](#ellipse-scriptable-options) | Right edge of the ellipse in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#ellipse-scriptable-options) | Left edge of the ellipse in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#ellipse-scriptable-options) | Top edge of the ellipse in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#ellipse-scriptable-options) | Bottom edge of the ellipse in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| z | int | 0 | [Yes](#ellipse-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +#### Ellipse scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +EllipseAnnotation ellipse = new EllipseAnnotation(); +// sets callback for border width options +ellipse.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(ellipse); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +### Ellipse label + +An ellipse annotation can have a label to draw in the ellipse. + +Every ellipse annotation can have ONLY 1 label. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +EllipseAnnotation ellipse = new EllipseAnnotation(); +// sets label configuration +ellipse.getLabel().setDisplay(true); +ellipse.getLabel().setContent("My label"); +// stores the annotation in the main options +options.setAnnotations(ellipse); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| [color](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | #fff -          | [Yes](#ellipse-label-scriptable-options) | The text color of the label. +| content | String - String[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | `null` | [Yes](#ellipse-label-scriptable-options) | The content to show in the label. Provide an array to display values on a new line. +| display | boolean | `false` | [Yes](#ellipse-label-scriptable-options) | Whether or not the label is shown. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | See description | - | Defines when the label is drawn.
Defaults to the box annotation draw time if unset. +| [font](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | See description | [Yes](#ellipse-label-scriptable-options) | The text font of the label. The default value is the global font with the weight set to Weight.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| imageHeight | int - String | Undefined.INTEGER - `null` | [Yes](#ellipse-label-scriptable-options) | Overrides the height of the image. Could be set in pixel by a number, or in percentage of current height of image by a string. If uset, uses the height of the image. It is used only when the content is an image. +| imageOpacity | double | 0 | [Yes](#ellipse-label-scriptable-options) | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. It is used only when the content is an image or canvas element. +| imageWidth | int - String | Undefined.INTEGER - `null` | [Yes](#ellipse-label-scriptable-options) | Overrides the width of the image. Could be set in pixel by a number, or in percentage of current width of image by a string. If unset, uses the width of the image. It is used only when the content is an image. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 6 | [Yes](#ellipse-label-scriptable-options) | Number of pixels to add above and below the title text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) | See [position](#box-label-position) | [Yes](#ellipse-label-scriptable-options) | Anchor position of label on box. +| rotation | double | 0 | [Yes](#line-label-scriptable-options) | The rotation of label, in degrees. +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.START | [Yes](#ellipse-label-scriptable-options) | Horizontal alignment on the label content when is set as a multiple lines text. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#ellipse-label-scriptable-options) | The stroke color of the text. +|textStrokeWidth | int | 0 | [Yes](#ellipse-label-scriptable-options) | The stroke width of the text. +| xAdjust | double | 0 | [Yes](#ellipse-label-scriptable-options) | Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right. +| yAdjust | double | 0 | [Yes](#ellipse-label-scriptable-options) | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down. +| z | int | 0 | [Yes](#ellipse-label-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +#### Ellipse label scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +EllipseAnnotation ellipse = new EllipseAnnotation(); +// sets callback for color options +ellipse.getLabel().setColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(ellipse); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| [color](#fonts-and-colors) | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| content | [ContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ContentCallback.html) | String - List<String> - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| [font](#fonts-and-colors) | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<AnnotationContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| imageHeight | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| imageOpacity | [ImageOpacityCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageOpacityCallback.html) | double +| imageWidth | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<AnnotationContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| position | [LabelAlignPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/LabelAlignPositionCallback.html) | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) +| textAlign | [TextAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TextAlignCallback.html)<AnnotationContext> | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) +| textStrokeColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +## Label + +Label annotations are used to add contents on the chart area. This can be useful for describing values that are of interest. + + + +Every plugin options can have an unlimited number of labels annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LabelAnnotation label = new LabelAnnotation(); +label.setDrawTime(DrawTime.AFTER_DRAW); +label.setXScaleID(DefaultScaleId.X); +label.setYScaleID(DefaultScaleId.Y); +label.setXValue("February"); +label.setYValue(50); +label.setContent("My label"); +// stores the annotation in the main options +options.setAnnotations(label); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#label-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#label-scriptable-options) | The fill color of the label box.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#label-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT | [Yes](#label-scriptable-options) | Cap style of the border label box. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#label-scriptable-options) | The stroke color of the label box.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| borderDash | int[]| [] | [Yes](#label-scriptable-options) | The length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#label-scriptable-options) | The offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#label-scriptable-options) | Border line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 0 | [Yes](#label-scriptable-options) | The radius in pixels of label box. +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#label-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 0 | [Yes](#label-scriptable-options) | The stroke width of the label box. +| [color](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | HtmlColor.BLACK -          | [Yes](#label-scriptable-options) | The text color of the label. +| content | String - String[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | `null` | [Yes](#label-scriptable-options) | The content to show in the label. Provide an array to display values on a new line. +| display | boolean | `true` | [Yes](#label-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#label-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| [font](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | See description | [Yes](#label-scriptable-options) | The text font of the label. The default value is the global font.
See [Font](../defaults/DefaultsCharts#font). +| imageHeight | int - String | Undefined.INTEGER - `null` | [Yes](#label-scriptable-options) | Overrides the height of the image. Could be set in pixel by a number, or in percentage of current height of image by a string. If uset, uses the height of the image. It is used only when the content is an image. +| imageOpacity | double | 0 | [Yes](#label-scriptable-options) | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. It is used only when the content is an image or canvas element. +| imageWidth | int - String | Undefined.INTEGER - `null` | [Yes](#label-scriptable-options) | Overrides the width of the image. Could be set in pixel by a number, or in percentage of current width of image by a string. If unset, uses the width of the image. It is used only when the content is an image. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 6 | [Yes](#label-scriptable-options) | Number of pixels to add above and below the title text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) | See [position](#label-position) | [Yes](#label-scriptable-options) | Anchor position of label. +| rotation | double | 0 | [Yes](#label-scriptable-options) | The rotation of annotation, in degrees. +| shadowBlur | double | 0 | [Yes](#label-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#label-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#label-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.CENTER | [Yes](#label-scriptable-options) | Horizontal alignment on the label content when is set as a multiple lines text. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#label-scriptable-options) | The stroke color of the text. +|textStrokeWidth | int | 0 | [Yes](#label-scriptable-options) | The stroke width of the text. +| xAdjust | double | 0 | [Yes](#label-scriptable-options) | Adjustment along x-axis (left-right) of point relative to computed position. Negative values move the point left, positive right. +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | X coordinate of end two of the box, whose center is used as the center of the point, in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | X coordinate of end one of the box, whose center is used as the center of the point, in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| xValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | X coordinate of the center of point in units along the x axis. +| yAdjust | double | 0 | [Yes](#label-scriptable-options) | Adjustment along y-axis (top-bottom) of point relative to computed position. Negative values move the point up, positive down. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| yValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#label-scriptable-options) | Y coordinate of the center of point in units along the y axis. +| z | int | 0 | [Yes](#label-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point. + +#### Label position + +[AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) can define the `x` property for the horizontal alignment of the label with respect to the selected point. Similarly, the `y` property defines the vertical alignment. + +Possible options for both properties are LabelPosition.START, LabelPosition.CENTER, LabelPosition.END, or a double, a value between 0 and 1, is representing the percentage on the size where the label will be located. + +Default is LabelPosition.CENTER. + +#### Label scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LabelAnnotation label = new LabelAnnotation(); +// sets callback for border width options +label.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(label); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<AnnotationContext> | int - - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| [color](#fonts-and-colors) | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| content | [ContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ContentCallback.html) | String - List<String> - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| [font](#fonts-and-colors) | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<AnnotationContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| imageHeight | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| imageOpacity | [ImageOpacityCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageOpacityCallback.html) | double +| imageWidth | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<AnnotationContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| position | [LabelAlignPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/LabelAlignPositionCallback.html) | [AlignPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AlignPosition.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| textAlign | [TextAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TextAlignCallback.html)<AnnotationContext> | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| textStrokeColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +### Callout + +The callout connects the label by a line to the selected point. + +Every label annotation can have ONLY 1 callout. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LabelAnnotation label = new LabelAnnotation(); +// sets callout configuration +line.getCallout().setDisplay(true); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT| [Yes](#callout-scriptable-options) | Cap style of the callout line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)| HtmlColor.BLACK -          | [Yes](#callout-scriptable-options) | The color of the callout line. +| borderDash | int[] | [] | [Yes](#callout-scriptable-options) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#callout-scriptable-options) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#callout-scriptable-options) | Callout line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | 1 | [Yes](#callout-scriptable-options) | The width of the callout line in pixels. +| display | boolean | `false` | [Yes](#callout-scriptable-options) | Whether or not the callout is shown. +| margin | int | 5 | [Yes](#callout-scriptable-options) | Amount of pixels between the label and the callout separator. +| position | [CalloutPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/CalloutPosition.html) | CalloutPosition.AUTO | [Yes](#callout-scriptable-options) | The position of callout, with respect to the label. +| side | int | 5 | [Yes](#callout-scriptable-options) | Width of the starter line of callout pointer. +| start | double - int | 0.5D | [Yes](#callout-scriptable-options) | The percentage of the separator dimension to use as starting point for callout pointer. Could be set in pixel by an integer, or in percentage of the separator dimension by a double, a value between 0 and 1. + +#### Callout scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LabelAnnotation label = new LabelAnnotation(); +// sets callback for border color options +label.getCallout().setBorderColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(label); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| margin | [MarginCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/MarginCallback.html) | int +| position | [CalloutPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/CalloutPositionCallback.html) | [CalloutPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/CalloutPosition.html) +| side | [SideCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/SideCallback.html) | int +| start | [StartCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/StartCallback](https.html) | double - int + +## Line + +Line annotations are used to draw lines on the chart area. This can be useful for highlighting information such as a threshold. + + + +Every plugin options can have an unlimited number of lines annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LineAnnotation line = new LineAnnotation(); +line.setDrawTime(DrawTime.AFTER_DRAW); +line.setScaleID(DefaultScaleId.X.value()); +line.setBorderColor(HtmlColor.DARK_GRAY); +line.setBorderWidth(2); +line.setValue(new Date()); +// sets label configuration +line.getLabel().setDisplay(true); +line.getLabel().setContent("Now"); +line.getLabel().setPosition(LabelPosition.START); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#line-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#line-scriptable-options) | The stroke color of the line. +| borderDash | int[] | [] | [Yes](#line-scriptable-options) | the line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern. +| borderDashOffset | int | 0 | [Yes](#line-scriptable-options) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#line-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 2 | [Yes](#line-scriptable-options) | The stroke width of the line. +| controlPoint | double - String - [ControlPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/ControlPoint.html) | `{y:'-50%'}` | [Yes](#line-scriptable-options) | If `curve` is enabled, it configures the control point to drawn the curve, calculated in pixels. It can be set by a string in percentage format `"number%"` which are representing the percentage of the distance between the start and end point from the center. +| curve | boolean | `false` | [Yes](#line-scriptable-options) | Whether or not a quadratic [Bézier curve](https://developer.mozilla.org/en-US/docs/Glossary/Bezier_curve) is drawn. +| display | boolean | `true` | [Yes](#line-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#line-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| endValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | End two of the line when a single scale is specified. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| scaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | ID of the scale in single scale mode. If unset, `xScaleID` and `yScaleID` are used. +| shadowBlur | double | 0 | [Yes](#line-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#line-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#line-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| value | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | End one of the line when a single scale is specified. +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | X coordinate of end two of the line in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | X coordinate of end one of the line in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | Y coordinate of end one of the line in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#line-scriptable-options) | Y coordinate of end one of the line in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| z | int | 0 | [Yes](#line-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +If one of the axes does not match an axis in the chart, the line will take the entire chart dimension. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the line is expanded out to the edges in the respective direction. + +The line can be positioned in two different ways: + + * if `scaleID` is set, then `value` and `endValue` must also be set to indicate the end points of the line. The line will be perpendicular to the axis identified by `scaleID`. + * if `scaleID` is unset, then `xScaleID` and `yScaleID` are used to draw a line from `(xMin, yMin)` to `(xMax, yMax)`. + +#### Line scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +// sets callback for border width options +line.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| controlPoint | [ControlPointCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ControlPointCallback.html) | double - String - [ControlPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/ControlPoint.html) +| curve | [CurveCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/CurveCallback.html) | boolean +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| endValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| value | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +### Line label + +A line annotation can have a label to draw on the line. + +Every line annotation can have ONLY 1 label. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LineAnnotation line = new LineAnnotation(); +// sets label configuration +line.getLabel().setDisplay(true); +line.getLabel().setContent("My threshold"); +line.getLabel().setBackgroundColor(HtmlColor.RED); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| autoRotation | boolean | `false` | - | If `true`, the rotation option is ignored and the label uses the degrees of the line. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | rgba(0,0,0,0.8) -          | [Yes](#line-label-scriptable-options) | Background color of the label container. +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#line-label-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT| [Yes](#line-label-scriptable-options) | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.BLACK -          | [Yes](#line-label-scriptable-options) | The color of the line. +| borderDash | int[] | [] | [Yes](#line-label-scriptable-options) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#line-label-scriptable-options) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#line-label-scriptable-options) | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderRadius | int - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) | 6 | [Yes](#line-label-scriptable-options) | The radius of label box in pixels. +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#line-label-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 0 | [Yes](#line-label-scriptable-options) | The width of the line in pixels. +| [color](#fonts-and-colors) | String[] - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)[] | #fff -          | [Yes](#line-label-scriptable-options) | The text color of the label. +| content | String - String[] - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | `null` | [Yes](#line-label-scriptable-options) | The content to show in the label. Provide an array to display values on a new line. +| display | boolean | `false` | [Yes](#line-label-scriptable-options) | Whether or not the label is shown. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | See description | - | Defines when the label is drawn.
Defaults to the line annotation draw time if unset. +| [font](#fonts-and-colors) | [IsFont](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsFont.html) - List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> - [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)[] | See description | [Yes](#line-label-scriptable-options) | The text font of the label. The default value is the global font with the style set to FontStyle.BOLD.
See [Font](../defaults/DefaultsCharts#font). +| imageHeight | int - String | Undefined.INTEGER - `null` | [Yes](#line-label-scriptable-options) | Overrides the height of the image. Could be set in pixel by a number, or in percentage of current height of image by a string. If uset, uses the height of the image. It is used only when the content is an image. +| imageOpacity | double | 0 | [Yes](#line-label-scriptable-options) | Overrides the opacity of the image or canvas element. Could be set a number in the range 0.0 to 1.0, inclusive. It is used only when the content is an image or canvas element. +| imageWidth | int - String | Undefined.INTEGER - `null` | [Yes](#line-label-scriptable-options) | Overrides the width of the image. Could be set in pixel by a number, or in percentage of current width of image by a string. If unset, uses the width of the image. It is used only when the content is an image. +| padding | [Padding](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/configuration/Padding.html) | 6 | [Yes](#line-label-scriptable-options) | Number of pixels to add above and below the title text.
See [padding documentation](../configuration/Commons#padding) for more details. +| position | [LabelPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/LabelPosition.html) - double | LabelPosition.CENTER | [Yes](#line-label-scriptable-options) | Anchor position of label on line. If set by a double, a value between 0 and 1, is representing the percentage on the size where the label will be located. +| rotation | double | 0 | [Yes](#line-label-scriptable-options) | The rotation of label, in degrees. +| shadowBlur | double | 0 | [Yes](#line-label-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#line-label-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#line-label-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| textAlign | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.CENTER | [Yes](#line-label-scriptable-options) | Horizontal alignment on the label content when is set as a multiple lines text. +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#line-label-scriptable-options) | The stroke color of the text. +| textStrokeWidth | int | 0 | [Yes](#line-label-scriptable-options) | The stroke width of the text. +| xAdjust | double | 0 | [Yes](#line-label-scriptable-options) | Adjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right. +| yAdjust | double | 0 | [Yes](#line-label-scriptable-options) | Adjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down. +| z | int | 0 | [Yes](#line-label-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +#### Line label scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +// sets callback for background color options +line.getLabel().setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderRadius | [BorderRadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderRadiusCallback.html)<AnnotationContext> | int - - [BarBorderRadius](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/BarBorderRadius.html) +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| [color](#fonts-and-colors) | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| content | [ContentCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ContentCallback.html) | String - List<String> - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| [font](#fonts-and-colors) | [FontsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontsCallback.html)<AnnotationContext> | List<[FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html)> +| imageHeight | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| imageOpacity | [ImageOpacityCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageOpacityCallback.html) | double +| imageWidth | [ImageSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ImageSizeCallback.html) | String - int +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<AnnotationContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| position | [LabelPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/LabelPositionCallback.html) | double - [LabelPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/LabelPosition.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double**(1)** +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| textAlign | [TextAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/TextAlignCallback.html)<AnnotationContext> | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) +| textStrokeColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +**(1)**To enable `autoRotation` by the rotation callback, the value to return must be `Double.NaN`. + +```java +// sets callback for auto rotation +line.getLabel().setRotation(new RotationCallback(){ + + @Override + public Double invoke(AnnotationContext context){ + return Double.NaN; // autoRotation is set + } +}); +``` + +### Callout + +The callout connects the label by a line to the line annotation. + +Every line annotation can have ONLY 1 line label and callout. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LineAnnotation line = new LineAnnotation(); +// sets label configuration +line.getLabel().setDisplay(true); +line.getLabel().setContent("My threshold"); +line.getLabel().setBackgroundColor(HtmlColor.RED); +line.getLabel().setYAdjust(-100); +// sets callout configuration +line.getLabel().getCallout().setDisplay(true); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT| [Yes](#line-label-callout-scriptable-options) | Cap style of the callout line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)| HtmlColor.BLACK -          | [Yes](#line-label-callout-scriptable-options) | The color of the callout line. +| borderDash | int[] | [] | [Yes](#line-label-callout-scriptable-options) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | 0 | [Yes](#line-label-callout-scriptable-options) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#line-label-callout-scriptable-options) | Callout line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin). +| borderWidth | int | 1 | [Yes](#line-label-callout-scriptable-options) | The width of the callout line in pixels. +| display | boolean | `false` | [Yes](#line-label-callout-scriptable-options) | Whether or not the callout is shown. +| margin | int | 5 | [Yes](#line-label-callout-scriptable-options) | Amount of pixels between the label and the callout separator. +| position | [CalloutPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/CalloutPosition.html) | CalloutPosition.AUTO | [Yes](#line-label-callout-scriptable-options) | The position of callout, with respect to the label. +| side | int | 5 | [Yes](#line-label-callout-scriptable-options) | Width of the starter line of callout pointer. +| start | double - int | 0.5D | [Yes](#line-label-callout-scriptable-options) | The percentage of the separator dimension to use as starting point for callout pointer. Could be set in pixel by an integer, or in percentage of the separator dimension by a double, a value between 0 and 1. + +#### Line label Callout scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +// sets label configuration +line.getLabel().setDisplay(true); +line.getLabel().setContent("My threshold"); +line.getLabel().setBackgroundColor(HtmlColor.RED); +line.getLabel().setYAdjust(-100); +line.getLabel().getCallout().setDisplay(true); +// sets callback for border color options +line.getLabel().getCallout().setBorderColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(label); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| margin | [MarginCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/MarginCallback.html) | int +| position | [CalloutPositionCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/CalloutPositionCallback.html) | [CalloutPosition](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/CalloutPosition.html) +| side | [SideCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/SideCallback.html) | int +| start | [StartCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/StartCallback](https.html) | double - int + +### Arrow heads + +Enabling it, you can add arrow heads at start and/or end of a line. It uses the `borderWidth` of the line options to configure the line width of the arrow head. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +LineAnnotation line = new LineAnnotation(); +// sets arrowheads configuration +line.getArrowHeads().setDisplay(true); +line.getArrowHeads().setLength(20); +line.getArrowHeads().setWidth(12); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The following options can be specified per (`line.getArrowHeads().getStart()` and/or `line.getArrowHeads().getEnd()`) arrow head, or at the top level (`line.getArrowHeads()`) which apply to all arrow heads. + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `lineAnnotation.borderColor` | [Yes](#arrowheads-scriptable-options) | Background color of the arrow head. +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#arrowheads-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `lineAnnotation.borderColor` | [Yes](#arrowheads-scriptable-options) | The border arrow head color. +| borderDash | int[] | `lineAnnotation.borderDash` | [Yes](#arrowheads-scriptable-options) | Length and spacing of dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash). +| borderDashOffset | double | `lineAnnotation.borderDashOffset` | [Yes](#arrowheads-scriptable-options) | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset). +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `lineAnnotation.borderShadowColor` | [Yes](#arrowheads-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | `lineAnnotation.borderWidth` | [Yes](#arrowheads-scriptable-options) | The width of the line in pixels. +| display | boolean | `false` | [Yes](#arrowheads-scriptable-options) | Whether or not the arrow head is shown. +| end | [ArrowHeads](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/ArrowHeads.html) | - | - | To configure the arrow head at the end of the line. +| fill | boolean | `false` | [Yes](#arrowheads-scriptable-options) | Whether or not the arrow head is filled. +| length | int | `12` | [Yes](#arrowheads-scriptable-options) | The length of the arrow head in pixels. +| shadowBlur | double | `lineAnnotation.shadowBlur` | [Yes](#arrowheads-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | `lineAnnotation.shadowOffsetX` | [Yes](#arrowheads-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | `lineAnnotation.shadowOffsetY` | [Yes](#arrowheads-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| start | [ArrowHeads](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/ArrowHeads.html) | - | - | To configure the arrow head at the start of the line. +| width | int | `6` | [Yes](#arrowheads-scriptable-options) | The width of the arrow head in pixels. + +#### ArrowHeads scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +LineAnnotation line = new LineAnnotation(); +// sets callback for background color options +line.getArrowHeads().setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(AnnotationContext context){ + // logic + return color; + } +}); +// stores the annotation in the main options +options.setAnnotations(line); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| fill | [FillCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/FillCallback.html) | boolean +| length | [LengthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/LengthCallback.html) | int +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| width | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int + +## Point + +Point annotations are used to mark points on the chart area. This can be useful for highlighting values that are of interest. + + + +Every plugin options can have an unlimited number of points annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +PointAnnotation point = new PointAnnotation(); +// sets annotation configuration +point.setXScaleID(DefaultScaleId.X); +point.setYScaleID(DefaultScaleId.Y); +point.setXValue("February"); +point.setYValue(50); +point.setRadius(10); +point.setBackgroundColor(HtmlColor.YELLOW.alpha(0.3D)); +point.setBorderWidth(2); +point.setBorderColor(HtmlColor.YELLOW.darker()); +// stores the annotation in the main options +options.setAnnotations(point); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#point-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#point-scriptable-options) | The fill color of the point.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#point-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#point-scriptable-options) | The stroke color of the point. +| borderDash | int[] | [] | [Yes](#point-scriptable-options) | The line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern. +| borderDashOffset | int | 0 | [Yes](#point-scriptable-options) | Offset for border dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#point-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 1 | [Yes](#point-scriptable-options) | The stroke width of the point. +| display | boolean | `true` | [Yes](#point-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#point-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| pointStyle | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) | PointStyle.CIRCLE | [Yes](#point-scriptable-options) | Style of the point. +| radius | double | 10 | [Yes](#point-scriptable-options) | Size of the point in pixels. +| rotation | double | 0 | [Yes](#point-scriptable-options) | The rotation of the point, in degrees. +| shadowBlur | double | 0 | [Yes](#point-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#point-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#point-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| xAdjust | double | 0 | [Yes](#point-scriptable-options) | Adjustment along x-axis (left-right) of point relative to computed position. Negative values move the point left, positive right. +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | X coordinate of end two of the box, whose center is used as the center of the point, in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | X coordinate of end one of the box, whose center is used as the center of the point, in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| xValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | X coordinate of the center of point in units along the x axis. +| yAdjust | double | 0 | [Yes](#point-scriptable-options) | Adjustment along y-axis (top-bottom) of point relative to computed position. Negative values move the point up, positive down. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| yValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#point-scriptable-options) | Y coordinate of the center of point in units along the y axis. +| z | int | 0 | [Yes](#point-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point. To enable to use the box positioning, the `radius` must be set to `0`. + +#### Point scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +PointAnnotation point = new PointAnnotation(); +// sets callback for border width options +point.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(point); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| pointStyle | [PointStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PointStyleCallback.html)<AnnotationContext> | [PointStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/PointStyle.html) - [Img](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Img.html) - [Canvas](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/Canvas.html) +| radius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<AnnotationContext> | double +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +## Polygon + +Polygon annotations are used to mark whatever polygon (for instance triangle, square or pentagon) on the chart area. This can be useful for highlighting values that are of interest. + + + +Every plugin options can have an unlimited number of polygons annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +PolygonAnnotation polygon = new PolygonAnnotation(); +// sets annotation configuration +polygon.setXScaleID(DefaultScaleId.X); +polygon.setYScaleID(DefaultScaleId.Y); +polygon.setXValue("February"); +polygon.setYValue(50); +polygon.setRadius(10); +// pentagon +polygon.setSides(5); +polygon.setBackgroundColor(HtmlColor.YELLOW.alpha(0.3D)); +polygon.setBorderWidth(2); +polygon.setBorderColor(HtmlColor.YELLOW.darker()); +// stores the annotation in the main options +options.setAnnotations(polygon); +``` + +The complete options are described by following table: + +| Name | Type | Default | Scriptable | Description +| :- | :- | :- | :- | :- +| adjustScaleRange | boolean | `true` | [Yes](#polygon-scriptable-options) | If `true`, the scale range should be adjusted if this annotation is out of range. +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#polygon-scriptable-options) | The fill color of the polygon.
See [default colors](../defaults/DefaultsCharts#commons-charts-options). +| backgroundShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#polygon-scriptable-options) | The color of shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderCapStyle | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) | CapStyle.BUTT | [Yes](#polygon-scriptable-options) | Cap style of the border line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap). +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `Defaults.get().getGlobal()`
`.getColorAsString()` | [Yes](#polygon-scriptable-options) | The stroke color of the polygon. +| borderDash | int[] | [] | [Yes](#polygon-scriptable-options) | The line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern. +| borderDashOffset | int | 0 | [Yes](#polygon-scriptable-options) | Offset for border dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset) +| borderJoinStyle | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) | JoinStyle.MITER | [Yes](#polygon-scriptable-options) | Border line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin) +| borderShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | HtmlColor.TRANSPARENT | [Yes](#polygon-scriptable-options) | The color of border shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowColor). +| borderWidth | int | 1 | [Yes](#polygon-scriptable-options) | The stroke width of the polygon. +| display | boolean | `true` | [Yes](#polygon-scriptable-options) | Whether or not this annotation is visible. +| drawTime | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) | DrawTime.
AFTER_DATASETS_DRAW | [Yes](#polygon-scriptable-options) | Defines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph. +| [init](#initial-animation) | boolean | false | - | If `true` or customized by [callback](#initial-animation), the annotation element will be animated since the initial phase. +| radius | double | 10 | [Yes](#polygon-scriptable-options) | Size of the polygon in pixels. +| rotation | double | 0 | [Yes](#polygon-scriptable-options) | The rotation of the polygon, in degrees. +| shadowBlur | double | 0 | [Yes](#polygon-scriptable-options) | The amount of blur applied to shadows. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowBlur). +| shadowOffsetX | int | 0 | [Yes](#polygon-scriptable-options) | The distance that shadows will be offset horizontally. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetX). +| shadowOffsetY | int | 0 | [Yes](#polygon-scriptable-options) | The distance that shadows will be offset vertically. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/shadowOffsetY). +| sides | int | 3 | [Yes](#polygon-scriptable-options) | Amount of sides of polygon. +| xAdjust | double | 0 | [Yes](#polygon-scriptable-options) | Adjustment along x-axis (left-right) of polygon relative to computed position. Negative values move the polygon left, positive right. +| xMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | X coordinate of end two of the box, whose center is used as the center of the polygon, in units along the x axis. +| xMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | X coordinate of end one of the box, whose center is used as the center of the polygon, in units along the x axis. +| xScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the X scale to bind onto. +| xValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | X coordinate of the center of polygon in units along the x axis. +| yAdjust | double | 0 | [Yes](#polygon-scriptable-options) | Adjustment along y-axis (top-bottom) of polygon relative to computed position. Negative values move the polygon up, positive down. +| yMax | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the polygon, in units along the y axis. +| yMin | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | Y coordinate of end one of the box, whose center is used as the center of the polygon, in units along the y axis. +| yScaleID | String - [ScaleId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/ScaleId.html) | `null` | - | The ID of the Y scale to bind onto. +| yValue | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) | `null` | [Yes](#polygon-scriptable-options) | Y coordinate of the center of polygon in units along the y axis. +| z | int | 0 | [Yes](#polygon-scriptable-options) | All visible elements will be drawn in ascending order of `z` option, with the same `drawTime` option. + +If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point. + +The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point. To enable to use the box positioning, the `radius` must be set to `0`. + +#### Polygon scriptable options + +Some options also accept a callback which is called at runtime and that takes the context as single argument, see [here](#scriptable-context) the details, which is representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +PolygonAnnotation polygon = new PolygonAnnotation(); +// sets callback for border width options +polygon.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(polygon); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| adjustScaleRange | [AdjustScaleRangeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustScaleRangeCallback.html) | boolean +| backgroundColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> - [Pattern](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Pattern.html) +| backgroundShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderCapStyle | [CapStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/CapStyleCallback.html)<AnnotationContext> | [CapStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/CapStyle.html) +| borderColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderDash | [BorderDashCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashCallback.html)<AnnotationContext> | List<Integer> +| borderDashOffset | [BorderDashOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/BorderDashOffsetCallback.html)<AnnotationContext> | double +| borderJoinStyle | [JoinStyleCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/JoinStyleCallback.html)<AnnotationContext> | [JoinStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/JoinStyle.html) +| borderShadowColor | [ColorsCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorsCallback.html)<AnnotationContext> | List<String> - List<[IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html)> +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<AnnotationContext> | int +| display | [SimpleDisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/SimpleDisplayCallback.html)<AnnotationContext> | boolean +| drawTime | [DrawTimeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/DrawTimeCallback.html) | [DrawTime](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/enums/DrawTime.html) +| radius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<AnnotationContext> | double +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<AnnotationContext> | double +| shadowBlur | [ShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowBlurCallback.html) | double +| shadowOffsetX | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| shadowOffsetY | [ShadowOffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ShadowOffsetCallback.html) | int +| sides | [SidesCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/SidesCallback.html) | int +| xAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| xMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| xValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yAdjust | [AdjustSizeCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/AdjustSizeCallback.html) | double +| yMax | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yMin | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| yValue | [ValueCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ValueCallback.html) | String - double - [Date](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Date.html) +| z | [ZCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/ZCallback.html) | int + +## Events + +All annotations provide a set of callbacks which can be enabled to catch events on them. + +To catch events is enough to set the events which you want to catch at [AnnotationOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptions.html) and set a callback instance in the annotation. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +// without id (a unique one is created automatically) +BoxAnnotation box = new BoxAnnotation(); +// sets callback for specific annotation +box.setClickCallback(new ClickCallback(){ + + @Override + public boolean onClick(IsChart chart, AbstractAnnotation annotation, ChartEventContext event){ + // logic + return false; // no redrawing + } +}); +``` + +You can also catch events with listeners defined for all defined annotations with a single instance, defining it to [AnnotationOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationOptions.html). + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// sets callback for all annotations +options.setClickCallback(new ClickCallback(){ + + @Override + public boolean onClick(IsChart chart, AbstractAnnotation annotation, ChartEventContext event){ + // logic + return false; // no redrawing + } +}); +``` + +These are the table of callbacks to implement: + +| Event | Callback type | Description +| :- | :- | :- +| enter | [EnterCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/listeners/EnterCallback.html) | Called when the mouse enters the annotation. +| leave | [LeaveCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/listeners/LeaveCallback.html) | Called when the mouse leaves the annotation. +| click | [ClickCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/listeners/ClickCallback.html) | Called when a click occurs on the annotation. + +:::info +If the event callback returns `true`, the chart will re-render automatically after processing the event completely. This is important when there are the annotations that require re-draws (for instance, after a change of a rendering options). +::: + +## Hooks + +All annotations provide 2 hooks which can be enabled to be notified before and after the annotation drawing. + +These hooks enable the user to apply own custom shapes or drawings on top to the existing annotations. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +BoxAnnotation box = new BoxAnnotation(); +// sets callback +box.setBeforeDraw(new ElementHookCallback(){ + + @Override + public void invoke(AnnotationContext context){ + // logic + } +}); +// sets callback +box.setAfterDraw(new ElementHookCallback(){ + + @Override + public void invoke(AnnotationContext context){ + // logic + } +}); + +``` + +| Hook | Callback type | Description +| ---- | ---- | ---- +| beforeDraw | [ElementHookCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/listeners/ElementHookCallback.html) | Called before that the annotation is being drawn. +| afterDraw | [ElementHookCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/listeners/ElementHookCallback.html) | Called after the annotation has been drawn. + +## Scriptable context + +Some options also accept a callback which is called at runtime and that takes the context as single argument, [AnnotationContext](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AnnotationContext.html) representing contextual information and chart instance. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +BoxAnnotation box = new BoxAnnotation(); +// sets callback for border width options +box.setBorderWidth(new WidthCallback(){ + + @Override + public Integer invoke(AnnotationContext context){ + // logic + return borderWidth; + } +}); +// stores the annotation in the main options +options.setAnnotations(box); +``` + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| annotation | [AbstractAnnotation](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/AbstractAnnotation.html) | The annotation configuration where the options is defined as scriptable. +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| element | [AnnotationElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/elements/AnnotationElement.html) | The element instance related to the annotation. +| shared | Map<String, Object> | A map that can be used to share objects among all contexts for all annotation. +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be `ContextType.CHART` or `ContextType.ANNOTATION` + +#### Fonts and colors + +When the label to draw has multiple lines, you can use different font and color for each row of the label. This is enabled configuring an array or list of fonts or colors for those options. When the lines are more than the configured fonts of colors, the last configuration of those options is used for all remaining lines. + +#### Initial animation + +The `init` option is scriptable but it doesn't get the [annotation context](#scriptable-context) as argument but a specific context because the element has not been initialized yet, when the callback is invoked. + +You can implement a [InitCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/annotation/callbacks/InitCallback.html) interface to enable your own initial animation of the annotation. + +```java +// creates a plugin options +AnnotationOptions options = new AnnotationOptions(); +// creates an annotation +BoxAnnotation box = new BoxAnnotation(); +// sets callback +box.setInit(new InitCallback(){ + + /** + * Invoked to enable a custom logic to apply the animation initialization. + * + * @param chart chart instance + * @param properties initializing annotation element properties + * @param options annotation options + * @return could be a boolean or an AnnotationProperties + */ + @Override + public Object invoke(IsChart chart, AnnotationProperties properties, AbstractAnnotation options){ + AnnotationProperties initAnimProps = new AnnotationProperties(); + // logic + return initAnimProps; + } +}); +// stores the annotation in the main options +options.setAnnotations(box); +``` diff --git a/versioned_docs/version-6.5/extensions/DataLabels.md b/versioned_docs/version-6.5/extensions/DataLabels.md new file mode 100644 index 000000000..30e7b28f8 --- /dev/null +++ b/versioned_docs/version-6.5/extensions/DataLabels.md @@ -0,0 +1,693 @@ +--- +id: DataLabels +title: DataLabels plugin +hide_title: true +sidebar_label: DataLabels +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## DataLabels plugin + +**Charba** provides out of the box the feature to enable [DataLabels](https://github.com/chartjs/chartjs-plugin-datalabels) which is a highly customizable plugin that displays labels on data for any type of charts, with all its capabilities. + + + +## Activation + +(quoted from [documentation guide](https://github.com/chartjs/chartjs-plugin-datalabels/tree/master/docs/guide) of DataLabels project) + +The data labels plugin is injected directly in the document. + +The plugin ID is a constant everywhere available, `DataLabelsPlugin.ID`, in [DataLabelsPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsPlugin.html) entry point. + +This plugin registers itself globally, meaning that once injected, all charts will display labels. In case you want it enabled only for a few charts, you can enable it as following: + +```java +// -------------------------------------- +// enabling the plugin without any parameter +// the plugin is NOT registered to all charts +// -------------------------------------- +DataLabelsPlugin.enable(); + +// -------------------------------------- +// enabling the plugin with `true` parameter +// the plugin is registered to all charts +// -------------------------------------- +DataLabelsPlugin.enable(true) +``` + +To activate the plugin in a specific chart, it's enough to provide the configuration options (see [below](#configuration)) or enabling it by: + +```java +// -------------------------------------- +// ENABLING the plugin to a chart instance +// storing a plugin options +// -------------------------------------- +// creates a plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets the align options +options.setAlign(Align.CENTER); +// stores the plugin options directly by the options +options.store(chart); + +// -------------------------------------- +// ENABLING the plugin to a chart instance +// by a boolean using default plugin +// options +// -------------------------------------- +chart.getOptions().getPlugins().setEnabled(DataLabelsPlugin.ID, true); +``` + +## Configuration + +The plugin options can be changed at 3 different levels and are evaluated with the following priority: + + * per dataset, by `dataset.setOptions` method + * per chart by `chart.getOptions().getPlugins().setOptions` method + * per chart type by `Defaults.get().getOptions([chartType]).getPlugins().setOptions` method + * or globally by `Defaults.get().getGlobal().getPlugins().setOptions` method + +The configuration class [DataLabelsOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsOptions.html) contains all properties needed to configure the plugin. + +```java +// creates a plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets the align options +options.setAlign(Align.CENTER); + +// -------------------------------------- +// STORING plugin options +// -------------------------------------- +// stores the plugin options by plugin ID +chart.getOptions().getPlugins().setOptions(DataLabelsPlugin.ID, options); +// stores the plugin options without plugin ID +chart.getOptions().getPlugin().setOptions(options); +// stores the plugin options directly by the options +options.store(chart); +``` + +You can also change the default for all charts instances, as following: + +```java +// creates a plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets the align options +options.setAlign(Align.CENTER); + +// -------------------------------------- +// STORING plugin options +// -------------------------------------- +// stores the plugin options by plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(DataLabelsPlugin.ID, options); +// stores the plugin options without plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(options); +// stores the plugin options directly by the options +options.store(); +``` + +If you need to read the plugin options, there is the specific factory, [DataLabelsOptionsFactory](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsOptionsFactory.html) as static reference inside the [DataLabels](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabels.html) entry point which can be used to retrieve the options from chart as following: + +```java +// gets options reference +DataLabelsOptions options; + +// -------------------------------------- +// GETTING plugin options from chart +// -------------------------------------- +if (chart.getOptions().getPlugin().hasOptions(DataLabelsPlugin.ID)){ + // retrieves the plugin options by plugin ID + options = chart.getOptions().getPlugin().getOptions(DataLabelsPlugin.ID, DataLabelsPlugin.FACTORY); + //retrieves the plugin options without plugin ID + options = chart.getOptions().getPlugin().getOptions(DataLabelsPlugin.FACTORY); +} +``` + +## Options + +The complete options are described by following table: + +| Name | Type | Default | Scriptable +| :- | :- | :- | :----- +| [align](DataLabels#alignment-and-offset) | double - [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Align.html) | Align.CENTER | [Yes](#scriptable) +| [anchor](DataLabels#anchoring) | [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Anchor.html) | Anchor.CENTER | [Yes](#scriptable) +| backgroundColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `null` | [Yes](#scriptable) +| borderColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | `null` | [Yes](#scriptable) +| borderRadius | double | 0 | [Yes](#scriptable) +| borderWidth | int | 0 | [Yes](#scriptable) +| [clamp](DataLabels#clamping) | boolean | `false` | [Yes](#scriptable) +| [clip](DataLabels#clipping) | boolean | `false` | [Yes](#scriptable) +| color | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | [default color](../defaults/DefaultsCharts) | [Yes](#scriptable) +| [display](DataLabels#visibility) | [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) | Display.TRUE | [Yes](#scriptable) +| events | [IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)[] - Set<[IsEvent](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/IsEvent.html)> | `Defaults.get().getGlobal()`
`.getEvents()` | The events option defines the browser events that the plugin should listen to. This overrides the options at chart level. +| [offset](DataLabels#alignment-and-offset) | int | 4 | [Yes](#scriptable) +| opacity | double | 1 | [Yes](#scriptable) +| [rotation](DataLabels#rotation) | double | 0 | [Yes](#scriptable) +| [textAlign](DataLabels#text-alignment) | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) | TextAlign.START | [Yes](#scriptable) +| textStrokeColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | the `color` property | [Yes](#scriptable) +| textStrokeWidth | int | 0 | [Yes](#scriptable) +| textShadowBlur | double | 0 | [Yes](#scriptable) +| textShadowColor | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) | the `color` property | [Yes](#scriptable) + +## Scriptable + +All options also accept a callback which is called for each data and that takes the context as single argument, [DataLabelsContext](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsContext.html) representing contextual information and chart instance. + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets background color callback +options.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DataLabelsContext context){ + IsChart chart = context.getChart(); + List datasets = chart.getData().getDatasets(); + LineDataset dataset = (LineDataset)datasets.get(context.getDatasetIndex()); + return dataset.getBackgroundColor(); + } +}); +``` + +The context object contains the following properties: + +| Name | Type | Description +| :- | :- | :- +| active | boolean | Whether the associated element is hovered. +| attributes | [NativeObjectContainer](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/commons/NativeObjectContainer.html) | User object which you can store your options at runtime. +| chart | [IsChart](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/IsChart.html) | Chart instance. +| dataIndex | int | The index of the current data. +| element | [ChartElement](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ChartElement.html) | The element (point, arc, bar, etc.) for this data. +| datasetIndex | int | The index of the current data set. +| datasetItem | [DatasetItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DatasetItem.html) | The data set information for this data. +| label | [LabelItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/LabelItem.html) | The label configuration where the options is defined as scriptable. +| mode | [TransitionMode](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/options/TransitionMode.html) | The update mode, brought by conte +| type | [ContextType](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/ContextType.html) | The type of the context. It can be ONLY `ContextType.DATALABELS`. + +The colored properties (backgroundColor, borderColor, color, textStrokeColor and textShadowColor) can be set (by callbacks) also to a [pattern](../coloring/Patterns), [gradient](../coloring/Gradients), [CanvasPatternItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/CanvasPatternItem.html) or [CanvasGradientItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/CanvasGradientItem.html), as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets background color callback +options.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DataLabelsContext context){ + IsChart chart = context.getChart(); + List datasets = chart.getData().getDatasets(); + LineDataset dataset = (LineDataset)datasets.get(context.getDatasetIndex()); + return dataset.getBackgroundColorAsPattern(); + } +}); +``` + +:::info +The gradient coordinates are relative the label coordinates (local), not relative to the canvas coordinates (global), as reported in [this thread](https://github.com/chartjs/chartjs-plugin-datalabels/issues/114), therefore don't use **Charba** [gradient](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/Gradient.html) object but directly the [CanvasGradientItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/elements/CanvasGradientItem.html) if you need to use gradients. +::: + +See the example here how to use gradients in the meantime: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets background color callback +options.setBackgroundColor(new ColorCallback(){ + + CanvasGradientItem gradient = null; + + @Override + public CanvasGradientItem invoke(DataLabelsContext context){ + IsChart chart = context.getChart(); + if (gradient == null){ + // creates a canvas gradient + gradient = chart.getCanvas().getContext2d().createLinearGradient(-25, -25, 25, 25); + gradient.addColorStop(0, "#fff000"); + gradient.addColorStop(1, "#000fff"); + } + return gradient; + } +}); +``` + +As workaround, you can use the following code which get the color at specific offset from a gradient: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets background color callback +option.setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DataLabelsContext context){ + IsChart chart = context.getChart(); + List datasets = chart.getData().getDatasets(); + LineDataset dataset = (LineDataset)datasets.get(context.getDatasetIndex()); + Gradient gradient = dataset.getBackgroundColorAsGradient(); + // calculates the factor on data count + double factor = dataset.getData().size() > 0 ? context.getIndex() * 1D / (dataset.getData().size() -1) : 0; + // calculates the interpolation for gradient + return gradient.getInterpolatedColorByOffset(factor); + } +}); +``` + +The following options can be set by a callback: + +| Name | Callback | Returned types +| :- | :- | :- +| align | [AlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/AlignCallback.html) | double - [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Align.html) +| anchor | [AnchorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/AnchorCallback.html) | [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Anchor.html) +| backgroundColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DataLabelsContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DataLabelsContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| borderRadius | [RadiusCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RadiusCallback.html)<DataLabelsContext> | double +| borderWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DataLabelsContext> | int +| clamp | [ClampCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/ClampCallback.html) | boolean +| clip | [ClipCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/ClipCallback.html) | boolean +| color | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DataLabelsContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| display | [DisplayCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/DisplayCallback.html)<DataLabelsContext> | [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) +| font | [FontCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html)<DataLabelsContext> | [FontItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) +| offset | [OffsetCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/OffsetCallback.html)<DataLabelsContext> | int +| opacity | [OpacityCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/OpacityCallback.html) | double +| padding | [PaddingCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html)<DataLabelsContext> | [PaddingItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) +| rotation | [RotationCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/RotationCallback.html)<DataLabelsContext> | double +| textAlign | [TextAlignCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/TextAlignCallback.html)<DataLabelsContext> | [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) +| textStrokeColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DataLabelsContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) +| textStrokeWidth | [WidthCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/WidthCallback.html)<DataLabelsContext> | int +| textShadowBlur | [TextShadowBlurCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/callbacks/TextShadowBlurCallback.html) | double +| textShadowColor | [ColorCallback](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/ColorCallback.html)<DataLabelsContext> | String - [IsColor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/colors/IsColor.html) + +## Font + +Every options has got a inner element to set font options. + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets options +options.getFont().setFontSize(12); +options.getFont().setWeight(Weight.BOLD); +``` + +The complete options are described by following table: + +| Name | Type | Default | Descriptions +|:- |:- |:- |:- +| fontFamily | String | [default font family](../defaults/DefaultsCharts#font) | The font family of label. +| fontSize | int | [default font size](../defaults/DefaultsCharts#font) | The font size of label. +| fontStyle | [FontStyle](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/FontStyle.html) | [default font style](../defaults/DefaultsCharts#font) | The font style of label. +| weight | [Weight](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Weight.html) | [default font weight](../defaults/DefaultsCharts#font) | Font weight (boldness) for text. +| [lineHeight](#multiple-lines-of-labels-text) | double - String | 1.2 | Height of an individual line of text. + +The font element can be set as [scriptable option](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/FontCallback.html), providing a [font item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/FontItem.html) instance, as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets options +options.setFont(new FontCallback(){ + + @Override + public Font invoke(DataLabelsContext context){ + FontItem font = new FontItem(); + // your logic + return font; + } +}); +``` + +## Padding + +Every options has got a inner element to set padding options. + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets options +options.getPadding().setTop(12); +``` + +The complete options are described by following table: + +| Name | Type | Default +| :- | :- | :- +| top | int | 4 +| right | int | 4 +| bottom | int | 4 +| left | int | 4 + +The padding element can be set as [scriptable option](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/callbacks/PaddingCallback.html), providing a [padding item](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/PaddingItem.html) instance, as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets options +options.setPadding(new PaddingCallback(){ + + @Override + public PaddingItem invoke(DataLabelsContext context){ + PaddingItem padding = new PaddingItem(); + // your logic + return padding; + } +}); +``` + +## Labels + +By default, a single label is created per data, however, it's possible to define multiple labels for each data element using the labels option. + +This option is an object where each property represents a new label, the key being the label key and the value being the options specific to each label. + +The following example shows how to set multiple labels to a dataset: + +```java +// creates datasest +PieDataset dataset = chart.newDataset(); +// creates plugin options +DataLabelsOptions mainOptionForDataset = new DataLabelsOptions(); +// creates additional "index" label +LabelItem index = mainOptionForDataset.getLabels().createLabel("index"); +index.setAlign(Align.END); +index.setAnchor(Anchor.END); +... // additional label configuration +// creates additional "name" label +LabelItem name = mainOptionForDataset.getLabels().createLabel("name"); +name.setAlign(Align.TOP); +name.getFont().setSize(18); +... // additional label configuration +// stores the options to the dataset +dataset.setOptions(DataLabelsPlugin.ID, mainOptionForDataset); +``` + + + +:::info +Options defined under each labels, always overrides options defined at the chart and dataset level. +::: + +## Anchoring + +An anchor point is defined by an orientation vector and a position on the data element. The orientation depends on the scale type (vertical, horizontal or radial). The position is calculated based on the [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Anchor.html) option and the orientation vector. + +Supported values for [Anchor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Anchor.html): +- `CENTER` (default): element center +- `START`: lowest element boundary +- `END`: highest element boundary + + + +## Clamping + +The clamp option, when `true`, enforces the anchor position to be calculated based on the *visible geometry* of the associated element (i.e. part inside the chart area). + + + +If the element is fully hidden (i.e. entirely outside the chart area), anchor points will **not** be adjusted and thus will also be outside the viewport. + +## Alignment and Offset + +The [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Align.html) option defines the position of the label relative to the anchor point position and orientation. Its value can be expressed either by a number representing the clockwise angle (in degree) or by one of the following string presets: + +- `CENTER` (default): the label is centered on the anchor point +- `START`: the label is positioned before the anchor point, following the same direction +- `END`: the label is positioned after the anchor point, following the same direction +- `RIGHT`: the label is positioned to the right of the anchor point (0) +- `BOTTOM`: the label is positioned to the bottom of the anchor point (90) +- `LEFT`: the label is positioned to the left of the anchor point (180) +- `TOP`: the label is positioned to the top of the anchor point (270) + +The `offset` represents the distance (in pixels) to pull the label *away* from the anchor point. This option is **not applicable** when [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Align.html) is `CENTER'`. Also note that if [Align](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/enums/Align.html) is `START`, the label is moved in the opposite direction. The default value is `4`. + + + +## Rotation + +This option controls the clockwise rotation angle (in degrees) of the label, the rotation center point being the label center. The default value is `0` (no rotation). + +## Visibility + +The [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) option controls the visibility of labels and accepts the following values: + +- `TRUE` (default): the label is drawn +- `FALSE`: the label is hidden +- `AUTO`: the label is hidden if it overlaps with another label + +## Overlap + +The [Display](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/Display.html) is the option can be used to prevent overlapping labels, based on the following rules when two labels overlap: + +- if both labels are `TRUE`, they will be drawn overlapping +- if both labels are `AUTO`, the one with the highest data index will be hidden. If labels are at the same data index, the one with the lowest dataset index will be hidden +- if one label is `TRUE` and the other one is `AUTO`, the one with `AUTO` will be hidden (whatever the data/dataset indices) + +Labels with `FALSE` don't contribute to the overlap detection. + +## Clipping + +When the clip option is `true`, the part of the label which is outside the chart area will be masked. + +## Formatting + +Every label will be drawn with a default behavior. This can be overridden thanks to the `formatter` option and a formatter callback. + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets formatter callback +option.setFormatter(new FormatterCallback(){ + + /** + * Returns the formatted label value. + * + * @param context plugin context instance + * @param dataItem value container to be formatted. + * @return the label value to be showed + */ + @Override + public String invoke(DataLabelsContext context, DataItem dataItem){ + // your logic + return formettedValue; + } +}); +``` + +The [DataItem](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/items/DataItem.html) argument is a wrapper to the possible values that a dataset can contain: + + * doubles. + * strings. + * [FloatingData](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/FloatingData.html), available only for [BAR](../charts/ChartBar#floating-bars) dataset instances. + * [DataPoint](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/data/DataPoint.html). + +### Multiple lines of labels text + +Labels can be displayed on multiple lines by using the newline character (`\n`) between each line or by providing an array of strings where each item represents a new line. + +Example: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets formatter callback +option.setFormatter(new FormatterCallback(){ + + @Override + public String invoke(DataLabelsContext context, DataItem dataItem){ + StringBuffer sb = new StringBuffer(); + sb.append("line1").append('\n').append("line2").append('\n').append(dataItem.getValue()); + return sb.toString(); + } +}); +``` + +The space between each line can be adjusted using the font `lineHeight` option. + +## Text Alignment + +The [textAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html) option only applies to multiple line labels and specifies the text alignment being used when drawing the label text. Note that right-to-left text detection based on the current locale is not currently implemented. + +Supported values for [TextAlign](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/TextAlign.html): + +- `START` (default): the text is left-aligned +- `CENTER`: the text is centered +- `END`: the text is right-aligned +- `LEFT`: alias of `START` +- `RIGHT`: alias of `END` + +## Listeners element + +Every options has got a inner element to set listener handlers. + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets "enter" event handler +option.getListeners().setEnterEventHandler(new EnterEventHandler(){ + + @Override + public boolean onEnter(DataLabelsContext context, ChartEventContext event){ + IsChart chart = context.getChart(); + chart.getCanvas().getElement().getStyle().setCursorType(CursorType.POINTER); + return true; + } +}); +// sets "leave" event handler +option.getListeners().setLeaveEventHandler(new LeaveEventHandler(){ + + @Override + public boolean onLeave(DataLabelsContext context, ChartEventContext event){ + IsChart chart = context.getChart(); + chart.getCanvas().getElement().getStyle().setCursorType(CursorType.DEFAULT); + return true; + } +}); +``` + +The [listeners element](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/Listeners.html) allows to register callbacks to be notified when an event is detected on a specific label. This option is an object where the property is the type of the event to listen and the value is a callback with the [context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsContext.html) and [event](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/ChartEventContext.html) arguments. + +The [context](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/DataLabelsContext.html) contains the same information as for other callbacks, can be modified (e.g. add new options, by `context.setOptions` method) and thus, if the callback explicitly returns `true`, the label is updated with the new context and the chart re-rendered. This allows to implement visual interactions with labels such as highlight, selection, etc. + +Listeners can be registered for any label at chart level or for labels of a specific dataset. + +If no listener is registered, incoming events are immediately ignored, preventing extra computation such as intersecting label bounding box. That means there should be no performance penalty for configurations that don't use events. + +### Events + +This plugin currently supports the following label events and interface to be implemented: + +| **Name** | **Charba events** | **Description** +| :- | :- | :- +| enter | `mousemove` | the mouse is moved over a label. See [EnterEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/events/EnterEventHandler.html) +| leave | `mousemove` | the mouse is moved out of a label. See [LeaveEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/events/LeaveEventHandler.html) +| click | `click` | the mouse's primary button is pressed and released on a label. See [ClickEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/events/ClickEventHandler.html) + +**Charba** event that need to be enabled in order to get the associated label event working. + +**Charba** provides an abstract handler implementation with all interfaces ([AbstractEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/datalabels/events/AbstractEventHandler.html)) which can be extended, only with needed methods, and add easily as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// sets event handlers +options.setListenersHandler(new AbstractEventHandler(){ + + // overrides methods + +}); +``` + +## Options builder + +**Charba** provides a builder to create options using the **set** methods in sequence and get the options object at the end of configuration. + +```java +// creates plugin options +DataLabelsOptions options = DataLabelsOptionsBuilder.create() + .setAlign(Align.center) + .setBackgroundColor(new ColorCallback(){ + + @Override + public IsColor invoke(DataLabelsContext context){ + IsChart chart = context.getChart(); + List datasets = chart.getData().getDatasets(); + LineDataset dataset = (LineDataset)datasets.get(context.getDatasetIndex()); + return dataset.getBackgroundColor(); + } + }).build(); +// stores plugin options to the chart +chart.getOptions().getPlugins().setOptions(DataLabelsPlugin.ID, options); +``` + +Creating a build by `DataLabelsOptionsBuilder.create()` it will use the global options as default, instead by `DataLabelsOptionsBuilder.create(chart)` it will use the global chart options as default. + +## Out-of-the-box implementations + +**Charba** provides some callbacks implementations, developed for common purposes. + +### Cursor handler + +**Charba** provides a common listener handler for [listener](#listeners-element) to change the cursor type when the labels are clickable. + +To apply the handler, you can set an instance to the plugin options, as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// creates the handler instance +// uses the CursorType.POINTER +DataLabelsPointerHandler handler = new DataLabelsPointerHandler(); +// sets the handler +options.setListenersHandler(handler); +``` + +The handler can be customized at constructor level, setting which [cursor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/CursorType.html) must be used hovering the labels, as following: + +```java +// creates the handler instance +// uses the CursorType.POINTER +DataLabelsPointerHandler handler = new DataLabelsPointerHandler(); +// creates the handler instance +// uses the CursorType.CROSSHAIR +DataLabelsPointerHandler handler = new DataLabelsPointerHandler(CursorType.CROSSHAIR); +``` + +### Selection handler + +**Charba** provides a common listener handler for [listener](#listeners-element) to invoke data set selection handlers if there were defined. The handler accepts [DatasetSelectionEventHandler](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/events/DatasetSelectionEventHandler.html) instances in order to notify which data set has been selected clicking on the label. + +To apply a callback, you can set an instance to the plugin options, as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// creates the handler instance +DataLabelsSelectionHandler handler = new DataLabelsSelectionHandler(); +// adds the handler +handler.addDatasetSelectionEventHandler(new DatasetSelectionEventHandler(){ + + /** + * Invoked when the user clicks on the chart to select a data set. + * + * @param event chart data set selection event + */ + @Override + public void onSelect(DatasetSelectionEvent event){ + // logic + } +}); + +DataLabelsOptions options = new DataLabelsOptions(); +options.setListenersHandler(handler); +``` + +Against to the [data set selection event handler](../configuration/Interaction#selecting-a-dataset), at chart level, this invocation is synchronous. + +The handler can be customized at constructor level, setting which [cursor](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/dom/enums/CursorType.html) must be used hovering the labels, as following: + +```java +// creates the handler instance +// uses the CursorType.POINTER +DataLabelsSelectionHandler handler = new DataLabelsSelectionHandler(); +// creates the handler instance +// uses the CursorType.CROSSHAIR +DataLabelsSelectionHandler handler = new DataLabelsSelectionHandler(CursorType.CROSSHAIR); +``` + +### Percentage formatter + +**Charba** provides a common callback for [formatter](DataLabels#formatting) in order to provide the percentage of the value for each data index per dataset. + +To apply the callback, you can set an instance to the plugin options, as following: + +```java +// creates plugin options +DataLabelsOptions options = new DataLabelsOptions(); +// creates the callback +PercentageCallback callback = new PercentageCallback(); +// sets the callback as formatter +options.setFormatter(callback); +``` + +The handler can be customized at constructor level, setting: + + * decimal precision, in order to have a good number of decimal digits of percentage to show. Default is **2**; + * stacked, as boolean argument, in order to calculate the percentage on the total of the dataset (`false`) or using the same data index of stacked datasets (`true`). Default is `false`. diff --git a/versioned_docs/version-6.5/extensions/Extensions.md b/versioned_docs/version-6.5/extensions/Extensions.md new file mode 100644 index 000000000..afbc7a048 --- /dev/null +++ b/versioned_docs/version-6.5/extensions/Extensions.md @@ -0,0 +1,21 @@ +--- +id: Extensions +title: Extensions +hide_title: true +sidebar_label: Introduction +--- +## Extensions + +**Charba** provides out of the box the feature to enable some available plugins for [Chart.JS](http://www.chartjs.org/), with all their capabilities. + +The plugins are *native javascript* implementation and **Charba** provides the wrapper in order to be able to use them. + +Currently the extensions, ready to use inside **Charba**, are the following: + + * [Annotation](Annotation) which can add annotations (like boxes, lines, points or ellipses) on a chart instance. + * [DataLabels](DataLabels) which is a highly customizable plugin that displays labels on data for any type of charts. + * [Labels](Labels) which is a light weight plugin to display labels on pie, doughnut and polar area chart. Original PieceLabel. + * [Zoom](Zoom) which is a light weight plugin to zoom and pan a chart. + * [Gradient](Gradient) which is a light weight plugin to apply gradients to the datasets by data values. + +In this way, the user doesn't have to take care about compatibility of different versions because they are provided as components of **Charba** and they can be activate on demand. diff --git a/versioned_docs/version-6.5/extensions/Gradient.md b/versioned_docs/version-6.5/extensions/Gradient.md new file mode 100644 index 000000000..2598aaf55 --- /dev/null +++ b/versioned_docs/version-6.5/extensions/Gradient.md @@ -0,0 +1,124 @@ +--- +id: Gradient +title: Gradient plugin +hide_title: true +sidebar_label: Gradient +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Gradient plugin + +**Charba** provides out of the box the feature to enable [Gradient](https://github.com/kurkle/chartjs-plugin-gradient) which is a light weight plugin to apply gradients to the datasets by data values. + + + +## Activation + +The gradient plugin is injected directly in the document. + +The plugin ID is a constant everywhere available, `GradientPlugin.ID`, in [GradientPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/GradientPlugin.html) entry point. + +This plugin registers itself globally, meaning that once injected, all charts will enable zooming. In case you want it enabled only for a few charts, you can enable it as following: + +```java +// -------------------------------------- +// enabling the plugin without any parameter +// the plugin is NOT registered to all charts +// -------------------------------------- +GradientPlugin.enable(); + +// -------------------------------------- +// enabling the plugin with `true` parameter +// the plugin is registered to all charts +// -------------------------------------- +GradientPlugin.enable(true); +``` + +To activate the plugin in a specific chart, it's enough to provide the configuration options (see [below](#configuration)) to the datasets, which should be rendered by the gradient, or enabling it by: + +```java +// -------------------------------------- +// ENABLING the plugin to a chart instance +// storing a plugin options +// -------------------------------------- +// creates chart +LineChart chart = new LineChart(); +// creates dataset +LineDataset dataset = chart.newDataset(); +// creates a plugin options +GradientOptions options = new GradientOptions(); +// gets background color property options +PropertyOptions propOptions = options.getBackgroundColor(); +// sets axis kind to apply gradient +propOptions.setAxis(AxisKind.Y); +// gets colors +Colors stopColors = propOptions.getColors(); +// sets color at different data value +stopColors.setColor(0, HtmlColor.GREEN); +stopColors.setColor(50, HtmlColor.YELLOW); +stopColors.setColor(100, HtmlColor.RED); +// sets plugin options to dataset +dataset.setOptions(options); +``` + +## Configuration + +The plugin options can be changed at only at dataset level by `dataset.setOptions` method. + +The configuration class [GradientOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/GradientOptions.html) contains all properties needed to configure the plugin. + +The complete options are described by following table: + +| Name | Type | Description +| :- | :- | :----- +| backgroundColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as background color of the dataset. +| borderColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as border color of the dataset. +| hoverBackgroundColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as background color of the dataset, when hovered. +| hoverBorderColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as border color of the dataset, when hovered. +| pointBackgroundColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as background color of the points of the dataset. +| pointBorderColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as border color of the points of the dataset. +| pointHoverBackgroundColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as background color of the points of the dataset, when hovered. +| pointHoverBorderColor | [PropertyOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/PropertyOptions.html) | Sets the gradient as border color of the points of the dataset, when hovered + +## Property options + +The property option enables the configuration of the gradient, like the orientation, based on the axis related to the dataset, and the colors for a specific dataset option. + +```java +// creates a plugin options +GradientOptions options = new GradientOptions(); +// gets background color property options +PropertyOptions propOptions = options.getBackgroundColor(); +// sets axis kind to apply gradient +propOptions.setAxis(AxisKind.Y); +``` + +The complete options are described by following table: + +| Name | Type | Description +| :- | :- | :- +| axis | [AxisKind](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/enums/AxisKind.html) | The axis to use for applying the gradient to the dataset. +| colors | [Colors](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/gradient/Colors.html) | Sets the colors to composed the gradient + + + +## Colors + +The colors option enables to adds color stop, defined by a data value and a color, to a given canvas gradient. + +```java +// creates a plugin options +GradientOptions options = new GradientOptions(); +// gets background color property options +PropertyOptions propOptions = options.getBackgroundColor(); +// sets axis kind to apply gradient +propOptions.setAxis(AxisKind.Y); +// gets colors +Colors stopColors = propOptions.getColors(); +// sets color at different data value +stopColors.setColor(0, HtmlColor.GREEN); +stopColors.setColor(50, HtmlColor.YELLOW); +stopColors.setColor(100, HtmlColor.RED); +``` + +The colors stop data value can be a String, double or a date, related to the axis defined to be used for gradient creation. diff --git a/versioned_docs/version-6.5/extensions/Labels.md b/versioned_docs/version-6.5/extensions/Labels.md new file mode 100644 index 000000000..3da2b3fd6 --- /dev/null +++ b/versioned_docs/version-6.5/extensions/Labels.md @@ -0,0 +1,378 @@ +--- +id: Labels +title: Labels plugin +hide_title: true +sidebar_label: Labels +--- +import useBaseUrl from '@docusaurus/useBaseUrl'; + +## Labels plugin + +**Charba** provides out of the box the feature to enable [Labels](https://github.com/emn178/chartjs-plugin-labels) which is a light weight plugin to display labels on pie, doughnut, polar area and bar chart (former name was PieceLabel). + + + +
+
+ +:::info +The plugin has been heavily changed in order to be compliant with [Chart.JS](http://www.chartjs.org/) version 3.x) in the **Charba** [project](https://github.com/pepstock-org/Charba/blob/master/src/org/pepstock/charba/client/resources/js/chartjs-plugin-labels.js) because the [original project](https://github.com/emn178/chartjs-plugin-labels) is unmaintained. +::: + +## Activation + +The labels plugin is injected directly in the document. + +The plugin ID is a constant everywhere available, `LabelsPlugin.ID`, in [LabelsPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelsPlugin.html) entry point. + +This plugin registers itself globally, meaning that once injected, all charts will display labels. In case you want it enabled only for a few charts, you can enable it as following: + +```java +// -------------------------------------- +// enabling the plugin without any parameter +// the plugin is NOT registered to all charts +// -------------------------------------- +LabelsPlugin.enable(); + +// -------------------------------------- +// enabling the plugin with `true` parameter +// the plugin is registered to all charts +// -------------------------------------- +LabelsPlugin.enable(true) +``` + +To activate the plugin in a specific chart, it's enough to provide the configuration options (see [below](#configuration)) or enabling it by: + +```java +// -------------------------------------- +// ENABLING the plugin to a chart instance +// storing a plugin options +// -------------------------------------- +// creates a plugin options +LabelsOptions options = new LabelsOptions(); +// creates a label by "myLabel" id +Label label = options.createLabel("myLabel"); +// sets the render +label.setRender(Render.LABEL); +// stores the plugin options directly by the options +options.store(chart); + +// -------------------------------------- +// ENABLING the plugin to a chart instance +// by a boolean using default plugin +// options +// -------------------------------------- +chart.getOptions().getPlugins().setEnabled(DataLabelsPlugin.ID, true); +``` + +## Configuration + +The plugin options can be changed at 2 different levels and are evaluated with the following priority: + + * per chart by `chart.getOptions().getPlugins().setOptions` method + * or globally by `Defaults.get().getGlobal().getPlugins().setOptions` method + +The configuration [LabelsOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelsOptions.html) class is the entry point of plugin configuration. + +Every [label](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/Label.html) configuration can be add to the [LabelsOptions](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelsOptions.html), assigning a unique id. + +The id of a label configuration can be set by a string or by a specific class, [LabelId](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelId.html). + +```java +// ------------------------ +// CONFIGURES the label by +// LabelId id +// ------------------------ +// creates a plugin options +LabelsOptions options = new LabelsOptions(); +// creates label id +LabelId labelId = LabelId.create("myLabel1"); +// creates and adds a label by "myLabel1" id +Label label = options.createLabel(labelId); +// sets the render +label.setRender(Render.PERCENTAGE); +... // additional label configuration +// stores the plugin options directly by the options +options.store(); +``` + +The below example is showing how to create and add 2 labels (each one must have a unique id): + +```java +// ------------------------ +// CONFIGURES the multiple +// labels +// ------------------------ +// creates a plugin options +LabelsOptions options = new LabelsOptions(); +// creates and adds a label by "myLabel1" id +Label label1 = options.createLabel(LabelId.create("myLabel1")); +// sets the render +label1.setRender(Render.LABEL); +... // additional label configuration +// creates and adds a label by "myLabel2" id +Label label2 = options.createLabel("myLabel2"); +// sets the render +label2.setRender(new RenderCallback(){ + + @Override + public String invoke(LabelsContext context){ + return "$$ "+ (int)(context.getValue() * context.getPercentage() / 100); + } +}); +... // additional label configuration +// stores the plugin options directly by the options +options.store(); +``` + + + +You can also change the default for all charts instances, as following: + +```java +// creates a plugin options +LabelsOptions options = new LabelsOptions(); +// creates a label by "myLabel" id +Label label = options.createLabel("myLabel"); +// sets the render +label.setRender(Render.LABEL); + +// -------------------------------------- +// STORING plugin options +// -------------------------------------- +// stores the plugin options by plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(LabelsPlugin.ID, options); +// stores the plugin options without plugin ID +Defaults.get().getGlobal().getPlugin().setOptions(options); +// stores the plugin options directly by the options +options.store(); +``` + +If you need to read the plugin options, there is the specific factory, [LabelsOptionsFactory](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelsOptionsFactory.html) as static reference inside the [LabelsPlugin](https://pepstock-org.github.io/Charba/6.5/org/pepstock/charba/client/labels/LabelsPlugin.html) entry point which can be used to retrieve the options from chart as following: + +```java +// gets options reference +LabelsOptions options; + +// -------------------------------------- +// GETTING plugin options from chart +// -------------------------------------- +if (chart.getOptions().getPlugin().hasOptions(LabelsPlugin.ID)){ + // retrieves the plugin options by plugin ID + options = chart.getOptions().getPlugin().getOptions(LabelsPlugin.ID, LabelsPlugin.FACTORY); + //retrieves the plugin options without plugin ID + options = chart.getOptions().getPlugin().getOptions(LabelsPlugin.FACTORY); +} +``` + +You can access to the configured labels configurations as following: + +```java +// ------------------------ +// GETS the configured +// labels +// ------------------------ +// retrieves the plugin options by plugin ID +LabelsOptions options = chart.getOptions().getPlugin().getOptions(LabelsPlugin.FACTORY); +// gets all labels configurations +List