Package com.jbstrap.ui.components.charts

Class GaugeChart

java.lang.Object
com.jbstrap.ui.components.charts.BaseChart<T>
com.jbstrap.ui.components.charts.SeriesBasedChart<GaugeChart>
com.jbstrap.ui.components.charts.GaugeChart
All Implemented Interfaces:
DataDescriptorCallback, ClickableChartData<GaugeChart>, MultiSeriesChart<GaugeChart,GaugeSeries>
public class GaugeChart extends SeriesBasedChart<GaugeChart> implements MultiSeriesChart<GaugeChart,GaugeSeries>, ClickableChartData<GaugeChart>

A gauge chart is a chart resembling an analog instrument where one or more needles indicate the measured value. The chart is capable of displaying multiple series, but each series can only contain one type of data. Each series is represented on the chart as a separate needle. Also, you can specify one or more ranges and sections. These are represented as colored arcs on the circumference of the instrument’s scale. By default, if you do not specify any sections, the chart area is divided into three parts of equal size. You can specify the starting value and color of each section. The default colors are red, yellow and green. The chart’s default display is setting is a speedometer gauge speedometer. A speedometer’s readings increase from the left to the right, the minimum value being on the left side and the maximum value being on the right side. If the specified value does not fall into to the measured range (it is below the lower threshold or above the upper threshold), the needle points to the lower or upper thresholds. You can also modify the visualization type, making it possible to change the shape of the instrument. The instrument can also be a semicircle facing the right or the left, or even a horizontal semicircle.

This chart is does not allow you to modify the tooltip, you can only use a DOT. However, the chart enables you to create custom tooltips using any JBStrap component. If you want to display a tooltip that is different from the default one, you need to create it on your own using ChartTooltipRenderer. You only need to implement one method which returns the tooltip as a component. In order to do this, you can reuse any JBStrap component. It is possible to display a button, a list or even another chart on the tooltip.

The chart also supports click event handling. This means that you can implement server-side business logic for the event that is triggered when a user clicks on chart data. This is when a ChartClick event is triggered. This event provides you information on where and which chart the user clicked on. This can be reused in various ways, e.g. to update a list.

