Web > Charts

Charts AmiScript Reference¶

Known issues

Some chart features have known issues in the current release. See Known issues.

This page lists the AmiScript classes for charts, ChartPanel and its plots, axes, and layers, with their methods, callbacks, and the render stats that report what a chart drew.

Overview¶

A chart is a ChartPanel. Find it by its panel id and cast it, then reach its parts from it:

ChartPanel c = (ChartPanel) layout.getPanel("Trades");
ChartPanelPlot p = c.getPlot(0, 0);
ChartPanelLayer l = p.getLayer(0);
ChartPanelAxis a = c.getAxis("left", 0, 0);

Class	What it is
`ChartPanel`	The chart, a panel with a grid of plots and their axes
`ChartPanelPlot`	One plot in the grid
`ChartPanelAxis`	One axis
`ChartPanelLayer`	One layer of a plot. Its kinds are `ChartPanelXYLayer` (bar, line, area, scatter), `ChartPanelRadialLayer` (pie, radial bar, speedometer), `ChartPanelLegend`, `ChartPanelCrosshair`, and `ChartPanelAnnotation`

A script's changes to a chart are transient: they apply in the session until they are committed with the object's commit(). Transient panels are covered in Arranging an application.

Running a script¶

The examples on this page run in a session, where layout and session are defined. To run one in the AMIDB Shell Tool:

Select Dashboard -> AMIDB Shell Tool....
Select "Run on this web session". The tool opens on "Run on Center", where a script that names session fails with "Unknown variable: session".
Type the script, and select "Run (alt+⏎)".
Check the output below the script: a script ending in a value shows it, such as (Table) and its rows for session.getDevTools().getAllRenderStats().

Over MCP, an agent runs the same scripts with web_script.

ChartPanel¶

Method	Returns	Description
`getPlot(Integer x, Integer y)`	`ChartPanelPlot`	The plot at column `x` and row `y`, from `0`. Null outside the grid
`getPlots()`	`List`	Every plot
`getRowsCount()`, `getColumnsCount()`	`Integer`	The number of rows and columns of plots
`getAxis(String position, Integer rowOrColumn, Integer offset)`	`ChartPanelAxis`	An axis by its side, `"left"`, `"right"`, `"top"`, or `"bottom"`, in any case; the row or column it belongs to; and its place on that side, from `0`. Null for any other side
`getAxises()`	`List`	Every axis
`getAxisCount(String position, Integer rowOrColumn)`	`Integer`	The number of axes on one side of a row or column
`toImagePng(Number widthPx, Number heightPx, Boolean printBg)`	`Binary`	The chart as a PNG image. See Exporting a chart as an image
`toImagePngForPlot(Integer plotX, Integer plotY, Number widthPx, Number heightPx)`	`Binary`	One plot as a PNG image, without its axes
`toImagePngForPlotWithBg(...)`	`Binary`	The same, with the background

ChartPanel also has the methods every panel has.

ChartPanelPlot¶

Method	Returns	Description
`getLayer(Integer position)`	`ChartPanelLayer`	The layer at a position, from `0`, the front layer: the last entry in the layer editor's "LAYERS"
`getLayers()`	`List`	Every layer
`getLayersCount()`	`Integer`	The number of layers
`getRow()`, `getColumn()`	`Integer`	The plot's place in the grid; the top row and the left column are `0`
`getOwner()`	`ChartPanel`	The chart

ChartPanelAxis¶

Method	Returns	Description
`getAxisTitle()`, `setAxisTitle(String title)`	`String`, `Boolean`	The axis title
`setMinValue(Number min)`, `setMaxValue(Number max)`	`Boolean`	Fix the axis's lowest or highest value, turning off its automatic range. Return `true`. A null argument returns `false` and changes nothing
`getVisibleMinValue()`, `getVisibleMaxValue()`	`Double`	The lowest and highest values the axis shows now. Use these to read back a range
`getMinValue()`, `getMaxValue()`	`Double`	The axis's stored range. These do not reflect `setMinValue` or `setMaxValue`
`setZoom(Number zoom)`, `getZoom()`, `isZoomed()`	`Boolean`, `Double`, `Boolean`	The zoom factor; `1.0` when not zoomed. A null zoom returns `false`
`setZoomByMinMax(Number min, Number max)`	`Boolean`	Zoom to show a range
`setVisibleOffset(Number offset)`, `getVisibleOffset()`, `getVisibleLength()`	`Boolean`, `Double`, `Double`	The visible part of a zoomed axis
`setMajorTickUnit(Number unit)`, `setMinorTickUnit(Number unit)`	`Boolean`	The tick spacing
`isVertical()`, `isReverse()`	`Boolean`	Whether the axis is vertical, and whether its values run in reverse
`getOffset()`, `getPlotPosition()`	`Integer`	The axis's place
`getChart()`, `getOwner()`	`ChartPanel`	The chart

ChartPanelAxis a = ((ChartPanel) layout.getPanel("Trades")).getAxis("left", 0, 0);
a.setMaxValue(50);
return a.getVisibleMaxValue();   // 50.0; getMaxValue() still returns the earlier value

ChartPanelLayer¶

