Chart Object Properties

Setting the chart type:

type

The type property determines the type of chart. It is a text string, which is one of the following values (case is ignored when you assign the string):

'line' (default)

Selects a Line Chart. Each series is drawn as lines between successive X, Y points. By default, markers are not shown at each point. (If you want markers, set the marker property for the series). You can specify the color and line type for each series individually, or leave the Chart object to select a default.

'stair'

Selects a Stair Chart. Same as a Line chart, except that instead of the line being drawn directly from each X,Y point to the next, a horizontal line is drawn first to the next X position, and then a vertical line is drawn to the next Y position.

This sort of chart is useful for displaying series where the Y values change in step-wise fashion (for example, a chart of interest rates set by a central bank against time, or a chart showing a digital representation of an analog value).

'area'

Selects an Area Chart. Similar to a line chart, except that each series is drawn as a filled area between the lines connecting the X,Y points, and the X axis. The series are drawn in the order in which they were created, so a later series may conceal some or all of an earlier series. You can specify the color and fill pattern for each series individually, or leave the Chart object to select a default. (Tip: If you want to avoid concealing one series underneath another, you can set the fillpattern property of each series to be something other than solid).

'scatter'

Selects a Scatter Chart. No line is drawn between the X,Y points of the series; instead, a marker is drawn at each X,Y point. You can leave the Chart object to choose a default marker type, or specify it yourself using the marker property of each series.

This sort of chart is useful for displaying experimental results. (Sometimes, you will also want to include a separate line series showing a theoretical fit to the experimental results, or a least-squares regression to show a trend. You can do this using the mixed chart type).

'bar'

Selects a Bar Chart. The graph is drawn as a series of filled vertical bars from the X axis. (The X values are ignored, except possibly to set labels for the bars). If you have more than one series, the bars for each series are displayed side-by-side. As with the other chart types, you can set the fill color and/or pattern individually for each series, or leave the Chart object to choose defaults. You can also set the thickness of each bar (relative to the available space) using the barwidth property.

'stackedbar'

Selects a Stacked Bar Chart. Like a bar chart, but the bars for each series are placed on top of each other at each data point, rather than side-by-side. This type of chart is useful for showing both the total value of a quantity (for example, total sales by quarter), and the contributions to the total (for example, how much each region contributed to the total).

Normally, stacked bar charts are used only for series where all the Y data values are positive. If there are negative Y values encountered at a given X value, there will in effect be two stacked bars drawn; the positive ones will be stacked on top of each other in the positive direction, and the negative ones will be stacked on top of each other in the negative direction.

'horizbar'

Selects a Horizontal Bar Chart. Same as a Bar chart, except that the bars are drawn horizontally.

'horizstackedbar'

Selects a Horizontal stacked bar chart. Same as a Stacked Bar chart, except that the bars are drawn horizontally.

'hilo'

Selects a High-Low-Open-Close (HLOC) chart. Unlike the previous chart types, for an HLOC chart you need to specify more than one Y value for each X value for a series. As a minimum, you should specify the High and Low values (using the properties highvalues and lowvalues). For a financial chart, these typically represent the highest price and the lowest price reached by a stock or commodity during a particular trading period. The chart is drawn as a series of vertical bars between the High and Low values for each X value (thus showing the price range for the period). You can optionally specify Open values for the series (using the property openvalues), typically representing the opening price for the period. These are drawn as a small tick to the left of the vertical bar. You can also optionally specify Close values for the series (using the property closevalues, which is a synonym for yvalues). These are drawn as a small tick to the right of the vertical bar.

Although primarily used for financial data, this type of chart can also be used for other applications, such as displaying experimental results. In this case, the Open and Close values would both be specified to represent the primary experimental results, with the High and Low values representing the confidence limits.

'candle'

Selects a Candlestick chart. This is a variant of the High-Low-Open-Close chart. Again, a line is drawn between the High and Low values, but the difference between the Open and Close values is shown by a rectangle. If the Open value is greater than the Close, the rectangle is filled with the series foreground color, otherwise it is filled with the background color.

This type of chart is often used to show price trends over time; the filled rectangles make it very obvious whether the closing prices were higher or lower than the opening prices for each trading period.

'pie'

