Package com.storedobject.chart

Class SOChart

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.littemplate.LitTemplate

com.storedobject.helper.LitComponent

com.storedobject.helper.LitComponentWithSize

com.storedobject.chart.SOChart

All Implemented Interfaces:

com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.internal.Template, Serializable

@NpmPackage(value="echarts",
            version="5.6.0")
@Tag("so-chart")
@JsModule("./so/chart/chart.js")
public class SOChart
extends LitComponentWithSize

Chart is a Vaadin Component so that you can add it to any layout component for displaying it. It is a LitComponent wrapper around the "echarts" library.

Chart is composed of one more chart Components and each chart Component may have zero or more ComponentParts. Examples of chart Components are (a) Chart, (b) RectangularCoordinate, (c) PolarCoordinate etc. An example of a ComponentPart is AngleAxis that is used by the PolarCoordinate.

Typical usage of the SOChart is to new it and add it to some layout for displaying it. Any Component that is added to the Chart will be displayed. For example, you can create a PieChart and add it to the SOChart using add(Component...).

     SOChart soChart = new SOChart();
     soChart.setSize("600px", "400px");
     CategoryData labels = new CategoryData("Banana", "Apple", "Orange", "Grapes");
     Data data = new Data(25, 40, 20, 30);
     soChart.add(new PieChart(labels, data));
     myLayout.add(soChart);
 

Author:

Syam

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
SOChart()	Constructor.

Method Summary

Modifier and Type	Method	Description
void	add(Component... components)	Add components to the chart.
void	add(ComponentGroup... componentGroups)	Add component groups.
protected void	addCustomEncoding(ComponentPart componentPart, StringBuilder buffer)	This method is invoked after rendering each ComponentPart.
protected void	addCustomEncoding(Class<? extends ComponentPart> componentPartClass, StringBuilder buffer)	This method is invoked after rendering each ComponentPart type so that you can add more such components.
void	addData(AbstractDataProvider<?> data)	Add data to the chart.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener)	Adds a listener to the specified event type.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, Chart chart)	Adds a listener for a specific event type to the given chart.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, Chart chart, int dataIndex)	Adds a listener for the specified event type to the given chart.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, Chart chart, int dataIndex, String dataType)	Adds an event listener to a specified event type on the given chart, with additional options for specifying data index and data type.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, Chart chart, String dataType)	Adds an event listener to the specified chart for the given event type.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, Object userData)	Adds a listener for a specified event type.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, String parameters)	Registers an event listener for a specified event type with optional parameters.
com.vaadin.flow.shared.Registration	addListener(EventType eventType, EventListener listener, String parameters, Object userData)	Adds a listener for a specific event type, allowing custom parameters and optional user data to be passed.
void	clear()	Clear the chart.
protected String	customizeDataJSON(String json, AbstractDataProvider<?> data)	This method is invoked just before the JSON string that is being constructed to send data to the client.
protected String	customizeJSON(String json)	This method is invoked just before the JSON string that is being constructed in the update() method is sent to the client.
void	debug(boolean debugData, boolean debugOptions, boolean debugEvents)	Enables or disables debugging functionality at the client-side.
void	disableDefaultLegend()	Legends will be shown by default.
void	disableDefaultTooltip()	A tooltip will be shown by default.
void	dispatchAction(String parameters)	Dispatch an action to the chart.
void	enableDefaultLegend()	Enables the default legend for the chart.
void	enableDefaultTooltip()	Enables the default tooltip for the associated component.
static Color	getDefaultColor(int index)	Get the default color used by the chart component.
List<AbstractColor>	getDefaultColors()	Get the list of default colors.
Legend	getDefaultLegend()	Get the default legend.
TextStyle	getDefaultTextStyle()	Get the default text style.
Tooltip	getDefaultTooltip()	Get the default tooltip.
protected void	onAttach(com.vaadin.flow.component.AttachEvent attachEvent)
void	onError(String message)	This method is invoked when SOChart wants to show some errors.
void	remove(Component... components)	Remove components from the chart.
void	remove(ComponentGroup... componentGroups)	Remove component groups.
void	removeAll()	Remove all components, associated data and event handlers from the chart.
void	removeData(AbstractDataProvider<?> data)	Remove extra data added via addData(AbstractDataProvider).
void	setDarkTheme()	Set the dark theme.
void	setDefaultBackground(Color background)	Set the default background color.
void	setLanguage(Language language)	Set language.
void	setSVGRendering()	Switch on SVG rendering instead of canvas rendering.
void	setVisible(boolean visible, Chart chart)	Sets the visibility of a chart by sending the appropriate action.
void	toggleVisible(Chart chart)	Toggles the visibility of a chart by sending the appropriate action..
void	update()	Update the chart display with the current set of components.
void	update(boolean skipData)	This method is same as update() but based on the parameter passed, no data may be passed to the client-side.
void	updateData(AbstractDataProvider<?>... data)	Update the chart with modified data from the data provider.
void	updateData(HasData... dataOwners)	Update the chart with modified data from the data providers of a given set of data owners.

