All Manuals > CAPI User Guide and Reference Manual > 23 LW-GT Reference Entries

generate-bar-chart Function


Generate a list of drawing-objects which display the bars of a bar chart.




generate-bar-chart values &key function start-position step-position width orientation colors title-position argument font base title-color absolute-p => bars

A list.
A function of one or two arguments, depending on argument.
The position of the first bar.
The distance between bars.
The width of a bar.
One of the keywords :rightward, :leftward, :downward and :upward.
A list of colors.
One of the keywords :middle, :top, :bottom, :right and :left, or nil.
A Lisp object.
A font specification.
The position of the "base" of each bar.
A color specification.
A boolean.
A list of drawing-objects.

The function generate-bar-chart generates a list of drawing-objects which display the bars of a bar chart.

values is a list giving the values that need displaying. There is a bar for each element in the list.

For each element in values, generate-bar-chart uses the function function to find the length of the bar and a title to add to it. If argument is non-nil, function is called with two arguments: argument and the element of values. Otherwise, function is called with one argument, the element. function must return the length of the bar, and optionally the title as a second return value. The default value of argument is nil.

If function is not supplied, the default function checks if the element is a list, and if it is returns the first element of it as the length and the second element as the title. If it is not a list it returns it and nil as the second value.

generate-bar-chart then generates a drawing-object that draws the bar, which is a rectangle with length being the result of the function and width width. The default value of width is 1.

For orientation :upward or :downward, the "length dimension" is vertical, and the "width dimension" is the horizontal, and the reverse for the other orientations. The default value of orientation is :upward.

The position of the rectangle in the "length dimension" is from base to (+ base length) for orientation :upward and :leftward, and from base to (- base length) for the other orientations. The default value of base is 0.

start-position and step-position determine the position of the center of the rectangle in the "width dimension". Hence the position of the n'th rectangle in the "width dimension" is from:

(- (+ #START-POSITION (* (1- n) #STEP-POSITION)) (/ #WIDTH 2))


(+ (+ #START-POSITION (* (1- n) #STEP-POSITION)) (/ #WIDTH 2))

The default value of start-position is 1. The default value of step-position is (* 3 width).

The color of the rectangle is taken from the items of colors in turn, starting again from the beginning when reaching the end. The default value of colors is (:red :green :blue :yellow :purple).

generate-bar-chart then also computes where the string should appear with respect to the bar, depending on title-position, generates a drawing object using make-draw-string, passing it font, absolute-p and title-color. title-position nil means the end of the bar. The default value of font is the font of the pane. absolute-p determines whether the title is drawn in absolute mode. The default value of absolute-p is t.

See also

14.1 Lower level - drawing objects and objects displayers

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:48