Class ChartTable

Object
   |
   +--Table
         |
         +--VisualTable
               |
               +--ChartTable

class ChartTable

extends VisualTable

A data table that can be fed with real-time data delivered by Lightstreamer Server and displayed through a multiline graphic chart, where some or all of the table fields can be associated to distinct lines of the chart. The class contains the subscription details and the event handlers that allow Lightstreamer to display the real-time data.
In short, each real-time update (i.e. each new row that enters the logical data table) is associated to an X-coordinate and each field value in the row can specify the Y-coordinate of a point to be added to the corresponding line. To accomplish this, the fields can be associated to chart lines through addLine(), where the line configuration is also specified. In addition, one field has to be associated to the X axis and its values should be generated by a growing source. Note that, in order to create a chart, the presence of such a growing field is mandatory; however it may not be a subscribed field: an extra field, to be synthesized, for instance, from the local time, can be defined and used as well.
Note that only numeric fields can be associated to chart elements. If any conversion is needed in order to read a field value as a number, then an extra field can be used. Custom management of the chart overflow conditions can be performed through the provided event handlers.
The multiline chart for the visualization of pushed values is dynamically maintained by Lightstreamer inside a container HTML element. The container element can be provided as a DIV or SPAN element owning the "source='Lightstreamer'" special attribute, together with a "table" attribute that defines the screen table id. The association to the data table is made when the data table is brought to the "running" state, through the identifier supplied to PushPage.addTable(), that must match the screen table id. This element is a sort of "macrocell", on which all considerations done for HTML cells for the generic VisualTable class also apply. However, VisualTable.setPushedHtmlEnabled() is not meaningful in this case.
Defined in lspushpage.js

Constructor Detail

ChartTable

ChartTable(<GroupDescriptor> tGroup, <SchemaDescriptor> tSchema, <String> tSubscriptionMode)

Creates an object to be used to describe a data table whose values should be displayed and cumulated into a multiline chart. The object can be supplied to PushPage.addTable() and PushPage.removeTable(), in order to bring the data table to "running" or back to "inactive" state.

Parameters:
tGroup - A group descriptor object, which identifies the items that provide the logical data table rows. Usually, the group consists of just one item and the chart lines show the history of all updates for some fields of this item. If the group consists of more than one item, then the same field on different items can be used to generate different lines. However, the same field on both items is used to supply the X-coordinates; this means that the values for this field should be generated by the same growing source for both items.
An Array of item names or a String group identifier can also be used directly, instead of a group descriptor object.
Note that, in case a GroupListDescriptor or an array is used, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSchema - A schema descriptor object, which identifies the fields that represent the chart lines. An Array of field names or a String schema identifier can also be used directly, instead of a schema descriptor object.
Note that, in case a SchemaListDescriptor or an array is used, a LiteralBasedProvider or equivalent Metadata Adapter is needed on the Server in order to understand the subscription request.
tSubscriptionMode - the subscription mode for the items, required by Lightstreamer Server. This kind of data table is suited for MERGE, DISTINCT and RAW modes.

addLine

void addLine(<ChartLine> chartLine,<String> id)

Operation method that adds a line to a chart.

Lifecycle: Lines can be added to the chart at any time. However, if a line is added while the data table is in "running" state, the values that were received from the Server before the call are not shown.
Note that whenever the chart is cleared as a consequence of the VisualTable.setClearOnAdd() or VisualTable.setClearOnRemove() settings, all the lines are also removed and may need to be recreated and added again after the new call to PushPage.addTable().
Moreover, whenever the chart is cleared as a consequence of the VisualTable.setClearOnDisconnected() setting, all the lines are also removed and may need to be recreated and added again upon the reconnection; this could be performed by implementing the LightstreamerEngine.onStatusChange() and Table.onStart() event handlers.

Parameters:
chartLine - A ChartLine instance, that specifies the configuration properties of the line.
id - A unique identifier for the line.

onXOverflow

void onXOverflow(<Number> lastX, <Number> minX, <Number> maxX)