Selects a Pie chart. Draws one or more circular areas, where each value is shown as a slice of the circle representing the proportion of the total attributable to each series. As such, they are rather like stacked bar charts, except that you cannot tell the total value at each point, only the proportion contributed by each series. Negative values are ignored. If there are multiple pie charts displayed, they are automatically arranged in rows and columns to make the best use of the available space. Each pie will have the same radius.

By default, the pie chart will be accompanied by a 'legend' which shows the colors used for each series (provided you have specified a caption property for the series). However, the pie chart often looks better if you disable the legend (by setting the placelegend property of the Chart object to 'none'), and use the style property to cause each pie slice to be labelled with the series caption and a percentage value.

Caution: The Chart object displays one pie chart for each X value, with each series contributing a slice to each pie (unless the value is zero or negative). It does NOT display one pie per series. Thus, in the limiting case where you want a single pie showing four segments, you need to create four separate series, each with just one value. Although this may seem somewhat unnatural at first, it is implemented in this way for consistency with other chart types (especially bars and stacked bars). This means you can swap between the different chart types to display the same data in different ways. This approach also allows you to set the color, fill pattern and caption for each segment by setting properties of the Series objects. The QUICKPIE function in the workspace 10 SAMPLESCHART can be used if you want to create a simple pie chart from an APL array.

You can label the individual pies by setting xlabels property of the Chart object.

'mixed'

Selects a Mixed chart type, with different types for each Series. For all of the Chart types above, each series in the chart in displayed in the same way. Sometimes, however, you might want to mix different types of chart together. For example, you might want to show experimental results as a Scatter chart, and the prediction of a mathematical model of the data as a Line chart. Or you might want to show monthly profit figures as a Bar chart, and the cumulative year-to-date profit as a Line chart.

If you set the type property of the Chart object to 'mixed', then each series will be drawn according to the type property of the individual Series object. This can be any of the above types except for horizontal or stacked bars, or pies.

Setting titles and labels:

title or caption
subtitle
note

These properties are all text vectors, and are simply labels displayed around the chart. Normally, the title property is displayed in the largest font, and is intended to represent the title for the whole chart. The subtitle property is displayed below the title, in a slightly smaller font, and is intended as a sub-title for the whole chart. The note property is typically displayed in a small font, and is intended to represent additional information such as a copyright notice or acknowledgement. However, you can use these labels in any way you wish, or omit them altogether by leaving them as empty vectors.

xaxislabel
yaxislabel
yaltaxislabel

These properties are also text vectors, and are labels displayed adjacent to the axes. They are usually used to indicate the units or meaning of the scale along the axis.

Specifying where labels and legends are drawn:

placetitle
placenote
placelegend

These properties determine where various labels of the chart are drawn.

The placetitle property determines where the title and subtitle (if any) are drawn. It is a text string, and can be one of the values 'top', 'topleft', 'topright', 'bottom', 'bottomleft', 'bottomright'. The default is 'top', meaning the title is centered above the chart.

The placenote property determines where the note (if any) is drawn. It can have the same values as the placetitle property. The default is 'bottomright'.

The placelegend property determines where the chart legend is drawn. The legend shows, for each series which has a non-empty caption property, a sample line, marker, or filled rectangle as appropriate, next to the caption. (If a given series has no caption, it will not appear in the legend). This property is a text string, which can be one of the values 'top', 'left', 'right', 'none', or an empty vector. If it is 'none' or an empty vector, the legend is not shown. The default is 'top'.

Choosing fonts:

font

The font property determines the base font used for the Chart object. By default, the Chart object uses this base font for every text element it draws, with the size being chosen as a proportion of the window size, and different sizes for the different elements (for example, the title is drawn as the biggest). By changing the font property, you can change the font family used to display all elements unless they are specifically altered using one of the specific font properties described below. The font property uses the same form as the font property of other controls, i.e. it is a nested vector of (Font name) (Size) (Style) (Character set). However, the Size parameter is not used. The default is Arial, plain text.

Note: Take care when changing this property to use a font which displays well at a wide range of sizes, unless the chart is not resizable. We recommend that you use a TrueType or OpenType font in all cases.

fontaxis
fontlegend
fontnote
fonttitle

These properties allow you to specify the font for individual elements of the chart. Any changes you make to these override the setting of the base font property.

