Class: Chart

Chart

A widget displaying the data from its model as a multiline chart. As with all the classes extending AbstractWidget the internal model can be automatically updated by listening to one or more Subscription instances.
In short, once both X and Y axis have been associated to a field through Chart#setXAxis and Chart#addYAxis, each row in the model will be represented as a line in the chart, connecting all the X,Y points corresponding to the subsequent values assumed by the related fields and dynamically extending with new values. Actually, it is possible to associate more fields to the Y axis so that it is possible to have more than one line per row.
According to the axis settings, every time a row enters the model, one or more lines will be added to the chart and corresponding instances of ChartLine will be generated and passed to the ChartListener#onNewLine event to be better configured.
The behavior of the underlying model is described in AbstractWidget, but there is one exception: if this instance is used to listen to events from Subscription instance(s), and the first Subscription it listens to is a DISTINCT Subscription, then the base behavior is overridden and the same behavior defined for MERGE and RAW modes is adopted.

Note that, in order to create a chart, the X axis should be associated with a field whose values are increasing. Anyway for both X and Y axis the used value must be a numeric value. If the original field values are not compliant with such restriction, they can be customized before being used by means of a parser Function.
Also, even if the Chart instance is listening to Subscription events, it is not mandatory to use server-sent fields to plot the chart.
The multiline chart for the visualization of model values is dynamically maintained by an instance of this class inside a container HTML element. The container element must be prepared on the page in the form of any HTML element owning the "data-source='Lightstreamer'" special attribute, together with an HTML "id" attribute that has to be specified in the constructor of this class.

new Chart(id)

Creates an object that extends AbstractWidget displaying its values as a multiline chart.
Note that the AbstractWidget#parseHtml method is automatically called by this constructor, hence the container element should have already been prepared on the page DOM. However, preparing the element later and then invoking AbstractWidget#parseHtml manually is also supported.
Parameters:
Name Type Description
id String The HTML "id" attribute of a DOM Element to which the chart will be attached.

Extends

Method Summary

addListener
Adds a listener that will receive events from the Chart instance.
addYAxis
Adds field(s) to be used as the source of the Y-coordinate for each update An optional parser can be passed to normalize the value before it is used to plot the chart.
configureArea
Setter method that sets the stylesheet and positioning to be applied to the chart area.
getListeners
Returns an array containing the ChartListener instances that were added to this client.
parseHtml
This method is automatically called by the constructor of this class.
positionXAxis
Operation method that sets or changes the limits for the visible part of the X axis of the chart (that is, the minimum and maximum X-coordinates shown in the chart).
removeListener
Removes a listener from the Chart instance so that it will not receive events anymore.
removeYAxis
Removes field(s) currently used as the source of the Y-coordinate for each update and all the related ChartLine.
setXAxis
Setter method that sets the field to be used as the source of the X-coordinate for each update.
setXLabels
Setter method that configures the legend for the X axis.

Inherited Methods

| getValue | onClearSnapshot | onCommandSecondLevelItemLostUpdates | onCommandSecondLevelSubscriptionError | onEndOfSnapshot | onItemLostUpdates | onItemUpdate | onListenEnd | onSubscription | onSubscriptionError | onUnsubscription | removeRow | setAutoCleanBehavior | updateRow |

Method Detail

addListener(listener)

Adds a listener that will receive events from the Chart instance.
The same listener can be added to several different Chart instances.

Lifecycle: a listener can be added at any time.

Parameters:
Name Type Description
listener ChartListener An object that will receive the events as shown in the ChartListener interface.
Note that the given instance does not have to implement all of the methods of the ChartListener interface. In fact it may also implement none of the interface methods and still be considered a valid listener. In the latter case it will obviously receive no events.

addYAxis(field, yParseropt)

Adds field(s) to be used as the source of the Y-coordinate for each update An optional parser can be passed to normalize the value before it is used to plot the chart. The resulting values should be in the limits posed by the ChartLine#positionYAxis related to the involved line, otherwise a ChartListener#onYOverflow event is fired to handle the situation. null can also be specified, in which case, if the associated X value is null the chart line will be cleared, otherwise the update will be ignored.
It is possible to specify an array of fields instead of specifying a single field. If that's the case multiple chart lines will be generated per each row in the model.
Note that for each field in the underlying model it is possible to associate only one line. If multiple lines based on the same fields are needed, dedicated fields should be added to the model, through AbstractWidget#updateRow. In case this instance is used to listen to events from Subscription instance(s), updateRow() can be invoked from within SubscriptionListener#onItemUpdate.

Lifecycle: The method can be invoked at any time, in order to add fields to be plotted or in order to change the parser associated to fields already being plotted. Until invoked for the first time, no chart will be printed.

Parameters:
Name Type Argument Description
field String A field name representing the Y axis. An array of field names can also be passed. Each field will generate its own line.
yParser CustomParserFunction | Array.<CustomParserFunction> <optional>
 A parser function that can be used to normalize the value of the Y field before using it to plot the chart. If the function is not supplied, then the field values should represent valid numbers in JavaScript or be null.
