abstract class %ZEN.SVGComponent.chart
extends svgComponent, %ZEN.Component.dataView
This is the abstract base class from which all SVG chart components are derived.
A chart provides a base on which to display a specific type
of chart (such as a barChart, lineChart, or pieChart).
This base class defines the data, grid (axes and scales), styles, and legend
used by charts.
All charts are plotted onto a virtual coordinate space that
measures 100 units by 100 units.
You can adjust the visual aspects of a chart by setting the various properties of this
class (plus any additional properties added by the specific chart subclass).
You can adjust the x and y axis settings (such as scaling and range) via the
xAxis and yAxis properties (which are objects of the type %ZEN.Auxiliary.axis).
• parameter DEFAULTAPPEARANCE = "2D";
Default appearance of this component.
• parameter DEFAULTASPECT = "none";
Do not worry about preserving the aspect ratio.
• parameter DEFAULTAUTOSCALETEXT = 1;
Default setting for autoscaling text as chart resizes
• parameter DEFAULTMARKERSVISIBLE = 0;
Default value for the markersVisible property.
• parameter DEFAULTPLOTTOEDGE = 1;
Parameter SYSMODULE = "chart";
Default value for the plotToEdge property.
• parameter DEFAULTVALUELABELSVISIBLE = 0;
Default value for the valueLabelsVisible property.
• parameter DEFAULTVIEWBOXHEIGHT = 100;
Default viewBoxHeight of this component.
This is set to 100 to provide a fixed coordinate system for meters.
• parameter DEFAULTVIEWBOXWIDTH = 100;
Default viewBoxWidth of this component.
This is set to 100 to provide a fixed coordinate system for meters.
• property appearance
as %ZEN.Datatype.string(VALUELIST=",2D,3D") [ InitialExpression = ..#DEFAULTAPPEARANCE ];
Controls the appearance of this chart.
Set this to "2D" (the default) for a standard chart appearance.
Setting this to "3D" will give the chart a 3-D appearance; the
plot area will appear to be recessed. Certain chart types, such as
bar charts, will display items with a 3-D look.
For pie charts, setting this to "3D" will display a pie chart with
a 3-D appearance, but will not affect the plot area.
• property autoScaleText
as %ZEN.Datatype.boolean [ InitialExpression = ..#DEFAULTAUTOSCALETEXT ];
Specifies how the text elements of a chart should be handled when a chart is
resized. If True, the text scales in proportion to the chart itself and all
requested labels are rendered regardless of legibility. If false, the size of
the text elements is fixed with respect to the page and some lables may be
omitted to avoid visual overlap if insufficient space is provided to render the
values should the chart be scaled down beyond certain thresholds
• property axisLineStyle
as %ZEN.Datatype.svgStyle;
Optional: style applied to line drawn for x and y axes.
• property axisTitleStyle
as %ZEN.Datatype.svgStyle;
Optional: default style applied to axis titles for this chart.
This is applied in addition to the style supplied by labelStyle.
• property backgroundStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for chart background panel.
• property bandLower
as %ZEN.Datatype.float;
If defined, then a colored band (specified by bandLowerStyle)
is displayed on the plot area covering the range lower than this value;
• property bandLowerStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for upper band on plot area.
• property bandUpper
as %ZEN.Datatype.float;
If defined, then a colored band (specified by bandUpperStyle)
is displayed on the plot area covering the range greater than this value;
• property bandUpperStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for upper band on plot area.
• property borderRadius
as %ZEN.Datatype.integer [ InitialExpression = 0 ];
Optional: radius applied to the chart's background rectangle and border.
• property borderStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for border line inset from outer edge of chart.
• property currYAxis
as %ZEN.Datatype.integer(MINVAL=0) [ InitialExpression = 0 ];
Specifies which yAxis definition is used to drive the chart yaxis (0 based).
• property gridStyle
as %ZEN.Datatype.svgStyle;
Optional: default style applied to all grid line elements for this chart.
If defined, this style overrides any styles define in the CSS style
definition for the page, but is in turn overridden by any styles defined
by a specific axis element.
• property hasZoom
as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
Optional: if true, display zoom in/out buttons (for certain chart types).
• property labelStyle
as %ZEN.Datatype.svgStyle;
Optional: default style applied to all grid label elements for this chart.
If defined, this style overrides any styles define in the CSS style
definition for the page, but is in turn overridden by any styles defined
by a specific axis element.
• property labelsVisible
as %ZEN.Datatype.boolean [ InitialExpression = 1 ];
If true, display axis labels for this chart (or slice labels in the
case of a pie chart).
• property legendHeight
as %ZEN.Datatype.length;
If this chart has a legend, height (within the chart coordinate space) of legend box.
If not specified a default height (based on number of data series) will be used.
• property legendLabelStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for text within the legend box.
• property legendStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for background of the legend box.
• property legendTitle
as %ZEN.Datatype.caption;
Title to display for legend box.
• property legendVisible
as %ZEN.Datatype.string(VALUELIST=",auto,false,true") [ InitialExpression = "auto" ];
If true, display a legend for this chart.
If "auto" then the legend is displayed if there is more than one data series
for the chart.
• property legendWidth
as %ZEN.Datatype.length;
If this chart has a legend, width (within the chart coordinate space) of legend box.
If not specified a default width will be used.
• property legendX
as %ZEN.Datatype.length;
If this chart has a legend, x-position (within the chart coordinate space) of legend box.
If not specified a default position will be used.
• property legendY
as %ZEN.Datatype.length;
If this chart has a legend, y-position (within the chart coordinate space) of legend box.
If not specified a default position will be used.
• property marginBottom
as %ZEN.Datatype.length;
Margin (within the chart coordinate space) from bottom edge of chart to bottom edge of grid (plot area).
If not specified, then this value will be automatically calculated.
• property marginLeft
as %ZEN.Datatype.length;
Margin (within the chart coordinate space) from left edge of chart to left edge of grid (plot area).
If not specified, then this width will be automatically calculated.
• property marginRight
as %ZEN.Datatype.length;
Margin (within the chart coordinate space) from right edge of chart to right edge of grid (plot area).
If not specified, then this width will be automatically calculated.
• property marginTop
as %ZEN.Datatype.length;
Margin (within the chart coordinate space) from top edge of chart to top edge of grid (plot area).
If not specified, then this value will be automatically calculated.
• property markerScale
as %ZEN.Datatype.float [ InitialExpression = 1 ];
Scaling applied to chart markers:
A value of 1.0 (or '') will display markers with their default size.
This only applies to charts that support markers.
• property markerShapes
as %ZEN.Datatype.csv [ InitialExpression = "circle,up,down,square" ];
Comma-delimited list of marker shapes used for data series markers.
Possible values are 'up','down','square','circle'.
This only applies to charts that support markers.
• property markerStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for series markers.
• property markersVisible
as %ZEN.Datatype.boolean [ InitialExpression = ..#DEFAULTMARKERSVISIBLE ];
Specifies whether markers should be displayed for the data
points within the chart.
This only applies to charts that display markers.
• property multipleTitleStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for title text within each "multiple" charts.
Used when showMultiples is enabled.
• property onelementClick
as %ZEN.Datatype.eventHandler;
onelementClick event handler:
This event handler is called by the chart
when the user clicks the mouse on a chart element
(such as a line chart marker, or bar in a bar chart).
The event handler is passed an argument, chart,
that is this chart object. You can then use the
getSelectedItem method to determine the
current selected element.
• property ongetData
as %ZEN.Datatype.eventHandler;
ongetData event handler:
This event handler, if defined, is called by the chart
to get an array of values to plot for a data series.
This provides an alternate way to provide display data for
a chart.
The event handler is passed an argument, series,
that contains the ordinal number (0-based) of the data series.
This event handler should return an array of numeric values for
the specified data series.
• property ongetLabelX
as %ZEN.Datatype.eventHandler;
ongetLabelX event handler:
This event handler, if defined, is called by the chart
to get the text for a given label on the x axis.
The event handler is passed an argument, value,
that contains the ordinal number (0-based) of the label.
• property ongetLabelY
as %ZEN.Datatype.eventHandler;
ongetLabelY event handler:
This event handler, if defined, is called by the chart
to get the text for a given label on the y axis.
The event handler is passed an argument, value,
that contains the ordinal number (0-based) of the label.
• property onrenderData
as %ZEN.Datatype.eventHandler;
onrenderData event handler:
This event handler, if defined, is called by the chart
just after it is finished displaying grid lines and data.
The event handler is passed an argument, chart,
that is this chart object. If it also passed group,
which is the SVG group to which any new svg content should be added.
• property onrenderPlotArea
as %ZEN.Datatype.eventHandler;
onrenderPlotArea event handler:
This event handler, if defined, is called by the chart
just after it displays its underlying plot area (and
bands) but before it display grid lines and data.
• property onshowTooltip
as %ZEN.Datatype.eventHandler;
onshowTooltip event handler:
This event handler, if defined, is called by the chart
just before it displays a tool tip.
• property plotAreaStyle
as %ZEN.Datatype.svgStyle [ InitialExpression = "fill:url(#glow-silverDiag);" ];
Optional: style used for chart plot area panel.
• property plotEdgeStyle
as %ZEN.Datatype.svgStyle;
Optional: for charts with a 3D look, this style is applied
to the edges on the left and bottom.
• property plotStyle
as %ZEN.Datatype.svgStyle;
Optional: default style applied to svg elements used for plotting
data by this chart (such as the line in a line chart).
• property plotToEdge
as %ZEN.Datatype.boolean [ InitialExpression = ..#DEFAULTPLOTTOEDGE ];
Specifies how values should be plotted along a category axis.
If true, plot the first and last values on the edges of the plotArea
(as in a line chart). If false, plot values in the centers of each
unit (as in a bar chart).
This is specified by subclasses.
• property scrollButtonStyle
as %ZEN.Datatype.svgStyle;
Optional: style applied to zoom and scroll buttons when visible.
• property selectedItem
as %ZEN.Datatype.integer [ InitialExpression = -1 ];
Item number (0-based) of currently selected chart element, if any.
• property selectedItemStyle
as %ZEN.Datatype.svgStyle;
Optional: style used to indicate the current selected
chart element.
• property selectedSeries
as %ZEN.Datatype.integer [ InitialExpression = -1 ];
Series number (0-based) of currently selected chart element, if any.
• property seriesColorScheme
as %ZEN.Datatype.string(VALUELIST=",urban,tuscan,caribbean,rustbelt,bright,glow,gray,pastel,solid") [ InitialExpression = "bright" ];
This is the name of a built-in color scheme used to plot
data series for the chart.
If seriesColors is defined, then this
property is ignored.
• property seriesColors
as %ZEN.Datatype.csv;
Comma-delimited list of CSS color values used for data series.
This can be set to a list of SVG fill color values, e.g.,
"red,green,blue" or "url(#glow-red),url(#glow-green),url(#glow-blue)".
The first color is used by the first data series and so on. If there are
more data series than colors, the colors are repeated.
If this is not defined the colors defined by seriesColorScheme
are used.
• property seriesColorsOverride
as %ZEN.Datatype.csv;
Additional Comma-delimited list of CSS color values used for data series.
If supplied, this is merged with the colors in the seriesColors list.
This makes it possible to override specific colors within a chart while preserving
the underlying default colors.
• property seriesCount
as %ZEN.Datatype.integer(MINVAL=0);
Number of data series to display on this chart.
If "", then this is computed automatically from the chart's data source when the
chart is connected to a dataController.
• property seriesNames
as %ZEN.Datatype.csv(ZENLOCALIZE=1);
Comma-delimited list of names used to label each data series in the legend box.
This is a localized value (the entire list is treated as one localized string).
• property seriesNumber
as %ZEN.Datatype.integer(MINVAL=0);
Optional. If defined then the chart will only plot the specified data series (0-based) when connected
to a data controller. This is used by DeepSee in some cases.
• property seriesSize
as %ZEN.Datatype.integer(MINVAL=0);
Number of items within each data series to display on this chart.
If "", then this is computed automatically from the chart's data source when the
chart is connected to a dataController.
• property seriesYAxes
as %ZEN.Datatype.csv;
Optional. If defined, specifies which y-axis should be used for each data
series. This is a csv-list of y-axis numbers (0-based).
By default, the every data series uses y-axis 0.
• property showMultiples
as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
Optional: If true, display chart as number of small multiple charts, one per data series.
This is only used by charts that support small multiples otherwise it is ignored.
• property stripeStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for grid stripes (when enabled).
• property stripesVisible
as %ZEN.Datatype.boolean [ InitialExpression = 0 ];
Optional: if true, draw stripes over value axis grid lines.
• property textSize
as %ZEN.Datatype.string(VALUELIST=",small,medium,large") [ InitialExpression = "medium" ];
Optional: if "medium", use the default font sizes specified by the CSS for the chart.
if "small" or "large" adjust the size of any text in the chart that does not have an explicit
style set (via a property).
• property title
as %ZEN.Datatype.caption;
Title to display for chart.
• property titleBoxStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for box underneath title text.
• property titleStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for title text.
• property titleX
as %ZEN.Datatype.length;
If this chart has a title, x-position (within the chart coordinate space) of the title.
If not specified, then a default value is calculated.
• property titleY
as %ZEN.Datatype.length;
If this chart has a title, y-position (within the chart coordinate space) of the title.
If not specified, then a default value is calculated.
• property valueLabelStyle
as %ZEN.Datatype.svgStyle;
Optional: style used for value labels.
This only applies to charts that display element values (such as bar charts).
• property valueLabelsVisible
as %ZEN.Datatype.boolean [ InitialExpression = ..#DEFAULTVALUELABELSVISIBLE ];
Specifies whether values should be displayed for elements within the chart.
This only applies to charts that display element values (such as bar charts).
• property xAxis
as %ZEN.Auxiliary.axis(ZENSETTING=0);
x axis specification for this chart.
• property yAxis
as %ZEN.Auxiliary.axis(XMLPROJECTION="none",ZENSETTING=0);
Deprecated. y axis specifications for this chart.
This is replaced by yAxisList. This prooperty is kept here so that
applications that set yAxis directly will still function.
• property yAxisList
as list of %ZEN.Auxiliary.axis(XMLPROJECTION="ELEMENT",XMLREF=1,XMLTYPECONSTRAINT="CHOICE",ZENSETTING=0);
List of y axis specifications for this chart.
• method addCommas(nStr)
[ Language = javascript ]
Format numeric value.
• method adjustChartTitle()
[ Language = javascript ]
Adjust position of chart title and legend (if needed).
• method calculateAxisConstraints()
[ Language = javascript ]
If the plot has axes, pre-calculate the internal values that will be used
to govern how those axes are rendered
• method calculateXAxisHeight()
[ Language = javascript ]
• method calculateXAxisTitleHeight()
[ Language = javascript ]
• method calculateYAxisWidth()
[ Language = javascript ]
Internl method to calculate how much room should be reserved
for the Y axis area. This includes both the axis title and
the individual lables
• method chartElementClickHandler(evt, series, item)
[ Language = javascript ]
Mouse click handler for chart elements.
Subclasses can use this method to associated click events
with chart elements.
• method computeEffectiveExtents(x, y, w, h, angle)
[ Language = javascript ]
• method computeStyle(className, idName)
[ Language = javascript ]
Compute and return the effective style that governs the rendering
of a given SVG element based on class and Id
• method createMarker(series, item, x, y, color, type, noevents)
[ Language = javascript ]
Create a plot marker.
This may be used by subclasses to display markers.
type can be 'up','down','circle','square'.
• method createSVGTextNode(caption, fontSize, autoScale, align, rotate, parentNode)
[ Language = javascript ]
• method createXLabelNode(index, fontSize, style, angle, group)
[ Language = javascript ]
• method embedStyle(element, styleNVP)
[ Language = javascript ]
Embed the various settings of a computed style name-value object
as direct attributes of the given node.
• method getChartElement(series, item)
[ Language = javascript ]
Return the svg object for a specified data element (if any).
• method getChartElementStyle(series, item)
[ Language = javascript ]
Return default style for the specified data element (if any).
This is used to restore styles when chart elements are unselected.
Subclasses can override this.
• method getChartRelatedElements(series, item)
[ Language = javascript ]
Return an array of related svg objects for a specified data element (if any).
(such as the edges of a 3d rendering).
• method getChartTitle()
[ Language = javascript ]
Get title for the chart.
• method getColorSchemeArray(scheme)
[ Language = javascript ]
Return an array of color values for given data series
color scheme.
• method getComputedFontSize(styleNVP, defaultMedium, defaultSmall, defaultLarge)
[ Language = javascript ]
Given a resolved style name-value pairing object, return the specified font
size, if none has been specified, return one of three default values based on the
value of the textSize property.
• method getLegendLabels()
[ Language = javascript ]
Return an array of labels to display within the Legend box.
Default implementation is to return a list of series names.
• method getMarkerShape(series)
[ Language = javascript ]
Return the marker type that should be used for the given series.
• method getNumericAbbreviation(val, min, max)
[ Language = javascript ]
Return a numeric abbreviation for a value.
min and max are range that value falls within.
E.g., 10K for 10000
• method getPelToPixelHRatio()
[ Language = javascript ]
The Normalized viewbox ranges from 0 0 to 100 100, the physical space
occupied by the chart is specified as the width and height (in pixels) of
the base SVG group. This function returns a mapping of logical picture
units to pixels in the horizontal direction.
• method getPelToPixelVRatio()
[ Language = javascript ]
The Normalized viewbox ranges from 0 0 to 100 100, the physical space
occupied by the chart is specified as the width and height (in pixels) of
the base SVG group. This function returns a mapping of logical picture
units to pixels in the vertical direction.
• method getPlotX(val)
[ Language = javascript ]
Given a logical value, return the corresponding x-axis
coordinate.
• method getPlotY(val, yAxisNo)
[ Language = javascript ]
Given a logical value, return the corresponding y-axis
coordinate.
• method getRangeGroupForSeries(series)
[ Language = javascript ]
Indicate which "group" should be used for computing axis ranges.
This is overridden by combo charts.
• method getSelectedItem()
[ Language = javascript ]
Returns index number (0-based) of the
current selected item, or -1 if there is no current selection.
• method getSelectedSeries()
[ Language = javascript ]
Returns index number (0-based) of the data series of the
current selected item, or -1 if there is no current selection.
• method getSeriesColor(series)
[ Language = javascript ]
Return the CSS color that should be used for the given series.
• method getSeriesCount()
[ Language = javascript ]
Return the number of data series for this chart.
• method getSeriesData(series)
[ Language = javascript ]
Return data values for the given series (0-based)
from the chart's data cache.
• method getSeriesNames()
[ Language = javascript ]
Return an array containing the names of the data series for this chart.
If a name is missing, the series number is used.
If the chart is connected to a data controller, get the names from the controller.
• method getSeriesSVGGroup()
[ Language = javascript ]
Return the svg group element that contains the data series elements.
• method getSeriesSize()
[ Language = javascript ]
Return the number of items within each data series
(this assumes that all data series have the same number of items).
• method getSeriesType(series)
[ Language = javascript ]
Return the type (how a series should be displayed) for the given data series (0-based).
This is used by combo chart and ignored by all others.
• method getXAxis()
[ Language = javascript ]
Return the x Axis definition for this chart.
• method getXAxisTitle()
[ Language = javascript ]
Return the x axis title.
• method getXAxisType()
[ Language = javascript ]
Return the type of x axis (category or value) used by
this chart.
• method getXLabelText(val)
[ Language = javascript ]
Given a logical value, return the text to use for an axis label.
Subclasses can override this for custom behavior.
• method getYAxis(index)
[ Language = javascript ]
Return the y Axis definition for this chart
(or null if not found).
• method getYAxisCount()
[ Language = javascript ]
Return the number of y Axis definitions for this chart.
• method getYAxisIndexForSeries(series)
[ Language = javascript ]
Return the index (0-based) of the y-axis associated with the given data series.
It may return -1 if the chart is not rendered yet.
• method getYAxisTitle()
[ Language = javascript ]
Return the y axis title.
• method getYAxisType()
[ Language = javascript ]
Return the type of y axis (category or value) used by
this chart.
• method getYLabelText(val, yAxisNo)
[ Language = javascript ]
Given a logical value, return the text to use for an axis label.
Subclasses can override this for custom behavior.
• method hasAxes()
[ Language = javascript ]
Indicates that this chart has axes and associated grids
A subclass may override this to turn off axis display.
• method hasMultiples()
[ Language = javascript ]
Indicates that this chart supports and is in "show multiples" mode.
A subclass may override this.
• method initializeAxisProperties()
[ Language = javascript ]
• method integrateStyleSpec(styleNVP, newRule)
[ Language = javascript ]
Integrate a new Style specification into an exising set of
name-value style pairs, adding and overwriting existing styles
as appropriate
• method is3D()
[ Language = javascript ]
Indicates whether this chart should be drawn with a 3-D
appearance.
• method notifyViewHandler(reason, data1, data2, data3)
[ Language = javascript ]
Notification that the dataController associated with this dataView
has raised an event.
• method pickVerticalSkips(flag, max)
[ Language = javascript ]
This is the core of the vertical decimation algorithm. Given a maximum number of label
to choose from an array, pick a subset that will (hopefully) use the available
space effectively and keep things visually balanced.
• method plotLineForSeries(group, s, data, stacked, chartFilled, markersVisible, hasEvents)
[ Language = javascript ]
Draw a line for one data series, s (0-based).
data contains the data for all series as an array of arrays.
• method prepareAxisGroup(idName, parentNode)
[ Language = javascript ]
Prepare the axis group for population with axis information
• method removeChildNodes(node)
[ Language = javascript ]
• method renderAxes()
[ Language = javascript ]
Draw the x and y axes and grid lines.
• method renderBands()
[ Language = javascript ]
Draw the upper/lower bands for the chart.
• method renderContents()
[ Language = javascript ]
Client-side method to render control.
• method renderLegend()
[ Language = javascript ]
Draw the legend for the chart.
• method renderPlotArea()
[ Language = javascript ]
Draw the plot area of the chart.
• method renderSeries(group)
[ Language = javascript ]
Draw data series for this chart.
This is implemented by subclasses.
group is the SVG container for the chart components.
• method renderSeriesGroup()
[ Language = javascript ]
Draw the data series for this chart.
This method renders the container for the data series and
then invokes a sub-class specific renderSeries method.
• method renderTitle()
[ Language = javascript ]
Draw the title for the chart.
• method renderXAxisTitle(group)
[ Language = javascript ]
Draw the title section for the Y axis (if any) and
return the height reserved for the rendering
• method renderXLabels()
[ Language = javascript ]
Draw the labels for the x axis.
• method renderYAxisTitle(group)
[ Language = javascript ]
Draw the title section for the Y axis (if any) and
return the width reserved for the rendering
• method renderYLabels(test)
[ Language = javascript ]
Draw the labels for the y axis.
If test is true, then this is a "test" plot to determine
the max width of the labels.
• method selectElement(series, item)
[ Language = javascript ]
Select the specified chart element.
• method setCurrYAxis(axisNo)
[ Language = javascript ]
Set the current y Axis definition used this chart.
axisNo is the index of the y-axis, 0-based.
• method setProperty(property, value, value2)
[ Language = javascript ]
Set the value of a named property.
• method setSizeHandler()
[ Language = javascript ]
Notification that this component has been resized.
• method setXAxis(axis)
[ Language = javascript ]
Set the x Axis definition for this chart.
Return the old axis if present.
• method setYAxis(axis)
[ Language = javascript ]
Set the y Axis definition for this chart.
Return the old axis if present.
• method stripWhitespace(str)
[ Language = javascript ]
• method updateChart()
[ Language = javascript ]
Call this method to update contents of this chart.
• method usePercentForRange()
[ Language = javascript ]
This method returns true if data series is a "percentage bar chart" and so
calculated data range should be 0 to 100%
• method useSumForRange()
[ Language = javascript ]
This method returns true if data series should be summed
when calculating data range for the chart.
Typically a chart will return true if it is in "stacked" mode.