Methods inherited from class com.storedobject.helper.LitComponentWithSize

setHeight, setMaxHeight, setMaxWidth, setMinHeight, setMinWidth, setSize, setWidth

Methods inherited from class com.storedobject.helper.LitComponent

executeJS, onDetach

Methods inherited from class com.vaadin.flow.component.littemplate.LitTemplate

getChildren

Methods inherited from class com.vaadin.flow.component.Component

addListener, findAncestor, fireEvent, from, get, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasSize

getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeightFull, setMaxHeight, setMaxWidth, setMinHeight, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidthFull

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Constructor Details

SOChart

public SOChart()

Constructor.

Method Details

onAttach

protected void onAttach(com.vaadin.flow.component.AttachEvent attachEvent)

Overrides:

onAttach in class com.vaadin.flow.component.Component

debug

public void debug(boolean debugData,
 boolean debugOptions,
 boolean debugEvents)

Enables or disables debugging functionality at the client-side. Debug messages will be printed to the JavaScript console if enabled.

Parameters:

debugData - if true, enables debugging for data sets used.

debugOptions - if true, enables debugging for options and configurations of the chart.

debugEvents - if true, enables debugging for events and their handling.

onError

@ClientCallable
public void onError(String message)

This method is invoked when SOChart wants to show some errors. The default implementation shows a notification for 1 minute. However, you can override this method to customize the error handling.

Parameters:

message - The error message to be shown.

dispatchAction

public void dispatchAction(String parameters)

Dispatch an action to the chart.

Parameters:

parameters - Parameters to be passed to the action. It must be a valid JSON string supported by echarts's dispatchAction method.

setVisible

public void setVisible(boolean visible,
 Chart chart)

Sets the visibility of a chart by sending the appropriate action. This has the same effect of clicking on the legend to hide/show the chart. However, this method is useful when you want to set the visibility of a chart programmatically.

Parameters:

visible - a boolean indicating whether the chart should be visible (true) or hidden (false)

chart - the chart whose visibility is to be set

toggleVisible

public void toggleVisible(Chart chart)

Toggles the visibility of a chart by sending the appropriate action..

Parameters:

chart - the chart whose visibility is to be toggles

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 Chart chart)

Adds a listener for a specific event type to the given chart. This method allows monitoring of events by attaching a listener to the specified chart.

Parameters:

eventType - the type of event to listen for

listener - the listener to handle the event

chart - the chart instance to which the event listener is being added

Returns:

a Registration object that can be used to unregister the listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 Chart chart,
 String dataType)

Adds an event listener to the specified chart for the given event type.

Parameters:

eventType - the type of event to listen for

listener - the event listener to be added

chart - the chart to which the listener is attached

dataType - additional data type information needed for the listener

Returns:

a Registration object that can be used to manage the listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 Chart chart,
 int dataIndex)

Adds a listener for the specified event type to the given chart. The listener can be tied to a specific data index for finer control.

Parameters:

eventType - the type of event to listen for

listener - the event listener to be invoked when the event occurs

chart - the chart to which the listener is being attached

dataIndex - the index of the data the listener should target, or -1 for no specific index

Returns:

a Registration object that can be used to unregister the listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 Chart chart,
 int dataIndex,
 String dataType)

Adds an event listener to a specified event type on the given chart, with additional options for specifying data index and data type.

Parameters:

eventType - the type of event to listen for

listener - the event listener to be added

chart - the chart instance for which the listener is being added

dataIndex - the index of the data point in the series; use -1 if not applicable

dataType - an optional string specifying the type of data; can be null or empty (when the chart has more than one type of associated data, this could be specified to identify the data such as "edge", "node" etc, in GraphChart.

Returns:

a Registration object representing the registration of the listener, which can be used to remove the listener later

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener)

Adds a listener to the specified event type. The listener will be triggered whenever the specified event occurs.

Parameters:

eventType - the type of the event for which the listener should be registered

listener - the listener to be executed when the event occurs

Returns:

a Registration instance that can be used to unregister the listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 Object userData)

Adds a listener for a specified event type. The listener will be notified when events of the given type occur.