Event handler that is called when a new update has been received such that one or more points have to be added to the chart lines, but cannot be shown because their X-coordinate value is higher than the upper limit set for the X axis. By implementing this event handler, the chart axis can be repositioned through positionXAxis() so that the new points can be shown on the chart.
Note that if a new update is received such that one or more points have to be added to the chart lines but cannot be shown because their X-coordinate value is lower than the lower limit set for the X axis, then this event handler is not called, but rather the new update is ignored. X axis limits should always be set in such a way as to avoid this case.

Default implementation: The X axis limits are shifted in such a way that the mid point on the visible part of the X axis becomes the new lower limit.

Parameters:
lastX - The X-coordinate value of the new points to be shown on the chart and that exceeds the current upper limit.
minX - The current lower limit for the visible part of the X axis.
maxX - The current upper limit for the visible part of the X axis.

positionXAxis

void positionXAxis(<Number> min, <Number> 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 data table is currently in "running" state, 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 should be set before bringing the data table to "running" state through PushPage.addTable() for the first time. Then, they can be changed at any time.

Parameters:
min - lower limit for the visible part of the X axis.
max - higher limit for the visible part of the X axis.

removeLine

void removeLine(<String> id)

Operation method that removes a line from a chart.

Lifecycle: Lines can be removed from the chart at any time.

Parameters:
id - The unique identifier for the line, as was supplied to addLine() when the line was added.

setAreaClass

void setAreaClass(<String> areaClass)

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

Invocation: optional.

Default value: if not set, the stylesheet is inherited from the DOM element containing the chart.

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

Parameters:
areaClass - the name of an existing stylesheet.

setAreaHeight

void setAreaHeight(<String> height)

Setter method that sets the height 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.

Invocation: optional.

Default value: if not set, the whole height of the container HTML element is used.

Lifecycle: The chart area height can be set and changed at any time.

Parameters:
height - the height in pixels of the chart area.

setAreaLeft

void setAreaLeft(<String> left)

Setter method that sets the distance 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 first X axis label.

Invocation: optional.

Default value: if not set, 0 is used.

Lifecycle: The left margin width can be set and changed at any time.

Parameters:
left - the width of the left margin of the chart area, in pixels.

setAreaTop

void setAreaTop(<String> top)

Setter method that sets the distance 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.

Invocation: optional.

Default value: if not set, 0 is used.

Lifecycle: The top margin height can be set and changed at any time.

Parameters:
top - the height of the top margin of the chart area, in pixels.

setAreaWidth

void setAreaWidth(<String> width)

Setter method that sets the width 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.

Invocation: optional.

Default value: if not set, the whole width of the container HTML element is used.

Lifecycle: The chart area width can be set and changed at any time.

Parameters:
width - the width in pixels of the chart area.

setXAxis

void setXAxis(<FieldDescriptor> field, <boolean> commaAsDecimalSeparator)

Setter method that sets the field to be used as the source of the X-coordinate for each update.

Invocation: mandatory.

Default value: No default.

Lifecycle: The X axis field should be set before bringing the data table to "running" state through PushPage.addTable().

Parameters:
field - a field descriptor object for the X field. A String field name or a Number representing a field position can also be used directly, instead of a field descriptor object.
commaAsDecimalSeparator - [Optional] true to specify that field values are decimal numbers in which the decimal separator is a comma; false to specify it is a dot. The parameter is optional, with false as its default value.

setXLabels

void setXLabels(<Number> labelsNum, <String> labelsClass, <LabelFormatter> labelsFormatter)

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 object.
Note that the room for the X axis labels on the page is not provided by Lightstreamer; it should be provided by specifying a chart height smaller than the container element height, through the setAreaHeight() 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 setAreaLeft() and setAreaWidth() settings.

Invocation: optional.

Default value: if not set, no labels are displayed relative to the X axis.

Lifecycle: The legend should be set before bringing the data table to "running" state through PushPage.addTable() for the first time.

Parameters:
labelsNum - the number of labels to be spread on the X axis; it should be 1 or greater.
labelsClass - [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 is applied.
labelsFormatter - [Optional] a LabelFormatter instance, that provides a method to format the X axis values designated for the labels. The parameter is optional; if missing or null, then a default LabelFormatter object is used.