LispKit Draw Chart Bar

Library (lispkit draw chart bar) supports drawing bar charts based on a data-driven API in which bar charts are being described declaratively. A drawing function is then able to draw a bar chart into a given drawing as defined by library (lispkit draw).

Bar Chart Model

The following diagram shows a generic bar chart model including the various elements that make up bar charts and parameters that can be configured:

Bar Chart Model and Parameters

The bar chart model on which library (lispkit draw chart bar) is based on consists of the following components:

Legend Configurations

A legend configuration is a record encapsulating all parameters needed for drawing a legend in a bar chart. Legend configurations are mutable objects that are created via procedure make-legend-config. For every parameter, there is an accessor and a setter procedure.

(make-legend-config key val …)     [procedure]

Creates a new legend configuration object from the provided keyword/value pairs. The following keyword arguments are supported. The default value is provided in parenthesis.

(make-legend-config
  'font: (font "Helvetica" 7)
  'stroke-width: 0.4
  'entry-pad: 5
  'sample-area-width: 16
  'sample-length: 8
  'horizontal-offset: 50)

(legend-config? obj)     [procedure]

Returns #t if obj is a legend configuration object, #f otherwise.

(legend-font lconf)     [procedure]

Returns the font defined by the given legend configuration lconf.

(legend-font-set! lconf font)     [procedure]

Sets the font for the given legend configuration lconf to font.

(legend-stroke-width lconf)     [procedure]

Returns the stroke width defined by the given legend configuration lconf.

(legend-stroke-width-set! lconf val)     [procedure]

Sets the stroke width for the given legend configuration lconf to val.

(legend-horizontal-offset lconf)     [procedure]

Returns the horizontal offset defined by the given legend configuration lconf.

(legend-horizontal-offset-set! lconf val)     [procedure]

Sets the horizontal offset for the given legend configuration lconf to val.

(legend-vertical-offset lconf)     [procedure]

Returns the vertical offset defined by the given legend configuration lconf.

(legend-vertical-offset-set! lconf val)     [procedure]

Sets the horizontal offset for the given legend configuration lconf to val.

(legend-sample-area-width lconf)     [procedure]

Returns the sample area width defined by the given legend configuration lconf.

(legend-sample-area-width-set! lconf val)     [procedure]

Sets the sample area width for the given legend configuration lconf to val.

(legend-sample-length lconf)     [procedure]

Returns the sample length defined by the given legend configuration lconf.

(legend-sample-length-set! lconf val)     [procedure]

Sets the sample length for the given legend configuration lconf to val.

(legend-line-pad lconf)     [procedure]

Returns the line padding defined by the given legend configuration lconf.

(legend-line-pad-set! lconf val)     [procedure]

Sets the line padding for the given legend configuration lconf to val.

(legend-entry-pad lconf)     [procedure]

Returns the entry padding defined by the given legend configuration lconf.

(legend-entry-pad-set! lconf val)     [procedure]

Sets the entry padding for the given legend configuration lconf to val.

Bar Chart Configurations

A bar chart configuration is a record encapsulating all parameters needed for drawing a bar chart (excluding the bar chart legend). Bar chart configurations are mutable objects that are created via procedure make-bar-chart-config. For every parameter of the configuration, there is an accessor and a setter procedure.

(make-bar-chart-config key val …)     [procedure]

Creates a new bar chart configuration object from the provided keyword/value pairs. The following keyword arguments are supported. The default value is provided in parenthesis.

(make-bar-chart-config
  'size: (size 495 200)
  'color: (color 0.9 0.9 0.9)
  'value-font: (font "Helvetica" 8.5)
  'bar-font: (font "Helvetica" 8)
  'label-font: (font "Helvetica" 9)
  'top-pad: 5
  'left-pad: 10
  'right-pad: 5
  'bar-gap: 10
  'vlabel-width: 34
  'glabel-height: 5
  'blabel-height: 20)

(bar-chart-config? obj)     [procedure]

Returns #t if obj is a bar chart configuration, otherwise #f is returned.

(bar-chart-size bconf)     [procedure]

Returns the size defined by the given bar chart configuration bconf.

(bar-chart-size-set! bconf size)     [procedure]

Sets the size for the given bar chart configuration bconf to size. size is a size object.

(bar-chart-value-font bconf)     [procedure]

Returns the value font defined by the given bar chart configuration bconf.

(bar-chart-value-font-set! bconf font)     [procedure]

Sets the value font for the given bar chart configuration bconf to font.

(bar-chart-bar-font bconf)     [procedure]

Returns the bar font defined by the given bar chart configuration bconf.

(bar-chart-bar-font-set! bconf font)     [procedure]

Sets the bar font for the given bar chart configuration bconf to font.

(bar-chart-label-font bconf)     [procedure]

Returns the label font defined by the given bar chart configuration bconf.

(bar-chart-label-font-set! bconf font)     [procedure]

Sets the label font for the given bar chart configuration bconf to font.

(bar-chart-group-font bconf)     [procedure]

Returns the group font defined by the given bar chart configuration bconf.

(bar-chart-group-font-set! bconf font)     [procedure]

Sets the group font for the given bar chart configuration bconf to font.

(bar-chart-descr-font bconf)     [procedure]

Returns the description font defined by the given bar chart configuration bconf.

(bar-chart-descr-font-set! bconf font)     [procedure]

Sets the description font for the given bar chart configuration bconf to font.

(bar-chart-stroke-width bconf)     [procedure]

Returns the stroke width defined by the given bar chart configuration bconf.

(bar-chart-stroke-width-set! bconf val)     [procedure]

Sets the stroke width for the given bar chart configuration bconf to val.

(bar-chart-top-pad bconf)     [procedure]

Returns the top padding defined by the given bar chart configuration bconf.

(bar-chart-top-pad-set! bconf val)     [procedure]

Sets the top padding for the given bar chart configuration bconf to val.

(bar-chart-bottom-pad bconf)     [procedure]

Returns the bottom padding defined by the given bar chart configuration bconf.

(bar-chart-bottom-pad-set! bconf val)     [procedure]

Sets the bottom padding for the given bar chart configuration bconf to val.

(bar-chart-right-pad bconf)     [procedure]

Returns the right padding defined by the given bar chart configuration bconf.

(bar-chart-right-pad-set! bconf val)     [procedure]

Sets the right padding for the given bar chart configuration bconf to val.

(bar-chart-left-pad bconf)     [procedure]

Returns the left padding defined by the given bar chart configuration bconf.

(bar-chart-left-pad-set! bconf val)     [procedure]

Sets the left padding for the given bar chart configuration bconf to val.

(bar-chart-bar-gap bconf)     [procedure]

Returns the bar gap defined by the given bar chart configuration bconf.

(bar-chart-bar-gap-set! bconf val)     [procedure]

Sets the bar gap for the given bar chart configuration bconf to val.

(bar-chart-group-gap bconf)     [procedure]

Returns the group gap defined by the given bar chart configuration bconf.

(bar-chart-group-gap-set! bconf val)     [procedure]

Sets the group gap for the given bar chart configuration bconf to val.

(bar-chart-vlabel-width bconf)     [procedure]

Returns the vertical label width defined by the given bar chart configuration bconf.

(bar-chart-vlabel-width-set! bconf val)     [procedure]

Sets the vertical label width for the given bar chart configuration bconf to val.

(bar-chart-vindicator-width bconf)     [procedure]

Returns the vertical value indicator width defined by the given bar chart configuration bconf.

(bar-chart-vindicator-width-set! bconf val)     [procedure]

Sets the vertical value indicator width for the given bar chart configuration bconf to val.

(bar-chart-vline-lengths bconf)     [procedure]

Returns a list of alternating dash/space lengths defined by the given bar chart configuration bconf. If #f is returned, no horizontal value lines are drawn.

(bar-chart-vline-lengths-set! bconf val)     [procedure]

Sets the list of alternating dash/space lengths for the given bar chart configuration bconf to val. val may be set to #f to disable drawing horizontal value lines.

(bar-chart-value-pad bconf)     [procedure]

Returns the value padding defined by the given bar chart configuration bconf.

(bar-chart-value-pad-set! bconf val)     [procedure]

Sets the value padding for the given bar chart configuration bconf to val.

(bar-chart-blabel-height bconf)     [procedure]

Returns the value padding, i.e. the space between bar and displayed value, defined by the given bar chart configuration bconf.

(bar-chart-blabel-height-set! bconf val)     [procedure]

Sets the value padding, i.e. the space between bar and displayed value, for the given bar chart configuration bconf to val.

(bar-chart-glabel-height bconf)     [procedure]

Returns the group label height defined by the given bar chart configuration bconf.

(bar-chart-glabel-height-set! bconf val)     [procedure]

Sets the group label height for the given bar chart configuration bconf to val.

(bar-chart-xaxis-overhead bconf)     [procedure]

Returns the overhead on the x axis of the coordinate system defined by the given bar chart configuration bconf.

(bar-chart-xaxis-overhead-set! bconf val)     [procedure]

Sets the overhead on the x axis of the coordinate system for the given bar chart configuration bconf to val.

(bar-chart-yaxis-overhead bconf)     [procedure]

Returns the overhead on the y axis of the coordinate system defined by the given bar chart configuration bconf.

(bar-chart-yaxis-overhead-set! bconf val)     [procedure]

Sets the overhead on the y axis of the coordinate system for the given bar chart configuration bconf to val.

Constructing Bar Charts

(bar-spec? obj)     [procedure]

Returns #t if obj is a bar diagram specification, #f otherwise. A bar diagram specification is a list of bars and bar groups.

(bar? obj)     [procedure]

Returns #t if obj is a bar object, otherwise #f is returned.

(bar label value …)     [procedure]
(bar label color value …)

Creates a new bar object. A bar without bar segments consists of a single value and an optional label string (#f disables the label) and color. A segmented bar has a value for all segments (i.e. all bars of a bar diagram should have the same number of segments). A segment is disabled by setting its value to 0.

(bar-label bar)     [procedure]

Returns the label of the given bar object bar.

(bar-color bar)     [procedure]

Returns the color of the given bar object bar.

(bar-values bar)     [procedure]

Returns the values of the given bar object bar.

(bar-group? obj)     [procedure]

Returns #t if obj is a bar group object, otherwise #f is returned.

(bar-group label bar …)     [procedure]

Creates a new bar group from the bars bar … with string label as label.

(bar-group-label group)     [procedure]

Returns the label of the given bar group group.

(bar-group-bars group)     [procedure]

Returns the bars of the given bar group group.

(bar-segment label col)     [procedure]
(bar-segment label col textcol)

Creates a bar segment represented by label string label and segment color col. Text color textcol is optional (and might be #f).

Drawing Bar Charts

(draw-bar-chart bars col ystep ydescr xdescr loc config legend)     [procedure]
(draw-bar-chart bars col ystep ydescr xdescr loc config legend drawing)

Draws the bar diagram bars with col as the default bar color into the drawing drawing. ystep defines the increment between values on the y axis. ydescr defines the label of the y axis. xdescr defines the label of the x axis. loc is a point at which the bar diagram is drawn with the bar diagram configuration config. If a legend should be drawn, a legend configuration needs to be provided as parameter legend.

(draw-bar-chart
  (list
    (bar "Jan" 0) (bar "Feb" 2) (bar "Mar" 6)
    (bar "Apr" 9) (bar "May" 14) (bar "Jun" 16)
    (bar "Jul" 19) (bar "Aug" 18) (bar "Sep" 15)
    (bar "Oct" 11) (bar "Nov" 5) (bar "Dec" 2))
  gray 5
  "Temperature [C°]" "Month"
  (point 50 105)
  (make-bar-chart-config
    'size: (size 495 200))
  #f)