Parameters:

eventType - the type of event to listen for

listener - the listener to handle the event

userData - optional user data to associate with the event listener, it can be accessed later by the listener via Event.getUserData()

Returns:

a Registration object that can be used to deregister the listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 String parameters)

Registers an event listener for a specified event type with optional parameters.

Parameters:

eventType - the type of the event the listener is to be registered for

listener - the listener that will handle the event

parameters - optional parameters associated with the event listener, if present, it should be a valid JSON string supported by echarts.

Returns:

a Registration object that can be used to remove the event listener

addListener

public com.vaadin.flow.shared.Registration addListener(EventType eventType,
 EventListener listener,
 String parameters,
 Object userData)

Adds a listener for a specific event type, allowing custom parameters and optional user data to be passed.

Parameters:

eventType - the type of event to listen for

listener - the listener that will handle the event

parameters - optional parameters associated with the event listener, if present, it should be a valid JSON string supported by echarts.

userData - optional user data to associate with the event listener, it can be accessed later by the listener via Event.getUserData()

Returns:

a Registration object that can be used to remove the listener

getDefaultColors

public List<AbstractColor> getDefaultColors()

Get the list of default colors. A list is returned, and you may add any number of colors to that list. Those colors will be used sequentially and circularly. However, please note that if the list contains less than 11 colors, more colors will be added to it automatically from the following to make count 11:
['#0000ff', '#c23531', '#2f4554', '#61a0a8', '#d48265', '#91c7ae', '#749f83', '#ca8622', '#bda29a', '#6e7074', '#546570', '#c4ccd3']

Returns:

List of default colors.

setDefaultBackground

public void setDefaultBackground(Color background)

Set the default background color.

Parameters:

background - Background color.

getDefaultTextStyle

public TextStyle getDefaultTextStyle()

Get the default text style. You may invoke this method and override default values if required. However, please note that setting padding, border (not text border) and alignment properties do not have any effect.

Returns:

Default text style.

disableDefaultTooltip

public void disableDefaultTooltip()

A tooltip will be shown by default. However, you can either disable it using this method or you can create your own customized tooltips and add it using add(Component...).

enableDefaultTooltip

public void enableDefaultTooltip()

Enables the default tooltip for the associated component. This method initializes the tooltip instance if it is currently null, ensuring that a tooltip is available for use.

getDefaultTooltip

public Tooltip getDefaultTooltip()

Get the default tooltip. You can customize it.

Returns:

THe default tooltip. Will return null if it was disabled via disableDefaultTooltip().

disableDefaultLegend

public void disableDefaultLegend()

Legends will be shown by default. However, you can either disable it using this method or you can create your own customized legends and add it using add(Component...).

enableDefaultLegend

public void enableDefaultLegend()

Enables the default legend for the chart. If the legend is not already initialized, this method creates a new instance of the legend.

getDefaultLegend

public Legend getDefaultLegend()

Get the default legend. You can customize it.

Returns:

THe default legend. Will return null if it was disabled via disableDefaultLegend().

setDarkTheme

public void setDarkTheme()

Set the dark theme.

setSVGRendering

public void setSVGRendering()

Switch on SVG rendering instead of canvas rendering.

setLanguage

public void setLanguage(Language language)

Set language.

Parameters:

language - Language.

addData

public void addData(AbstractDataProvider<?> data)

Add data to the chart. This method is normally not required to be used because the Charts that are added will automatically add its respective data too. This is used only when some extra data that is used in the Charts directly for some other display purposes.

Parameters:

data - Data to add.

removeData

public void removeData(AbstractDataProvider<?> data)

Remove extra data added via addData(AbstractDataProvider).

Parameters:

data - Data to remove.

add

public void add(ComponentGroup... componentGroups)

Add component groups.

Parameters:

componentGroups - Component groups to add.

remove

public void remove(ComponentGroup... componentGroups)

Remove component groups.

Parameters:

componentGroups - Component groups to remove.

add

public void add(Component... components)

Add components to the chart. (Chart will not be updated unless update() method is called).

Parameters:

components - Components to add.

remove

public void remove(Component... components)

Remove components from the chart. (Chart will not be updated unless update() method is called).

Parameters:

components - Components to remove.

removeAll

public void removeAll()

Remove all components, associated data and event handlers from the chart. (Chart display will not be cleared unless update() or clear() method is called).

clear

public void clear()

Clear the chart. This will remove the chart display. However, it can be rendered again by invoking update() as long as removeAll() is not called.

update

public void update()
            throws ChartException,
Exception

