chart-objects

Arguments: chart-widget

Returns the value of the chart-objects property of a chart-widget. The value may be set at creation time by passing the :chart-objects initarg, or any time later by calling (setf chart-objects).

chart-objects provides a description of the objects that are displayed in a chart-widget. This consists mainly of an object-id for each object, which may be used to determine the label that is shown for the object in the chart's legend (see on-print-chart-object), and which may also be passed to the chart's chart-value-returner function to identify the object.

This description can also indicate that some chart objects should be associated with a secondary value axis that can display a different range of values than the primary value axis.

A "chart object" is represented by one of the lines of a multi-line line graph, or by one of the segments in each bar of a stacked bar graph, or by one bar in each group of non-stacked bars for a chart item. If a chart displays only a single object, then there is usually no reason to specify the chart-objects property.

The value is a sequence (a vector or list) where each element represents one chart object. The first element of the list is for the chart object whose index is 0, the second element for index 1, and so on. The element for each object is a property list of keywords and values. Currently the only allowed keys are :id for an object's ID and :value-axis for which value axis is used for the object. The default value is nil.

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). If nil or unspecified, an object ID will default to the zero-based index of the object. If the on-print-chart-object function displays a meaningful string in the legend from an object index, then there may be no need to specify object ID's here.

The value axis of an object should be either 1 for the primary value axis or 2 for the secondary value axis. If nil or unspecified, the value axis defaults to 1, so this value need be specified only for an object that uses the secondary value axis. The secondary value axis is drawn only when one or more chart objects explicitly specify it here.

Here is a sample chart-objects value that could be used for a chart that displays values for two people names Doris and Tal using the scale of the primary value axis, plus temperature values using the different scale of a secondary axis.

#((:id :doris) (:id :tal)
  (:id :temperature :value-axis 2))

The chart-legend of the chart-widget could have an on-print-chart-object function like the following, to create a string for the legend from each object ID:

(lambda (object-id)
 (format nil "~:(~a~) (~a axis)"
   object-id
   (case object-id
     (:temperature "right")
     (t "left"))))

See chart-widget and also cg-chart-widget.htm.

Copyright (c) 1998-2008, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page is new in the 8.1 release.
Created 2007.4.30.