These properties are specified in a similar way to ordinary font properties, as a nested vector of (Font name) (Size) (Style) (Character set). However, the Size is defined in a special way. If it is set to a value between 0 and 1, it means that the height of the font should be the specified proportion of the window size, defined as the smaller of the window height and width. Values in the region of 0.03 to 0.05 are reasonable. This is recommended for resizable charts, to ensure that the labels remain in proportion to the chart as a whole. (If the font gets too small, a lower limit is imposed). If the font size is specified as an integer greater than 1, it is interpreted as a font size in Points, and will be fixed irrespective of the size of the Chart. This is likely to mean that the chart does not display well at very small or large sizes.

If the Font name is an empty vector, the base font family is used. If the Size or Style element is ¯1, the corresponding font attribute is left unchanged.

Specifying ticks, tick labels, and intercepts:

xmajorticks
ymajorticks
yaltmajorticks
xminorticks
yminorticks
yaltminorticks

By default, the Chart object chooses a suitable scale automatically, and chooses sensible major and minor tick positions. It labels the major tick positions with the corresponding numeric value.

These properties allow you to specify your own positions for the major or minor ticks along the X axis, Y axis, and alternate Y axis (if used). Each property is a numeric vector, specifying where each tick should be drawn. If both the major and minor tick vectors for a particular axis are empty (which is the default), the Chart object will position the tick marks automatically. If either the major or minor tick vector is not empty, ticks will be drawn only where you have specified them.

If you specify your own tick positions, the scale for a particular axis will usually range from the lowest tick mark you specify to the highest. However, it will be extended to include any data point which would otherwise fall outside the range.

xlabels
ylabels
yaltlabels

These properties can be used to change the labels written next to the major tick marks. By default, the Chart object labels the major ticks with the corresponding numeric value. If you specify one of these properties, then your labels will be used instead. However, (except for the X axis of a bar chart or pie chart), you must also specify the corresponding major tick positions, otherwise the Chart object will not know where the labels should be placed.

The labels can be specified either as a character vector with embedded carriage returns, or as a text matrix, or as a nested vector of character vectors. The first label is used for the first major tick position, and so on. If there are more labels specified than tick positions, the surplus labels are ignored. If there are fewer, the ticks which do not have user-defined labels are labelled with the default numeric value.

xlogscale
ylogscale
yaltlogscale

These are Boolean scalar properties. If set to 0 (which is the default), a normal linear scale applies. If set to 1, a logarithmic scale is used for the corresponding axis.

You cannot set a logarithmic scale for an axis where any data point is 0 or negative. If this situation occurs, the scale will revert to linear.

xintercept
yintercept

These properties can be used to specify where the X axis and main Y axis should cross the other axis. By default the X axis is placed at the bottom edge of the graph, or at the Y value of 0 if the Y axis ranges from negative to positive values, but you can specify a different position by changing the yintercept property. Similarly, the Y axis is by default placed at the left edge of the graph, or at X value 0 if the X axis ranges from negative to positive values, but you can specify a different value using the xintercept property.

xaltintercept

Returns the X position where the alternate Y axis (if any) crosses the X axis. Because the alternate Y axis is always drawn on the right-hand edge of the chart, this property is read-only.

xscale
yscale
yaltscale

These are read-only properties, each comprising a two-element numeric vector. They return the limits of the X, Y and Alternate Y axes respectively.

Changing the appearance of the chart:

style

The style property of a Chart object is the sum of a set of flags:

The default is 0.

border

The border property is a Boolean scalar. If it is set to 1, a border is drawn around the whole Chart object, including the titles and other labels.

monochrome

Normally, charts are drawn in color, with different series being drawn in different colors to distinguish them. Sometimes, however, you may want the chart to be drawn in monochrome, for example if you are printing it on a black-and-white printer. The monochrome property allows this. If you set it to 1, all the elements of the chart will be drawn in the Chart object's Foreground color (by default, black). Since this means that the different series cannot be distinguished by color, they will instead be distinguished by line type (solid, dashed, dotted, etc) or by fill pattern (vertical hatch, horizontal hatch etc). See the linetype and fillpattern properties of the Series object for more information on these.

color or colour