Update the chart display with the current set of components. ComponentPart.validate() method of each component will be invoked before updating the chart display. The chart display may be already there, and only the changes and additions will be updated. If a completely new display is required, clear() should be invoked before this. (Please note that an "update" will automatically happen when a SOChart is added to its parent layout for the first time).

Note: If this is not the first update, data changes will not be transmitted to the client. So, if you really want to update the whole data too, you should use the update(boolean) method with the parameter set to false. However, it is better to transmit data separately via one of the data update methods (updateData(AbstractDataProvider...) and updateData(HasData...)) or use the DataChannel for updating data once the first rendering was already done.

Throws:

ChartException - When any of the component is not valid.

Exception - If the JSON customizer raises any exception.

update

public void update(boolean skipData)
            throws ChartException,
Exception

This method is same as update() but based on the parameter passed, no data may be passed to the client-side. So, it is useful only if it is a partial update. Old set of data passed will be used for the display changes if parameter is true.

Why is this method required? If the data set is huge, it will be accountable for the majority of the communication overhead, and it will be useful if we can update the display with other changes if no data is changed.

Even after eliminating the overhead of data, we can eliminate other components that are not changed via the method remove(Component...).

Parameters:

skipData - Skip data or not. This parameter will be ignored if this is the first-time update. However, any data never sent to the client will be sent anyway.

Throws:

ChartException - When any of the component is not valid.

Exception - If the JSON customizer raises any exception.

addCustomEncoding

protected void addCustomEncoding(Class<? extends ComponentPart> componentPartClass,
 StringBuilder buffer)

This method is invoked after rendering each ComponentPart type so that you can add more such components.

Note: Please note that if you are adding any custom code, it should merge properly to the already generated part in the buffer. You may use customizeJSON(String) to check the outcome.

Warning: If you add custom code via this mechanism, it may not be compatible with the future releases because the functionality you add via this mechanism may be supported directly in the future releases.

Parameters:

componentPartClass - The component part class that is currently added. You may add more of these.

buffer - The buffer that contains the code that is already generated.

addCustomEncoding

protected void addCustomEncoding(ComponentPart componentPart,
 StringBuilder buffer)

This method is invoked after rendering each ComponentPart. You can add custom code into the buffer that already contains the encoding for the part. Also, you can add at the root-level (not related to any particular ComponentPart). For this, this method is invoked with the component part parameter set to null.

Note: Please note that if you are adding any custom code, it should merge properly to the already generated part in the buffer. You may use customizeJSON(String) to check the outcome.

Warning: If you add custom code via this mechanism, it may not be compatible with the future releases because the functionality you add via this mechanism may be supported directly in the future releases.

Parameters:

componentPart - The component part to which custom code can be added. If this is null, then code added will go to the root-level.

buffer - The buffer that contains the code that is already generated.

customizeJSON

protected String customizeJSON(String json)
                        throws Exception

This method is invoked just before the JSON string that is being constructed in the update() method is sent to the client. The returned value by this method will be sent to the "echarts" instance at the client-side. The default implementation just returns the same string. However, if someone wants to do some cutting-edge customization, this method can be used. This JSON string is used to construct the "option" parameter for the "echarts.setOption(option)" JavaScript method.

Parameters:

json - JSON string constructed by the update() method.

Returns:

Customized JSON string.

Throws:

Exception - If any custom error to be notified so that rendering will not happen.

customizeDataJSON

protected String customizeDataJSON(String json,
 AbstractDataProvider<?> data)
                            throws Exception

This method is invoked just before the JSON string that is being constructed to send data to the client. The returned value by this method will be sent to the "echarts" instance at the client-side. The default implementation just returns the same string. However, if someone wants to do some cutting-edge customization, this method can be used.

Parameters:

json - JSON string constructed by the update() method.

data - The data part for which this JSON string was created.

Returns:

Customized JSON string.

Throws:

Exception - If any custom error to be notified so that rendering will not happen.

updateData

public void updateData(AbstractDataProvider<?>... data)
                throws Exception

Update the chart with modified data from the data provider.

Parameters:

data - Data to be updated.

Throws:

Exception - if custom error is raised by customizeDataJSON(String, AbstractDataProvider).

updateData

public void updateData(HasData... dataOwners)
                throws Exception

Update the chart with modified data from the data providers of a given set of data owners.

Parameters:

dataOwners - Data owners whose data to be updated.

Throws:

Exception - if custom error is raised by customizeDataJSON(String, AbstractDataProvider).

getDefaultColor

public static Color getDefaultColor(int index)

Get the default color used by the chart component.

Parameters:

index - Index of the color.

Returns:

Color.