Function | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

## set-chart-value

Arguments: chart-widget &key item-index object-index item-id object-id value from-value low-value high-value icon-size update-now

Establishes one or more of the values to display on a `chart-widget` for a single pairing of a chart item and a chart object. The return value is not defined.

(For example, if a line graph has a line for each bowler on a team, and a bowling score for each week, then each bowler is represented by a chart object while each week is represented by a chart item.)

An alternative to calling set-chart-value multiple times is to provide a chart-value-returner function that will be called as needed to return all of the chart's values. That approach is more efficient if you already have all of the chart's data stored somewhere such as in an array. The set-chart-value approach is somewhat more straightforward, and is more suitable if you are incrementally adding or modifying the data over time.

chart-widget is the widget to modify.

### The keyword arguments

The first group of keyword arguments specify which chart item/object pair to modify.

- item-index is the zero-based index of the chart item to modify, or the symbol `:new` to add a chart item just after the last existing chart item, or the symbol `:last` to modify the last existing chart item (that is, the one with the highest index), or `nil` to not specify an item index. If both item-index and item-id are `nil`, then item-index defaults to `:new`. If both item-index and item-id are true, then the item at item-index is used and its ID is changed to the specified item-id. If the chart is empty and item-index is `:last`, then it behaves like `:new`.
- object-index is the zero-based index of the chart object to modify, or `nil` to not specify an object index. If both object-index and object-id are `nil`, then object-index defaults to zero. If both are true, then object-index takes precedence.
- item-id is the arbitrary ID of the chart item to modify, or `nil` to not specify an item ID. If item-index is `nil` and item-id is true, then if there is an existing item whose ID is item-id then it will be modified, and otherwise a new item will be created just after the current last item, and its ID will be item-id.
- object-id is the arbitrary ID of the chart object to modify, or `nil` to not specify an object ID. If object-index is `nil` and object-id is true, then if there is an existing object whose ID is object-id then it will be modified, and otherwise a new object will be created and its ID will be object-id.

  (If there is no entry in the chart-objects property for the specified object-index or object-id, the chart-objects sequence is expanded to include such an entry.)

The next group of keyword arguments specify one or more values for the specified item/object pair. Any subset of these arguments may be passed, though the auxilliary values will have no effect until if and when the main value is specified for the same item/object pair. A value must always be either a real number to add a value to the chart, or else `nil` to remove a value from the chart. Existing values can be modified by respecifying them in further calls to set-chart-value.

- value is the "main" value that is represented by the end of a bar in a bar graph or by line segment endpoints in a line graph.
- from-value is the starting point of a bar in a bar graph. It defaults to the base-value of the `bar-chart-view`, which in turn defaults to zero.
- low-value is an additional value that is typically somewhat lower than the main value. It is drawn according to the high-low-value-style of the `chart-view`, and is typically used for an error range.
- high-value is an additional value that is typically somewhat higher than the main value. It is drawn according to the high-low-value-style of the `chart-view`, and is typically used for an error range.
- icon-size is the size of the icon drawn at a particular data point on a line graph. The value is an integer to be used as the "radius" of the icon, measured in pixels. It is used only if the draw-icons property of the `line-graph-view` is true, and only if the icon-images property uses names of the built-in line-drawing icons (which are `:circle`, `:square`, `:triangle`, and `:diamond`) rather than pixmaps.
- update-now indicates whether to display the new value now. If `nil`, then the widget is invalidated so that it will be redrawn to reflect the new value, but as usual not until all queued events are handled. This allows adding many values quickly, which will then be displayed once at the end. If true, then the chart will be redrawn immediately. This allows animating the incremental adding of values. (If a sleep or process-wait occurs between the adding of incremental values, then the widget should still redisplay at those times without passing this argument as true.)

See `chart-widget` and also cg-chart-widget.htm.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version