The color property is defined in the same way as for other objects. It sets the Foreground and Background color of the Chart as a whole. Colors can be specified in one of two ways. In the first way, you specify a vector of three integers (Red, Green and Blue), so that for example 255 0 0 is pure red and 255 255 255 is white. In the second way, you specify a single integer which encodes the three values in base 256 as 256 ⊥ Blue Green Red. In addition, three special values are recognised; ¯1 means use the parent's foreground or background color as appropriate; ¯2 means use the default color (black for foreground and white for background); ¯3 (valid only for the Background) means that the background of the Chart is transparent, allowing you to draw the chart on top of a picture.

When the Chart is drawn, the control is first set to the Background color (unless it is transparent), and then the various graphics elements are drawn. By default, the axes, grids, labels and titles are all drawn in the Foreground color, but you can change this using more specific properties (see below). The data lines, markers, bars, or pie slices for each series are drawn in the color associated with the series (or in the Foreground color if the monochrome property is set to 1). Note that the Chart object chooses a default color for each series when it is created; you can change this by setting the color property for the child Series object.

coloraxis or colouraxis
colorgrid or colourgrid
colorlegend or colourlegend
colornote or colournote
colortitle or colourtitle

These properties allow you to set specific colors for the various individual elements of the chart. They are specified as a single color value (vector of three separate RGB values, or a single integer encoding the three values). The default is ¯1, meaning use the Chart object's foreground color. These properties are ignored if the monochrome property is set to 1.

linewidth

The linewidth property of the Chart is an integer scalar, which specifies the width in pixels of lines drawn in the chart. The default is 1. The value set here is used for all lines (axes, grids, and the data series lines), unless you specify a different value for a particular element using one of the more specific properties described below. You can set the line width for a particular data series by using the linewidth property of the child Series object.

axiswidth
gridwidth

These two properties allow you to specify the line width (in pixels) for the axis and grid lines respectively, as an integer scalar. The default is ¯1, which means use the value set in the Chart object's linewidth property.

barwidth

The barwidth property allow you to specify the width of the bars used in bar charts. It is an integer scalar, in the range 0 to 100, representing the percentage of the available width used to draw the bars at each X value. (For a Bar or Horizontal Bar chart with multiple series where the bars for each series are placed side by side, this width is shared equally between the different series). If the barwidth property is set to 100, then 100% of the available space is used, so there will be no gaps between the bars. If it is set to a low value (say 20), then the bars will be very narrow, with lots of white space between them. The default is 80.

margin

This property sets the space which the Chart object leaves around the chart. (In addition to this, the Chart object automatically allows extra space for the titles, legend, axis labels, and tick labels.) It is a numeric vector of four elements, representing the Left, Right, Top and Bottom margins, in the units set by the standard scale property of the control (do not confuse this with the X and Y scales used for plotting data). The default is 16 pixels for all four margins.

When you use the Print method to print the chart, the values in this property are added to the print margins specified on the Printing tab of the APLX Preferences dialog.

Other properties:

workarea

This is a read-only property. It returns a vector of four numbers, representing the Top Left Bottom Right of the data area of the graph within the control (i.e. the area enclosed by the axes, excluding any margin, titles, legend, or axis labels). It is expressed in the units set by the standard scale property of the control. It can be used if you need to draw extra features on the chart (see the notes on the Draw method below).

update

Normally, any changes you make to the chart take effect almost immediately (when events are next processed). In some cases, this might give a flickering effect if the chart ends up being redrawn several times because you are making a lot of changes to it. You can temporarily disable redraws by setting the update property to 0, and then making a sequence of changes to the chart. When you set the update property back to 1, the chart will be redrawn once, with all of the changed properties.

bitmap

The bitmap property is read-only. It returns a numeric matrix, which represents the image of the chart as an array of pixel values, with each pixel encoded as the RGB value. The image can be displayed in a Picture object, or (using an Image object), manipulated further and saved to file in any of the supported formats (such as JPEG or GIF).

picture

The picture property is read-only. It is similar to the bitmap property, in that it represents the image of the chart. However, instead of representing each pixel of the chart it is currently drawn, it contains the series of drawing commands (encoded in a platform-specific way into a vector of integers). It is thus a vector-graphics version of the chart image, and can be re-drawn in good quality at different sizes, typically in a Picture object. You can also write it to file, or to the clipboard. (The picture property is not currently implemented under Linux).

svg

This read-only property returns the representation of the chart in Scalable Vector Graphics (SVG) format. This format is ideal for publishing your charts, since SVG will retain high-quality output on high-resolution devices.