chart-value-returner

Arguments: chart-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 chart-widget. Otherwise it should be nil (the default), in which case the chart's data must be supplied by calling set-chart-value multiple times. chart-widget must be a chart-widget.

The function will be called automatically every time the chart-widget draws a value. The arguments to the function indicate which chart item and object it is drawing, and which type of value. The function should return a number to display (or an item ID; see below), or else nil if that type of value should not be drawn at all.

Generally when using a chart-value-returner you should also specify the chart-items-max-index property of the chart-widget, and maybe also the chart-items-min-index property, to tell the chart the range of item indices that it should pass to the function. And if the chart contains more than one object, then you should also set up the chart-objects property to tell the chart the range of object indices 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 chart-widget class for an example of a chart-value-returner function, or the chart-widget tutorial (in cg-chart-widget.htm for further examples.

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

Arguments: chart-widget value-type item-index object-index object-id

These arguments are:

• chart-widget is the chart being drawn.
• value-type is the type of value that is being drawn. This will be one of the following keywords:
  • :id: the arbitrary ID to use for a chart item.
  • :value: the "main" value of a chart item and object pair.
  • :from-value: an optional starting value for a bar in a bar graph.
  • :high-value: an optional value that's normally greater than the main value.
  • :low-value: an optional value that's normally less than the main value.
  • :icon-size: an optional size for a built-in icon drawn on a line graph.

  If value-type is :id, then the function should return an arbitrary value to use as the ID of the chart item, or else nil to default the ID to the item's zero-based index. This ID may then get passed to the item-axis' on-print-major-label or on-print-minor-label function to produce the string that is displayed on the item-axis tic mark for this chart item.

  If value-type is anything other than :id, then either a number should be returned to display the specified type of value, or nil should be returned to not display that type of value.

  (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 chart-widget. That will prevent the chart-value-returner function from ever being called for that type of value.)

• item-index is the zero-based index of the chart item being drawn. One exception is that when value-type is :id, the object-index and object-id arguments may be nil.
• 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 chart-widget to specify object IDs; otherwise an object-id will default to the object-index.

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.