Method	Returns	Description
`getFormula(String fieldname)`	`String`	A field's expression, such as `getFormula("xLbl")`
`setFormula(String fieldname, String value)`	Listed as `String`	Sets a field's expression. Returns `true` for a known field and `false` for an unknown one. An empty value clears the field
`getFormulaNames()`	`Set`	Every field name the layer has
`resetFormulas()`	`Boolean`	Resets the fields
`getDatamodel()`	`Datamodel`	The layer's datamodel
`getPlot()`, `getOwner()`	`ChartPanelPlot`	The layer's plot
`getChart()`	`ChartPanel`	The chart
`getXAxis()`, `getYAxis()`	`ChartPanelAxis`	The layer's axes
`getZPosition()`	`Integer`	The layer's place in the drawing order
`getSelected()`	`Table`	The rows of the selected shapes
`getCategoryCount()`	`Integer`	The number of categories on a category axis
`getGroupingPosition(Object categoryValue)`	`Double`	A category's position, such as `0.0` for the first; `NaN` for a value that is not a category
`getPositionForOrdinal(Number ordinal)`, `getGroupingSeriesNumber(Object groupingName)`	`Double`	Positions and series numbers by ordinal or name
`getSeriesColor(Number seriesNumber)`	`String`	A series' color, such as `#ef6900`. The palette repeats for numbers past its end
`getStyle(String styleKey)`, `getStyle(String styleKey, Number index)`	`String`	A style value
`sampleAt(Number x, Number y)`, `hitTestAt(Number x, Number y)`	`Map`	What is at a pixel. See Sampling a chart
`hasEntryAt(Number x, Number y)`	`Boolean`	Whether a shape is at a pixel

The field names are those of the layer's "Advanced" form, such as xPos, yPos, xLbl, name, where, orderBy, tooltip, and sel; getFormulaNames() lists them. A bar layer has 45.

setFormula does not check the expression: a column that does not exist is accepted, and the layer then fails to draw, with the error in its render stats, such as "Syntax error for Axis --> Y: Unknown variable: NoSuchCol".

ChartPanelLegend adds getTitle(), getWidth(), getHeight(), and getReferencedSeries(), and ChartPanelCrosshair and ChartPanelAnnotation have the layer methods.

A radial layer, ChartPanelRadialLayer, has the layer methods too, such as getFormula, sampleAt, and hitTestAt, although the class listing in the product shows it with only commit(). One radial field name is spelled raidusLabel.

Sampling a chart¶

sampleAt and hitTestAt report what a layer drew at a pixel of the plot, counted from the plot's top-left corner, with y increasing downward. Both return a map with these keys:

Key	Value
`xValue`, `yValue`	The values at that point, on the layer's axes
`rowNum`	The row of the layer's table
`groupId`	The group of the shape
`exact`	Whether the point is exactly on a shape
`intersects`	Whether the point is inside a shape
`isXDomain`	Whether the values are matched along the x axis
`layerId`	The layer

sampleAt returns the nearest point, whether or not a shape is there; on a pie it returns an empty map. hitTestAt returns the shape at the pixel; on a pie, its xValue and yValue are NaN.

Callbacks¶

A chart has the callbacks onSelected, onZoom, onKey, onMouse, onSize, and onVisible. Its plots, axes, and layers have none. Set them with the chart's menu -> AmiScript Callbacks..., or from AmiScript with getCallback(name).setAmiScript(...).

Callback	Runs when	Parameters
`onZoom`	The user zooms, such as with "Zoom In"	`r`, `c`: the row and column of the zoomed plot
`onSelected`	The selection changes	None. Read the selection with the layer's `getSelected()`

onSelected runs only on a chart whose layer is selectable, with "User Selectable:" set to true. A chart created in the gallery leaves it empty, so its onSelected never runs until it is set. See Making a layer selectable.

Exporting a chart as an image¶

toImagePng(widthPx, heightPx, printBg) returns the chart as a PNG image, as a Binary:

ChartPanel c = (ChartPanel) layout.getPanel("Trades");
Binary png = c.toImagePng(400, 300, false);
return png.getLength();

The arguments and result behave as follows:

All 3 arguments are required; a call with 2 is a compile error.
printBg false gives a transparent background, and true the chart's background color.
A null width and height use the chart's size on screen.
The same chart gives the same image each time it is exported.
A width and height of 0 stop the script: it returns null, and the session's Logger records "Thrown: Width (0) and height (0) cannot be <= 0".
A width and height other than the chart's own draw the chart at its on-screen layout, so part of it is cut off or it fills only a corner. The whole chart is drawn with null for both; maximize its window first.
The export draws axis labels rotated, and long ones are clipped. On a date axis left on "Auto", it labels every tick with a date and a time, where the window shows times above a row of dates. Its date labels are placed as in the window; see Dates on an axis.

Render stats¶

Render stats report what each part of a chart drew from its data, so a chart that looks empty or wrong can be diagnosed without looking at it.

Table t = session.getDevTools().getAllRenderStats();

getAllRenderStats() returns one table for every chart in the session, and getRenderStats(panel) the same for one panel. The columns are:

Column	Holds
`Panel`	The chart's panel id
`Scope`	`PANEL`, `AXIS`, or `LAYER`
`Id`	The part: the panel, an axis such as `LEFT#3`, or a layer's id
`Type`	The part's type, such as `amichartgrid`, `vertical`, `Chart`, `Legend`
`Binding`	A layer's datamodel and table
`Rows`	The rows a layer drew
`Detail`	The panel's size and plot and layer counts, an axis's range and title, or a layer's group count
`Problem`	Why a layer drew nothing, or empty

The Problem texts, and what each means, are listed in Troubleshooting. Some are reported for layers that are working.

session.getDevTools().getSchemaWarnings(panel) returns a chart's schema warnings: the field expressions that name columns its datamodel does not output.

What this does not support¶

Restoring an axis's automatic range: no AmiScript call turns it back on once setMinValue or setMaxValue has been used. setMinValue(null) and setMaxValue(null) return false and change nothing.
Reading back a range set from AmiScript with the getters: getMinValue() and getMaxValue() keep returning the earlier values. Read getVisibleMinValue() and getVisibleMaxValue() instead.