Since:
4.0
Author:
JBStrap
See Also:

  • Field Details

  • Constructor Details

    • GaugeChart

      public GaugeChart(String name)
      Creates the gauge chart.
      Parameters:
      name - Chart name It is mandatory to specify the chart name and it must be unique within the ChartCanvas. Later on, you can reference the chart with the name specified here.
      Throws:
      NullPointerException - Thrown if the specified name is null or it is an empty string

    • GaugeChart

      public GaugeChart(String name, DataDescriptor dataDescriptor, String categoryColumnName)
      Creates the gauge chart component and sets the name of the DataDescriptor and that of the category column.
      Parameters:
      name - Chart name It is mandatory to specify the chart name and it must be unique within the ChartCanvas. Later on, you can reference the chart with the name specified here.
      dataDescriptor - The DataDescriptor that contains the chart data
      categoryColumnName - The name of the DataDescriptor containing X axis data If not specified, or null is specified, the framework starts looking for the “CATEGORY” column.
      Throws:
      NullPointerException - Thrown if the specified name is null or it is an empty string
      IllegalArgumentException - Thrown if the column specified in the categoryColumnName parameter is not found in the DataDescriptor or if the categoryColumnName parameter is not specified and no “CATEGORY” column is found in the DataDescriptor.

  • Method Details

    • getSections

      public List<GaugeChartSection> getSections()
      Gets the chart’s sections.
      Returns:
      A list containing the chart’s section data

    • init

      protected void init()
      Description copied from class: BaseChart
      Chart initialization.
      Specified by:
      init in class BaseChart<GaugeChart>

    • setType

      public GaugeChart setType(GaugeChartType type)
      Sets the chart’s display type. The default display setting for the chart is GaugeChartType.SPEEDOMETER.
      Parameters:
      type - Display type Available types are listed in the enum GaugeChartType. If null is specified, the default setting GaugeChartType.SPEEDOMETER will apply.
      Returns:
      Chart instance

    • getType

      public GaugeChartType getType()
      Gets the chart’s display type.
      Returns:
      Chart display type

    • setTickCount

      public GaugeChart setTickCount(TickNumbers tickNumber)
      Sets the number of ticks based on the tick type. The default display setting for the chart is TickNumbers.SECTIONED.
      Parameters:
      tickNumber - The number of ticks on the chart Available values are listed in the enum TickNumbers. If null is specified, the chart is displayed with the default settings.
      Returns:
      Chart instance

    • setTickCount

      public GaugeChart setTickCount(int tickCount)
      Sets the number of ticks displayed on the chart.
      Parameters:
      tickCount - The number of ticks on the chart If a number smaller than 0 is specified, the number of ticks is automatically determined using the TickNumbers.SECTIONED setting.
      Returns:
      Chart instance

    • getTickNumbers

      public Object getTickNumbers()
      Gets the number of ticks displayed on the chart.
      Returns:
      The number of ticks as an Integer or a member of the TickNumbers enum if the number of ticks is automatically determined based on a type

    • setShowValueLabel

      public GaugeChart setShowValueLabel(boolean showValueLabel)
      Sets if value labels should be displayed on the chart. The value is displayed below the needle on the scale. By default, this setting is not enabled. This setting is applicable only if there is one needle on the chart.
      Parameters:
      showValueLabel - If true is specified, the value label appears on the chart alongside the needle Otherwise, the value label is not visible.
      Returns:
      Chart instance

    • isShowValueLabel

      public boolean isShowValueLabel()
      Checks if the needle’s value label (the measured reading of the gauge) is also displayed on the chart.
      Returns:
      If true, the measured reading is also displayed on the chart Otherwise it false.

    • setValueLabelSize

      public GaugeChart setValueLabelSize(int size)
      Sets the displayed value label’s font size. The default font size setting is 28 pixels for the measured gauge reading.
      Parameters:
      size - The font size of the measured gauge reading in pixels
      Returns:
      Chart instance

    • getValueLabelSize

      public int getValueLabelSize()
      Gets the font size of measured gauge reading.
      Returns:
      The font size of the measured gauge reading in pixels

    • setShowDataLabels

      public GaugeChart setShowDataLabels(boolean showDataLabels)
      Sets if the chart sections should display data labels. The default setting for data labels is enabled.
      Parameters:
      showDataLabels - If true is specified, data labels are on If false, data labels are turned off.
      Returns:
      Chart instance

    • isShowDataLabels

      public boolean isShowDataLabels()
      Checks if section data labels are visible on the chart.
      Returns:
      If true, section data labels are on Otherwise it false.

    • setPadding

      public GaugeChart setPadding(double padding)
      Sets the size of the padding between chart sections. The default padding for chart sections is 0.01.
      Parameters:
      padding - Padding (between 0 and 1)
      Returns:
      Chart instance

    • getPadding

      public double getPadding()
      Gets the size of the padding between chart sections.
      Returns:
      Padding (between 0 and 1)

    • setCornerRadius

      public GaugeChart setCornerRadius(int radius)
      Sets the rounding radius for chart section corners. The default rounding setting is 0, that is, chart section corners are not rounded.
      Parameters:
      radius - Rounding radius of chart section corners in pixels
      Returns:
      Chart instance

    • getCornerRadius

      public int getCornerRadius()
      Gets the rounding radius of chart section corners.
      Returns:
      Rounding radius of chart section corners in pixels

    • setThickness

      public GaugeChart setThickness(Integer thickness)
      Sets the thickness of the arc on the chart. The default thickness setting for the gauge chart arc is 38%.
      Parameters:
      thickness - The thickness of the gauge chart arc in percentage If 0 or a smaller value is specified, the chart does not show. If 100 or a greater value is specified, the chart fill all available area.
      Returns:
      Chart instance

    • getThickness

      public Integer getThickness()
      Gets the thickness of the gauge chart arc.
      Returns:
      Chart arc thickness in percentage

    • setColorTemplate

      public GaugeChart setColorTemplate(ColorTemplate template)
      Set the chart’s color scheme. The default color scheme setting for the chart is ColorTemplate.RED_TO_GREEN: lower values are displayed as red, higher values are displayed as green. The section color between the first and the last sections is automatically determined.
      Parameters:
      template - The chart’s color scheme Available values are listed in the enum ColorTemplate. If null is specified, the chart uses the default color scheme.
      Returns:
      Chart instance

    • getColorTemplate

      public ColorTemplate getColorTemplate()
      Gets the default color scheme.
      Returns:
      The chart’s default color scheme

    • setColorRange

      public GaugeChart setColorRange(String... colors)
      Sets a custom color scheme. This method sets the chart’s section colors using the colors specified in the parameters. If fewer colors are specified than the number of sections on the chart, the “missing” section colors are automatically updated with colors between the specified ones.
      Parameters:
      colors - A list of section colors as defined by the CSS3 standard
      Returns:
      Chart instance

    • getColorRange

      public List<String> getColorRange()
      Gets the previously defined color scheme.
      Returns:
      A list containing the chart’s previously specified color scheme If there is no previously specified color scheme, the method returns null.

    • addSeries

      public GaugeChart addSeries(Series series)
      Adds a new series to the chart.
      Specified by:
      addSeries in interface MultiSeriesChart<GaugeChart,GaugeSeries>
      Parameters:
      series - Series instance to be added
      Returns:
      Chart

    • setMin

      public GaugeChart setMin(double min)
      The minimum gauge chart reading (starting value). The default minimum value is 0.
      Parameters:
      min - Chart’s minimum value
      Returns:
      Chart instance

    • getMin

      public double getMin()
      Gets the chart’s minimum value.
      Returns:
      Chart’s minimum value

    • setMax

      public GaugeChart setMax(double max)
      The maximum gauge chart reading (end value).
      Parameters:
      max - Displayed maximum value
      Returns:
      Chart instance

    • getMax

      public double getMax()
      Gets the chart’s maximum value.
      Returns:
      The chart’s maximum value

    • createSection

      public GaugeChart createSection(String name, double start)
      Creates a new chart section. By default, the chart is divided into three sections of equal size. By adding sections, you further divide the chart. Default (initial) sections are deleted and only the new (added) sections remain.
      Parameters:
      name - Section name
      start - Starting value of the section
      Returns:
      Chart instance

    • createSection

      public GaugeChart createSection(String name, double start, String color)
      Creates a new chart section. By default, the chart is divided into three sections of equal size. By adding sections, you further divide the chart. Default (initial) sections are deleted and only the new (added) sections remain.
      Parameters:
      name - Section name
      start - Starting value of the section
      color - Section color as defined by the CSS3 standard
      Returns:
      Chart instance

    • getSectionByName

      public GaugeChartSection getSectionByName(String name)
      Gets a section of the chart by its specified name.
      Parameters:
      name - Section name
      Returns:
      The data of the specified section or null if there is no section with the specified name

    • removeSections

      public GaugeChart removeSections(String name)
      Removes the specified section from the chart. If the last section is removed, the chart is automatically divided into three sections of equal size.
      Parameters:
      name - Section name
      Returns:
      Chart instance

    • setSectionColor

      public GaugeChart setSectionColor(String name, String color)
      Sets a chart’s section color.
      Parameters:
      name - Section name Ha null, or a name is specified that has no corresponding sections on the chart, the method does nothing.
      color - Section color as defined by the CSS3 standard
      Returns:
      Chart instance

    • setScaleStartValue

      public GaugeChart setScaleStartValue(String name, double start)
      Modifies the section’s initial value.
      Parameters:
      name - Section name Ha null, or a name is specified that has no corresponding sections on the chart, the method does nothing.
      start - Starting value of the section
      Returns:
      Chart instance

    • changeSectionName

      public GaugeChart changeSectionName(String oldName, String newName)
      Modifies the section’s name.
      Parameters:
      oldName - The original name of the section you want to modify Ha null, or a name is specified that has no corresponding sections on the chart, the method does nothing.
      newName - New section name
      Returns:
      Chart instance

    • refreshScale

      protected void refreshScale()