If an array has been specified for the field parameter, then an array of parser functions can also be passed. Each parser will be executed on the field having the same index in the array. On the other hand, if an array of fields is passed but only one parser has been specified, then the parser will be applied to all of the fields.
See:

configureArea(chartCssopt, chartHeightopt, chartWidthopt, chartTopopt, chartLeftopt)

Setter method that sets the stylesheet and positioning to be applied to the chart area.

Lifecycle: The chart area stylesheet and position attributes can be set and changed at any time.

Parameters:
Name Type Argument Default Description
chartCss String <optional>
 the name of an existing stylesheet to be applied to the chart. If not set, the stylesheet is inherited from the DOM element containing the chart.
chartHeight Number <optional>
 the height in pixels of the chart area. Such height may be set as smaller than the height of the container HTML element in order to make room for the X axis labels. If not set, the whole height of the container HTML element is used.
chartWidth Number <optional>
 the width in pixels of the chart area. Such width may be set as smaller than the width of the container HTML element in order to make room for the Y axis labels. If not set, the whole width of the container HTML element is used.
chartTop Number <optional>
 0 the distance in pixels between the top margin of the chart area and the top margin of the container HTML element. Such distance may be set as a nonzero value in order to make room for the first Y axis label. If not set, 0 is used.
chartLeft Number <optional>
 0 the distance in pixels between the left margin of the chart area and the left margin of the container HTML element. Such distance may be set as a nonzero value in order to make room for the Y axis labels. If not set, 0 is used.
Throws:
if one of the numeric values is not valid.
Type
IllegalArgumentException

getListeners() → {Array}

Returns an array containing the ChartListener instances that were added to this client.
Returns:
an array containing the listeners that were added to this instance. Listeners added multiple times are included multiple times in the array.
Type
Array

parseHtml()

This method is automatically called by the constructor of this class. It will bind the current instance with the HTML element having the id specified in the constructor.
Overrides:

positionXAxis(min, max)

Operation method that sets or changes the limits for the visible part of the X axis of the chart (that is, the minimum and maximum X-coordinates shown in the chart). If these limits are changed while the internal model is not empty then this causes a repaint of the whole chart.
Note that rising the minimum X value shown also clears from the memory all the points whose X value becomes lower. So, those points will not be displayed again after lowering again the minimum X value.

Lifecycle: The X axis limits can be set at any time.

Parameters:
Name Type Description
min Number lower limit for the visible part of the X axis.
max Number higher limit for the visible part of the X axis.
Throws:
if the min parameter is greater than the max one.
Type
IllegalArgumentException

removeListener(listener)

Removes a listener from the Chart instance so that it will not receive events anymore.

Lifecycle: a listener can be removed at any time.

Parameters:
Name Type Description
listener ChartListener The listener to be removed.

removeYAxis(field)

Removes field(s) currently used as the source of the Y-coordinate for each update and all the related ChartLine.
It is possible to specify an array of fields instead of specifying a single field. If that's the case all the specified fields and related chart lines will be removed.

Lifecycle: The method can be invoked at any time, in order to remove plotted fields.

Parameters:
Name Type Description
field String A field name representing the Y axis. An array of field names can also be passed.
See:

setXAxis(field, xParseropt)

Setter method that sets the field to be used as the source of the X-coordinate for each update. An optional parser can be passed to normalize the value before it is used to plot the chart. The resulting values should be in the limits posed by the Chart#positionXAxis method, otherwise a ChartListener#onXOverflow event is fired to handle the situation. null can also be specified, in which case, if the associated Y value is null the chart will be cleared, otherwise the update will be ignored.

Lifecycle: The X axis field can be set at any time. Until set, no chart will be printed. If already set, the new setting only affects the new points while all the previously plotted points are cleaned.

Parameters:
Name Type Argument Description
field String A field name representing the X axis.
xParser CustomParserFunction <optional>
 A parser function that can be used to normalize the value of the X field before using it to plot the chart. If the function is not supplied, then the field values should represent valid numbers in JavaScript or be null.

setXLabels(labelsNum, labelsClassopt, labelsFormatteropt)

Setter method that configures the legend for the X axis. The legend consists of a specified number of labels for the values in the X axis. The labels values are determined based on the axis limits; the labels appearance is controlled by supplying a stylesheet and a formatter function.
Note that the room for the X axis labels on the page is not provided by the library; it should be provided by specifying a chart height smaller than the container element height, through the Chart#configureArea setting. Moreover, as the first and last labels are centered on the chart area borders, a suitable space should be provided also on the left and right of the chart area, through the same method.

Lifecycle: Labels can be configured at any time. If not set, no labels are displayed relative to the X axis.

Parameters:
Name Type Argument Description
labelsNum Number the number of labels to be spread on the X axis; it should be 1 or greater.
labelsClass String <optional>
 the name of an existing stylesheet, to be applied to the X axis label HTML elements. The parameter is optional; if missing or null, then no specific stylesheet will be applied.
labelsFormatter LabelsFormatter <optional>
 a Function instance used to format the X axis values designated for the labels. If the function is not supplied, then the value will be used with no further formatting.
Throws:
if labelsNum is not a valid poisitive integer number.
Type
IllegalArgumentException