Class ConfigurationOptions

  • All Implemented Interfaces:
    HasAnimation, ConfigurationElement, AddHandlerEventHandler, EventHandler, RemoveHandlerEventHandler
    Direct Known Subclasses:
    AbstractPieOptions, ScalesOptions, TreeMapOptions

    public abstract class ConfigurationOptions
    extends Object
    implements ConfigurationElement, HasAnimation
    Base object which maps chart configuration.
    CHARBA stores the unique chart ID in the CHART.JS chart options using charbaId property key.
    Important topics to take care:
    Responsive
    When it comes to change the chart size based on the window size, a major limitation is that the canvas render size (canvas.width and .height) can not be expressed with relative values, contrary to the display size (canvas.style.width and .height). 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.
    It provides a few 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.
    Legend
    Sometimes you need a very complex legend. In these cases, it makes sense to generate an HTML legend. Charts provide a generateLegend() method on their prototype that returns an HTML string for the legend. To configure how this legend is generated, you can set the legendCallback.
    Author:
    Andrea "Stock" Stocchero
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void afterAxisConfigurationUpdate​(Axis axis)
      Invoked after the axis options has been updated.
      protected void afterConfigurationUpdate()
      Invoked after the chart options has been updated.
      protected void beforeAxisConfigurationUpdate​(Axis axis)
      Invoked before the axis options are going to be updated.
      protected void beforeConfigurationUpdate()
      Invoked before the chart options are going to be updated.
      AnimationContainer getAnimationContainer()
      Returns an animation container instance to use in the default methods of this interface.
      double getAspectRatio()
      Canvas aspect ratio (i.e.
      protected Axis getAxisById​(int id)
      Returns the axis by the unique CHARBA id of scale or null if not axis.
      IsColor getBackgroundColor()
      Returns the default background color to use in the chart, on all objects, if not override by the specific configuration.
      String getBackgroundColorAsString()
      Returns the default background color to use in the chart, on all objects, if not override by the specific configuration.
      IsColor getBorderColor()
      Returns the default border color to use in the chart, on all objects, if not override by the specific configuration.
      String getBorderColorAsString()
      Returns the default border color to use in the chart, on all objects, if not override by the specific configuration.
      IsChart getChart()
      Returns the chart instance
      IsColor getColor()
      Returns the default color to use in the chart, on all objects, if not override by the specific configuration.
      String getColorAsString()
      Returns the default color to use in the chart, on all objects, if not override by the specific configuration.
      protected T getConfiguration()
      Returns the configuration element.
      Datasets getDatasets()
      Returns the data sets element.
      double getDevicePixelRatio()
      The chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g.
      Elements getElements()
      Returns the elements element.
      Set<IsEvent> getEvents()
      Returns the browser events that the chart should listen to.
      Filler getFiller()
      Returns the filler plugin configuration.
      Font getFont()
      Returns the font element.
      Hover getHover()
      Returns the hover element.
      Interaction getInteraction()
      Returns the interaction element.
      Layout getLayout()
      Returns the layout element.
      Legend getLegend()
      Returns the legend element.
      CLocale getLocale()
      Returns the locale instance for internationalization.
      Plugins getPlugins()
      Returns the plugins element.
      double getResizeDelay()
      Returns the delay the resize update by give amount of milliseconds.
      This can ease the resize process by debouncing update of the elements.
      Subtitle getSubtitle()
      Returns the subtitle element.
      Title getTitle()
      Returns the title element.
      Tooltips getTooltips()
      Returns the tooltips element.
      boolean hasAxisClickHandlers()
      Returns true if there is any axis click handler, otherwise false.
      boolean hasAxisEnterHandlers()
      Returns true if there is any axis enter handler, otherwise false.
      boolean hasAxisHoverHandlers()
      Returns true if there is any axis hover handler, otherwise false.
      boolean hasAxisLeaveHandlers()
      Returns true if there is any axis leave handler, otherwise false.
      boolean hasDatasetSelectionHandlers()
      Returns true if there is any data set selection handler, otherwise false.
      boolean hasSubtitleClickHandlers()
      Returns true if there is any subtitle click handler, otherwise false.
      boolean hasSubtitleEnterHandlers()
      Returns true if there is any subtitle enter handler, otherwise false.
      boolean hasSubtitleLeaveHandlers()
      Returns true if there is any subtitle leave handler, otherwise false.
      boolean hasTitleClickHandlers()
      Returns true if there is any title click handler, otherwise false.
      boolean hasTitleEnterHandlers()
      Returns true if there is any title enter handler, otherwise false.
      boolean hasTitleLeaveHandlers()
      Returns true if there is any title leave handler, otherwise false.
      boolean isAutoColors()
      Returns true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets.
      boolean isAutoColorsForceOverride()
      By default the colors plugin only works when you initialize the chart without any colors for the border or background specified.
      If you want to force the colors plugin to always color your datasets, for example when using dynamic datasets at runtime you will need to set the forceOverride option to true.
      boolean isDestroyOnDetach()
      Returns true if the chart is configured to be destroyed on the detach from DIV element, otherwise false.
      boolean isDrawOnAttach()
      Returns true if the chart is configured to be drawn on the attach of DIV element, otherwise false.
      boolean isMaintainAspectRatio()
      Returns the maintaining of the original canvas aspect ratio (width / height) when resizing.
      boolean isResponsive()
      Returns the resizing of the chart canvas when its container does.
      void load​(IsChart chart, Configuration configuration)
      Called to enable to load in the a configuration object the specific configuration item (by native object).
      ChartEnvelop<NativeObject> loadNativeObject​(ChartEnvelop<NativeObject> envelop)
      Returns the native object instance inside an envelop.
      It can be called only from org.pepstock.charba.client package.
      void loadOptions​(ChartEnvelop<NativeObject> envelop)
      Merges chart default options (by chart.defaults[type]), default scale options (by chart.defaults.scale) and global options (by chart.defaults.global) and chart options.
      The chain of priority is:
      chart options chart default options (by chart.defaults[type]) default scale options (by chart.defaults.scale) global options (by chart.defaults.global)
      void merge​(NativeObjectContainer source, String property)
      Merge a native object in the this one with a specific property name.
      This is used by plugins implementation (native java script ones) when they are not using the standard way to add plugin configuration in the options of chart.
      void onAdd​(AddHandlerEvent event)
      Invoked when a new event handler is added.
      void onRemove​(RemoveHandlerEvent event)
      Invoked when a chart event handler is removed.
      void setAspectRatio​(double ratio)
      Canvas aspect ratio (i.e.
      void setAutoColors​(boolean enabled)
      Sets true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets.
      void setAutoColorsForceOverride​(boolean forceOverride)
      By default the colors plugin only works when you initialize the chart without any colors for the border or background specified.
      If you want to force the colors plugin to always color your datasets, for example when using dynamic datasets at runtime you will need to set the forceOverride option to true.
      void setBackgroundColor​(String backgroundColor)
      Sets the default background color to use in the chart, on all objects, if not override by the specific configuration.
      void setBackgroundColor​(IsColor backgroundColor)
      Sets the default background color to use in the chart, on all objects, if not override by the specific configuration.
      void setBorderColor​(String borderColor)
      Sets the default border color to use in the chart, on all objects, if not override by the specific configuration.
      void setBorderColor​(IsColor borderColor)
      Sets the default border color to use in the chart, on all objects, if not override by the specific configuration.
      void setChartOptions​(ChartEnvelop<NativeObject> envelop)
      Sets the chart options as underlying configuration options, after the first draw of the chart.
      Leveraging on proxy, this is mandatory and enables the possibility to use only the configuration options to update the chart options at runtime.
      void setColor​(String color)
      Sets the default color to use in the chart, on all objects, if not override by the specific configuration.
      void setColor​(IsColor color)
      Sets the default color to use in the chart, on all objects, if not override by the specific configuration.
      protected void setConfiguration​(T configuration)  
      void setDestroyOnDetach​(boolean destroyOnDetach)
      Sets true if the chart is configured to be destroyed on the detach from DIV element, otherwise false.
      void setDevicePixelRatio​(double ratio)
      The chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g.
      void setDrawOnAttach​(boolean drawOnAttach)
      Sets true if the chart is configured to be draw on the attach of DIV element, otherwise false.
      void setEvents​(Set<IsEvent> events)
      Sets the browser events that the chart should listen to.
      void setEvents​(IsEvent... events)
      Sets the browser events that the chart should listen to.
      void setLocale​(CLocale locale)
      Sets the locale instance for internationalization.
      void setMaintainAspectRatio​(boolean maintainAspectRatio)
      Sets the maintaining of the original canvas aspect ratio (width / height) when resizing.
      void setResizeDelay​(int delay)
      Sets the delay the resize update by give amount of milliseconds.
      This can ease the resize process by debouncing update of the elements.
      void setResponsive​(boolean responsive)
      Sets the resizing of the chart canvas when its container does.
      String toJSON()
      Returns the JSON representation of the object.
    • Constructor Detail

      • ConfigurationOptions

        protected ConfigurationOptions​(IsChart chart,
                                       IsDefaultScaledOptions defaultValues)
        Builds the object storing the chart instance and defaults options.
        Parameters:
        chart - chart instance
        defaultValues - defaults options
    • Method Detail

      • loadOptions

        public final void loadOptions​(ChartEnvelop<NativeObject> envelop)
        Merges chart default options (by chart.defaults[type]), default scale options (by chart.defaults.scale) and global options (by chart.defaults.global) and chart options.
        The chain of priority is:
        • chart options
        • chart default options (by chart.defaults[type])
        • default scale options (by chart.defaults.scale)
        • global options (by chart.defaults.global)
        Parameters:
        envelop - the envelop for options as native options
      • setChartOptions

        public final void setChartOptions​(ChartEnvelop<NativeObject> envelop)
        Sets the chart options as underlying configuration options, after the first draw of the chart.
        Leveraging on proxy, this is mandatory and enables the possibility to use only the configuration options to update the chart options at runtime.
        Parameters:
        envelop - envelop for chart options as native options
      • beforeConfigurationUpdate

        protected void beforeConfigurationUpdate()
        Invoked before the chart options are going to be updated.
      • afterConfigurationUpdate

        protected void afterConfigurationUpdate()
        Invoked after the chart options has been updated.
      • beforeAxisConfigurationUpdate

        protected void beforeAxisConfigurationUpdate​(Axis axis)
        Invoked before the axis options are going to be updated.
        Parameters:
        axis - axis instance which is going to be updated
      • afterAxisConfigurationUpdate

        protected void afterAxisConfigurationUpdate​(Axis axis)
        Invoked after the axis options has been updated.
        Parameters:
        axis - axis instance which has been updated
      • getAnimationContainer

        public final AnimationContainer getAnimationContainer()
        Description copied from interface: HasAnimation
        Returns an animation container instance to use in the default methods of this interface.
        Specified by:
        getAnimationContainer in interface HasAnimation
        Returns:
        an animation container instance
      • getHover

        public Hover getHover()
        Returns the hover element.
        Returns:
        the hover
      • getInteraction

        public Interaction getInteraction()
        Returns the interaction element.
        Returns:
        the interaction
      • getLayout

        public Layout getLayout()
        Returns the layout element.
        Returns:
        the layout
      • getLegend

        public Legend getLegend()
        Returns the legend element.
        Returns:
        the legend
      • getTitle

        public Title getTitle()
        Returns the title element.
        Returns:
        the title
      • getSubtitle

        public Subtitle getSubtitle()
        Returns the subtitle element.
        Returns:
        the subtitle
      • getTooltips

        public Tooltips getTooltips()
        Returns the tooltips element.
        Returns:
        the tooltips
      • getElements

        public Elements getElements()
        Returns the elements element.
        Returns:
        the elements
      • getDatasets

        public Datasets getDatasets()
        Returns the data sets element.
        Returns:
        the data sets
      • getPlugins

        public Plugins getPlugins()
        Returns the plugins element.
        Returns:
        the plugins
      • getFiller

        public Filler getFiller()
        Returns the filler plugin configuration.
        Returns:
        the filler plugin configuration
      • getFont

        public Font getFont()
        Returns the font element.
        Returns:
        the font element
      • getAxisById

        protected Axis getAxisById​(int id)
        Returns the axis by the unique CHARBA id of scale or null if not axis.
        Parameters:
        id - the unique CHARBA id of scale
        Returns:
        the axis or null if not axis.
      • setEvents

        public void setEvents​(IsEvent... events)
        Sets the browser events that the chart should listen to.
        Parameters:
        events - the browser events that the chart should listen to.
      • setEvents

        public void setEvents​(Set<IsEvent> events)
        Sets the browser events that the chart should listen to.
        Parameters:
        events - the browser events that the chart should listen to.
      • getEvents

        public Set<IsEvent> getEvents()
        Returns the browser events that the chart should listen to.
        Returns:
        the browser events that the chart should listen to.
      • setLocale

        public void setLocale​(CLocale locale)
        Sets the locale instance for internationalization.
        Parameters:
        locale - the locale instance
      • getLocale

        public CLocale getLocale()
        Returns the locale instance for internationalization.
        Returns:
        the locale instance
      • setResponsive

        public void setResponsive​(boolean responsive)
        Sets the resizing of the chart canvas when its container does.
        Parameters:
        responsive - the resizing of the chart canvas when its container does.
      • isResponsive

        public boolean isResponsive()
        Returns the resizing of the chart canvas when its container does.
        Returns:
        the resizing of the chart canvas when its container does.
      • setMaintainAspectRatio

        public void setMaintainAspectRatio​(boolean maintainAspectRatio)
        Sets the maintaining of the original canvas aspect ratio (width / height) when resizing.
        Parameters:
        maintainAspectRatio - the maintaining of the original canvas aspect ratio (width / height) when resizing.
      • isMaintainAspectRatio

        public boolean isMaintainAspectRatio()
        Returns the maintaining of the original canvas aspect ratio (width / height) when resizing.
        Returns:
        the maintaining of the original canvas aspect ratio (width / height) when resizing.
      • setAspectRatio

        public void setAspectRatio​(double ratio)
        Canvas aspect ratio (i.e. width / height, a value of 1 representing a square canvas).
        Note that this option is ignored if the height is explicitly defined either as attribute or via the style.
        Parameters:
        ratio - the aspect ratio.
      • getAspectRatio

        public double getAspectRatio()
        Canvas aspect ratio (i.e. width / height, a value of 1 representing a square canvas).
        Note that this option is ignored if the height is explicitly defined either as attribute or via the style.
        Returns:
        the aspect ratio.
      • setResizeDelay

        public void setResizeDelay​(int delay)
        Sets the delay the resize update by give amount of milliseconds.
        This can ease the resize process by debouncing update of the elements.
        Parameters:
        delay - the delay the resize update by give amount of milliseconds
      • getResizeDelay

        public double getResizeDelay()
        Returns the delay the resize update by give amount of milliseconds.
        This can ease the resize process by debouncing update of the elements.
        Returns:
        the delay the resize update by give amount of milliseconds
      • setDevicePixelRatio

        public void setDevicePixelRatio​(double ratio)
        The chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g. Retina displays). Setting devicePixelRatio to a value other than 1 will force the canvas size to be scaled by that amount.
        Parameters:
        ratio - the pixel ratio.
      • getDevicePixelRatio

        public double getDevicePixelRatio()
        The chart's canvas will use a 1:1 pixel ratio, unless the physical display has a higher pixel ratio (e.g. Retina displays). Setting devicePixelRatio to a value other than 1 will force the canvas size to be scaled by that amount. Returns the pixel ratio.
        Returns:
        the pixel ratio..
      • isDrawOnAttach

        public boolean isDrawOnAttach()
        Returns true if the chart is configured to be drawn on the attach of DIV element, otherwise false.
        Returns:
        the drawOnAttach true if the chart is configured to be drawn on the attach of DIV element, otherwise false.
      • setDrawOnAttach

        public void setDrawOnAttach​(boolean drawOnAttach)
        Sets true if the chart is configured to be draw on the attach of DIV element, otherwise false.
        Parameters:
        drawOnAttach - the drawOnAttach to set
      • isDestroyOnDetach

        public boolean isDestroyOnDetach()
        Returns true if the chart is configured to be destroyed on the detach from DIV element, otherwise false.
        Returns:
        the destroyOnDetach true if the chart is configured to be destroyed on the detach from DIV element, otherwise false.
      • setDestroyOnDetach

        public void setDestroyOnDetach​(boolean destroyOnDetach)
        Sets true if the chart is configured to be destroyed on the detach from DIV element, otherwise false.
        Parameters:
        destroyOnDetach - the destroyOnDetach to set
      • setColor

        public void setColor​(IsColor color)
        Sets the default color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        color - color to use in the chart.
      • setColor

        public void setColor​(String color)
        Sets the default color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        color - color to use in the chart.
      • getColorAsString

        public String getColorAsString()
        Returns the default color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        color to use in the chart.
      • getColor

        public IsColor getColor()
        Returns the default color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        color to use in the chart.
      • setBackgroundColor

        public void setBackgroundColor​(IsColor backgroundColor)
        Sets the default background color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        backgroundColor - background color to use in the chart.
      • setBackgroundColor

        public void setBackgroundColor​(String backgroundColor)
        Sets the default background color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        backgroundColor - background color to use in the chart.
      • getBackgroundColorAsString

        public String getBackgroundColorAsString()
        Returns the default background color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        background color to use in the chart.
      • getBackgroundColor

        public IsColor getBackgroundColor()
        Returns the default background color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        background color to use in the chart.
      • setBorderColor

        public void setBorderColor​(IsColor borderColor)
        Sets the default border color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        borderColor - border color to use in the chart.
      • setBorderColor

        public void setBorderColor​(String borderColor)
        Sets the default border color to use in the chart, on all objects, if not override by the specific configuration.
        Parameters:
        borderColor - border color to use in the chart.
      • getBorderColorAsString

        public String getBorderColorAsString()
        Returns the default border color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        border color to use in the chart.
      • setAutoColors

        public void setAutoColors​(boolean enabled)
        Sets true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets.
        Parameters:
        enabled - true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets
      • isAutoColors

        public boolean isAutoColors()
        Returns true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets.
        Returns:
        true when the auto colors plugin has been enabled and CHART.JS apply the default colors to datasets
      • setAutoColorsForceOverride

        public void setAutoColorsForceOverride​(boolean forceOverride)
        By default the colors plugin only works when you initialize the chart without any colors for the border or background specified.
        If you want to force the colors plugin to always color your datasets, for example when using dynamic datasets at runtime you will need to set the forceOverride option to true.
        Parameters:
        forceOverride - true if auto color plugin forces setting palette.
      • isAutoColorsForceOverride

        public boolean isAutoColorsForceOverride()
        By default the colors plugin only works when you initialize the chart without any colors for the border or background specified.
        If you want to force the colors plugin to always color your datasets, for example when using dynamic datasets at runtime you will need to set the forceOverride option to true.
        Returns:
        true if auto color plugin forces setting palette.
      • getBorderColor

        public IsColor getBorderColor()
        Returns the default border color to use in the chart, on all objects, if not override by the specific configuration.
        Returns:
        border color to use in the chart.
      • hasDatasetSelectionHandlers

        public final boolean hasDatasetSelectionHandlers()
        Returns true if there is any data set selection handler, otherwise false.
        Returns:
        true if there is any data set selection handler, otherwise false.
      • hasTitleClickHandlers

        public final boolean hasTitleClickHandlers()
        Returns true if there is any title click handler, otherwise false.
        Returns:
        true if there is any title click handler, otherwise false.
      • hasTitleEnterHandlers

        public final boolean hasTitleEnterHandlers()
        Returns true if there is any title enter handler, otherwise false.
        Returns:
        true if there is any title enter handler, otherwise false.
      • hasTitleLeaveHandlers

        public final boolean hasTitleLeaveHandlers()
        Returns true if there is any title leave handler, otherwise false.
        Returns:
        true if there is any title leave handler, otherwise false.
      • hasSubtitleClickHandlers

        public final boolean hasSubtitleClickHandlers()
        Returns true if there is any subtitle click handler, otherwise false.
        Returns:
        true if there is any subtitle click handler, otherwise false.
      • hasSubtitleEnterHandlers

        public final boolean hasSubtitleEnterHandlers()
        Returns true if there is any subtitle enter handler, otherwise false.
        Returns:
        true if there is any subtitle enter handler, otherwise false.
      • hasSubtitleLeaveHandlers

        public final boolean hasSubtitleLeaveHandlers()
        Returns true if there is any subtitle leave handler, otherwise false.
        Returns:
        true if there is any subtitle leave handler, otherwise false.
      • hasAxisClickHandlers

        public final boolean hasAxisClickHandlers()
        Returns true if there is any axis click handler, otherwise false.
        Returns:
        true if there is any axis click handler, otherwise false.
      • hasAxisHoverHandlers

        public final boolean hasAxisHoverHandlers()
        Returns true if there is any axis hover handler, otherwise false.
        Returns:
        true if there is any axis hover handler, otherwise false.
      • hasAxisEnterHandlers

        public final boolean hasAxisEnterHandlers()
        Returns true if there is any axis enter handler, otherwise false.
        Returns:
        true if there is any axis enter handler, otherwise false.
      • hasAxisLeaveHandlers

        public final boolean hasAxisLeaveHandlers()
        Returns true if there is any axis leave handler, otherwise false.
        Returns:
        true if there is any axis leave handler, otherwise false.
      • load

        public final void load​(IsChart chart,
                               Configuration configuration)
        Description copied from interface: ConfigurationElement
        Called to enable to load in the a configuration object the specific configuration item (by native object).
        Specified by:
        load in interface ConfigurationElement
        Parameters:
        chart - chart instance
        configuration - chart configuration instance
      • setConfiguration

        protected final void setConfiguration​(T configuration)
        Parameters:
        configuration - the configuration to set
      • getConfiguration

        protected final T getConfiguration()
        Returns the configuration element.
        Returns:
        the configuration element.
      • merge

        public final void merge​(NativeObjectContainer source,
                                String property)
        Merge a native object in the this one with a specific property name.
        This is used by plugins implementation (native java script ones) when they are not using the standard way to add plugin configuration in the options of chart.
        Parameters:
        source - native object container to add
        property - property name
      • toJSON

        public final String toJSON()
        Returns the JSON representation of the object.
        Returns:
        the JSON representation of the object.
      • loadNativeObject

        public final ChartEnvelop<NativeObject> loadNativeObject​(ChartEnvelop<NativeObject> envelop)
        Returns the native object instance inside an envelop.
        It can be called only from org.pepstock.charba.client package.
        Parameters:
        envelop - envelop instance which will contain the native object
        Returns:
        the envelop, passed as argument, loaded with the native object
      • getChart

        public final IsChart getChart()
        Returns the chart instance
        Returns:
        the chart