Generic 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

## plot-value-returner

Arguments: plot-widget

The value of this property can be a function (or the name of a function) that supplies the data values to be displayed in a plot-widget. Otherwise it should be `nil` (the default), in which case the plot's data must be supplied by calling set-plot-value multiple times. plot-widget must be a `plot-widget`.

The function will be called automatically every time the plot-widget draws a value. The arguments to the function indicate which plot value index and object it is drawing, and which type of value. The function should return a number to display, or else `nil` if that type of value should not be drawn for the specified object and value index.

Generally when using a plot-value-returner you should also specify the plot-values-max-index property of the plot-widget, and maybe also the plot-values-min-index property, to tell the plot the range of value indexes that it should pass to the function. And if the plot contains more than one object, then you should also set up the chart-objects property to tell the plot the range of object indexes that it should pass to the function (and typically their object IDs as well).

Note that in the inspector this property is on the Events tab because its value is a function, though it is not actually handling window system events.

See the page for the `plot-widget` class for an example of a plot-value-returner function.

The parameter list of a plot-value-returner function should be this:

Arguments: plot-widget value-type value-index object-index object-id

These arguments are:

- plot-widget is the plot being drawn.
- value-type is the type of value that is being drawn. This will be one of the following keywords:
  - `:x`: the X coordinate of the point that is being plotted. This is always measured along a horizontal axis.
  - `:y`: the Y coordinate of the point that is being plotted. This is always measured along a vertical axis.
  - `:x-low`: an optional value that's normally less than the X coordinate.
  - `:x-high`: an optional value that's normally greater than the X coordinate.
  - `:y-low`: an optional value that's normally less than the Y coordinate.
  - :y-high: an optional value that's normally greater than the Y coordinate.
  - `:icon-size`: an optional size for a built-in icon drawn for a data point.

  (If a particular type of value will never be drawn, then for efficiency that value type could be removed from the value-types property of the plot-widget. That will prevent the plot-value-returner function from ever being called for that type of value.)

- value-index is the zero-based index of the point being drawn.
- object-index is the zero-based index of the chart object being drawn.
- object-id is the arbitrary ID of the chart object being drawn. This will be meaningful only if you have set up the chart-objects property of the plot-widget to specify object IDs; otherwise an object-id will default to the object-index.

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