chart-objects

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.