set-plot-value

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-plot-value

Arguments: plot-widget &key value-index object-index object-id x y x-low x-high y-low y-high icon-size update-now &

Establishes one or more of the values to display on a plot-widget for one of the points of one of the chart objects that are represented in a plot-widget. The return value is not defined.

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

plot-widget is the widget to modify.

The keyword arguments

The first group of keyword arguments specify which value-index/object pair to modify.

value-index is the zero-based index of the plot value to modify, or the symbol :new to add a plot value to the existing values for the specified object, or the symbol :last to modify the most-recently-added plot value for the object (that is, the one with the highest index), or else nil to default to :new. If the plot is empty and value-index is :last, then it behaves like :new. To simply add new values, you can avoid passing this argument.
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. If there is only one chart object, then there is probably no need to pass this argument or object-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 value-index/object pair. Any subset of these arguments may be passed, though the auxilliary values will have no effect until if and when the x and y values are both specified for the same value-index/object pair. An x, y, x-low, x-high, y-low, or y-high value may be either a real number to add a value to the plot or modify an existing value, or else nil to remove a value from the plot.

x is the X coordinate of a point to be plotted. This is always measured along a horizontal axis.
y is the Y coordinate of a point to be plotted. This is always measured along a vertical axis.
x-low is an additional value that is typically somewhat lower than the x value. It is drawn according to the high-low-value-style of the plot-view, and is typically used to represent an error range.
x-high 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 plot-view, and is typically used to represent an error range.
y-low and y-high are like x-low and x-high, except that they are plotted vertically from the main plotted point rather than horizontally from it.
icon-size is the size of the icon drawn at a particular plotted point. The value should be a positive integer to be used as the "radius" of the icon, measured in pixels, or else nil to defer to the icon-sizes of the icon-drawing-view. It is used only if the draw-icons property of the plot-view is true, and only if the icon-images property uses names of the built-in icons (which are :dot, :circle, :square, :triangle, and :diamond) rather than pixmaps. For :dot, the value refers to the diameter of the dot rather than the radius, to allow more accurate dot sizes.
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 plot 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.)