# Directives

CHART | Create/Control Chart

## Formats

1. | Define/Create: | CHART ctl_id,@(col,ln,wth,ht),[,ctrlopt]
2. | Load: | CHART LOAD ctl_id,strvar$[,ERR=stmtref]
3. | Clear Data: | CHART CLEAR ctl_id[,ERR=stmtref]
4. | Clear Data and Titles: | CHART DELETE ctl_id[,ERR=stmtref]
5. | Enable/Disable: | CHART {ENABLE | DISABLE} ctl_id[,ERR=stmtref]
6. | Retrieve Value: | CHART FIND ctl_id,dataset, point,{numvar | label$}[,ERR=stmtref]
7. | Read Selected Set: | CHART READ ctl_id, dataset,eom$[,ERR=stmtref]
8. | Update Existing Values: | CHART WRITE ctl_id,dataset,point,{data | label$}[,ERR=stmtref]
9. | Hide/Show: | CHART {HIDE | SHOW} ctl_id[,ERR=stmtref]
10. | Remove: | CHART REMOVE ctl_id[,ERR=stmtref]

Where:

@(col,ln,wth,ht) | Position and size of the check box region. Numeric expressions. Column and line coordinates for top left corner, width in number of columns and height in number of lines.
ctl_id | Unique logical identifier for the chart (any integer -32000 to +32000). Avoid integers that conflict with keyboard definitions (e.g. 4 cancels CTL=4 for the F4 key) or Negative CTL Definitions. Use this value with the Apostrophe Operator to access various CHART Properties.
ctrlopt | Control options. Supported options for CHART include:
ERR=stmtref | Error transfer.
FMT=def$ | Format type. The standard chart types for FMT= are 3DLINE (Default), 2DAREA, 3DAREA, 2DBAR, 3DBAR, 2DCOLUMN, 3DCOLUMN, 2DLINE, 2DPIE, 3DPIE, 2DRIBBON, 3DRIBBON, 2DSCATTER, 3DSCATTER, 2DSTACK and 3DSTACK.
FNT="font" | Font name (size controlled by window coordinates).
OPT=char$ | Single character parameter. The single character parameters for OPT= are:
"B" | Chart has no border or frame
"D" | Initially disabled
"d" | Permanently disabled
"h" | Permanently hidden
SEP=char$ | Delimiter character; Hex or ASCII string value.
TIP=text$ | Mouse pointer message. To change the colour, see 'TC'= system parameter.
dataset | Dataset from which values will be drawn.
numvar | Name of variable that will contain returned numeric data value.
eom$ | EOM character sequence used to select the set. Hex string expression.
label$ | Name of variable that will contain returned label value.
point | Data point within the dataset.
strvar$ | String containing the chart data.

## Description

Use the CHART directive to create two and three dimensional chart illustrations in a graphical application. When defining the chart, you can select from several available chart types including Area, Bar, Column, Line, Pie, Ribbon, Scatter, and Stack. The chart type and visual look information is determined by the FMT= option.

Chart Properties

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language.

See CHART Properties for the list of properties available for manipulating a chart object.

## Format 1

Creating a Chart

CHART ctl_id,@(col,ln,wth,ht),[,ctrlopt]

Use this format to create the chart. The value in ctl_id is a unique identifier that is used to generate a CTL value whenever the chart is selected and changed.

## Format 2

Loading Data into a Chart

CHART LOAD ctl_id,strvar$[,ERR=stmtref]

Use this format to load chart data into a chart. The last character in strvar$ identifies the separator for the dataset while the value defined by SEP= when the chart is created, is used to identify the different data points within each set. Legend labels can be specified as the first element in a dataset definition followed by an = (equals sign).

Example:

> chart load 10,"100,200,300,400/150,250,350,450/"

The above example loads a chart with two datasets consisting of four points (or data elements).

> chart load 10,"Last Year=100,200,300,400/This Year=150,250,350,450/"

This example includes legend labels for the first example.

## Format 3

Clearing Data from a Chart

CHART CLEAR ctl_id[,ERR=stmtref]

This clears the data values from the chart but not the titles and labels.

## Format 4

Clearing Data and Titles from a Chart

CHART DELETE ctl_id[,ERR=stmtref]

This clears all of the data values and all of the titles from the chart.

## Format 5

Enabling/Disabling a Chart

CHART {ENABLE | DISABLE} ctl_id[,ERR=stmtref]

If the mouse is clicked on a chart while it is enabled, then the program receives a CTL event based on the ctl_id of the chart. This does not occur when the chart is disabled.

## Format 6

Retrieving Values from a Chart

CHART FIND is used to retrieve values from a chart based on the specified dataset and data point. The format is described below.

> CHART FIND ctl_id, dataset, point, data$ [,ERR=stmtref]

The data is read from the chart and returned in data$.

> CHART FIND ctl_id, dataset, point, label$ [,ERR=stmtref]

This format retrieves the label in label$. Legend labels are determined for a specified dataset when the point value is set to zero. Point labels are determined for a specified point when the dataset value is set to zero.

The following example reads the value and label for the second point of the first dataset:

> chart find 10,1,2,RETURN_VALUE
> chart find 10,1,0,LEGEND_LABEL_1$
> chart find 10,0,1,POINT_LABEL_1$

## Format 7

Reading Selected Set from a Chart

CHART READ ctl_id, dataset,eom$[,ERR=stmtref]

Use CHART READ upon receiving a CTL notification that the control was selected with the mouse. The eom$ character will yield $01$ indicating that the dataset was selected by a mouse click.

## Format 8

Updating Existing Values in a Chart

CHART WRITE is used to change existing values in a chart based on the specified dataset and data point.

> CHART WRITE ctl_id,set,point,data$[,ERR=stmtref]

The above format updates the data for an individual point.

> CHART WRITE ctl_id,set,point,label$[,ERR=stmtref]

The above format changes chart labels. Legend labels are updated for a specified dataset when the point value is set to zero. Point labels are updated for a specified point when the dataset value is zero.

## Format 9

Hide/Show a Chart

CHART {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the CHART HIDE format, the chart remains active but is not displayed. It is still accessible to program(s). Use the CHART SHOW to restore the user's display and access.

## Format 10

Removing a Chart

CHART REMOVE ctl_id[,ERR=stmtref]

Use this format to delete an entire chart.

## See Also

Charting Alternatives in PxPlus
CHART Properties