| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: chart-or-plot
Returns the value of the chart-objects property of
a chart-or-plot. (Despite the word "chart" in
the symbol name, this property applies similarly to
a chart-widget
or a
plot-widget
.) The value may
be set at creation time by passing
a chart-objects initarg to make-instance, or any time later by calling
(setf
chart-objects).
The chart-objects property can
be used to specify several attributes of the objects that are
displayed in a chart-or-plot. A "chart object"
is represented by one of the lines of a multi-line line graph in a
chart-widget
, for example,
or by one of the segments in each bar of a stacked bar graph (also in
a chart-widget
), or by a
group of points that are drawn with a particular icon in a
plot-widget
. If a chart or
plot displays only a single object, then there may be no reason to
specify this chart-objects
property.
The description of each object can include attributes such as its object-id (an arbitrary identifier), a label to display in the legend, whether to associate the object with a primary or secondary value-axis, and/or whether to currently exclude the object from the chart or plot.
The chart-objects value is a sequence (a vector or list) where each element represents one chart object. The first element of the sequence is said to have an object-index of 0, the second element an object-index of 1, and so on. The element for each object is a property list of keywords and values. Here are the keys that may be used in the plist for an object:
:id
- The ID of an object may be any sort of
value, though the chart-object-id-equality-test function should be
suitable for the values used. Typically it is a
symbol. If nil
or unspecified, an object's ID
will default to the zero-based index of the object in the
chart-objects sequence. This ID value will be passed to the
chart-value-returner function
of a chart-widget
, or to
the plot-value-returner
function of a plot-widget
,
if one is used. An application can pass the ID to chart-value, set-chart-value, plot-value, or set-plot-value. Also, if
no :label
value is supplied here for an object,
then the ID value is used to derive a label string to display for the
object in the legend (typically modified by an on-print-chart-object function).
:label
- This value can be a string to
display for the object in the chart-legend of a chart or
plot. If nil
or unspecified, a label will be
derived from the object's ID. Supplying this value for every object
removes the need to write an on-print-chart-object function. If both are
supplied, then an explicit label string will
override the function.
:exclude
- If a true value is specified for
this key, then the object will currently not be drawn in the chart or
plot. Also, if the range-bottom or range-top is automatically computed for a
value-axis, then the object's data will not affect the determination
of the range. This :exclude
value will be toggled
on or off automatically if the click-to-toggle-inclusion property of the
chart-legend is true and the user clicks on the object's label in the
legend.
:value-axis
(chart-widget
only) - This value should be either
1 or 2, though 1 is the default when nil
or
unspecified. A value of 1 means that a chart object will be
associated with the primary value-axis of the chart-widget, which is
drawn either on the left side or the bottom side of the chart
(depending on the value of the chart-orientation property). A value
of 2 will associate the object with the secondary value-axis, which is
drawn either on the right side or the top side of the chart. A
secondary value-axis is drawn only when one or more chart objects
explicitly specify a value of 2 here in the chart-objects property.
When two value axes are used, they can have different ranges, which is
useful to compare two sets of values that are measured on different
scales.
:x-axis
(plot-widget
only) - This works
like :value-axis
for a chart-widget, except that it
applies to the value axes that always lie horizontally along the
bottom or top of a plot-widget. 1 indicates the lower axis while 2
indicates the upper axis.
:y-axis
(plot-widget
only) - This works like
:value-axis
for a chart-widget, except that it
applies to the value axes that always lie vertically along the left or
right side of a plot-widget. 1 indicates the left axis while 2
indicates the right axis.
If the chart-objects property is replaced with a different vector or list, then the chart-or-plot will be updated automatically to reflect the new value. But if you modify the existing vector or list, then the widget will not know that anything has changed, and so you would need to call update-chart-widget explicitly to update the display.
Here is a sample chart-objects value that might display bowling scores in a chart-widget for Doris and Hubert, overlaid with the room temperature for each bowling event. Explicit legend labels are supplied so that no on-print-chart-object function needs to be written. The bowling scores will default to being displayed along the scale of the primary value axis, while the temperatures will use the scale of a secondary value axis. Hubert will (for now) be excluded from the chart.
#((:id :doris :label "Doris") (:id :hubert :label "Hubert" :exclude t) (:id :temperature :label "Temperature" :value-axis 2))
See chart-widget
,
plot-widget
, and also
cg-chart-widget.htm.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |