(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:

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

  • A bar chart is defined by a list of bar groups.

  • Each bar group consists of a list of bars and an optional label.

  • Each bar consists of a list of values and optionally a label and a color.

  • Each value of a bar matches a bar segment (via the position in the list).

  • A list of bar segments is provided when a bar chart is being drawn. Each bar segment consists of a label, a bar color, and optionally, a text color (for the value shown in the bar).

  • A legend shows the provided bar segments and the color used to highlight them in the bar chart.

  • A legend configuration specifies how the legend is layed out (see the various parameters in the diagram above)

  • A bar chart configuration specifies how the bar chart overall is being drawn. This includes all fonts, offsets, padding values, etc. that are shown in the diagram above.

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 ..._)

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.

  • font: Font used for all text in a legend (Helvetica 10).

  • stroke-width: Width of a stroke for drawing the bounding box of the legend (1.0).

  • horizontal-offset: Horizontal offset from chart bounds (negative values are interpreted as offsets from the right bound) (70).

  • vertical-offset: Vertical offset from chart bounds (negative values are interpreted as offsets from the bottom bound) (10).

  • sample-area-width: Width of the sample area (17).

  • sample-length: Heigh and width of color sample boxes for the various segments (10).

  • line-pad: Padding between segment lines (3).

  • entry-pad: Top/bottom and left/right padding around segment descriptions including the sample area (6).

(legend-config? _obj_)

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

(legend-font _lconf_)

Returns the font defined by the given legend configuration lconf.

(legend-font-set! _lconf font_)

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

(legend-stroke-width _lconf_)

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

(legend-stroke-width-set! _lconf val_)

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

(legend-horizontal-offset _lconf_)

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

(legend-horizontal-offset-set! _lconf val_)

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

(legend-vertical-offset _lconf_)

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

(legend-vertical-offset-set! _lconf val_)

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

(legend-sample-area-width _lconf_)

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

(legend-sample-area-width-set! _lconf val_)

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

(legend-sample-length _lconf_)

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

(legend-sample-length-set! _lconf val_)

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

(legend-line-pad _lconf_)

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

(legend-line-pad-set! _lconf val_)

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

(legend-entry-pad _lconf_)

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

(legend-entry-pad-set! _lconf val_)

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 ..._)

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.

  • size: The rectangle in which the chart is drawn (495 x 200)

  • color: Color of text, axis, etc. (black)

  • bg-color: Color of legend background (white)

  • value-font: Font for displaying values (Helvetica 10)

  • bar-font: Font for displaying values on top of bars (Helvetica 11)

  • label-font: Font for displaying bar labels (Helvetica 12)

  • group-font: Font for displaying bar group labels (Helvetica-Bold 12)

  • descr-font: Font for describing the axis (Helvetica-LightOblique 10)

  • stroke-width: Width of a stroke in pixels (1.0)

  • top-pad: Top padding in pixels (20)

  • bottom-pad: Padding below the x axis (5)

  • right-pad: Right-side padding (15)

  • left-pad: Padding left to the y axis (10)

  • bar-gap: Space between two bar groups (20)

  • group-gap: Space between two bars within a group (5)

  • vlabel-width: Width of labels on y axis (50)

  • vindicator-width: Width of y label indicator lines (10)

  • vline-lengths: List of alternating dash/space lengths; can be set to #f to disable the line ((1 2))

  • value-pad: Padding between bar and displayed value (1)

  • blabel-height: Height of bar labels (14)

  • glabel-height: Height of group labels (30)

  • xaxis-overhead: Overhead on x axis (20)

  • yaxis-overhead: Overhead on y axis (20)

(bar-chart-config? _obj_)

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

(bar-chart-size _bconf_)

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

(bar-chart-size-set! _bconf size_)

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

(bar-chart-value-font _bconf_)

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

(bar-chart-value-font-set! _bconf font_)

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

(bar-chart-bar-font _bconf_)

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

(bar-chart-bar-font-set! _bconf font_)

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

(bar-chart-label-font _bconf_)

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

(bar-chart-label-font-set! _bconf font_)

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

(bar-chart-group-font _bconf_)

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

(bar-chart-group-font-set! _bconf font_)

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

(bar-chart-descr-font _bconf_)

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

(bar-chart-descr-font-set! _bconf font_)

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

(bar-chart-stroke-width _bconf_)

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

(bar-chart-stroke-width-set! _bconf val_)

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

(bar-chart-top-pad _bconf_)

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

(bar-chart-top-pad-set! _bconf val_)

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

(bar-chart-bottom-pad _bconf_)

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

(bar-chart-bottom-pad-set! _bconf val_)

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

(bar-chart-right-pad _bconf_)

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

(bar-chart-right-pad-set! _bconf val_)

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

(bar-chart-left-pad _bconf_)

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

(bar-chart-left-pad-set! _bconf val_)

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

(bar-chart-bar-gap _bconf_)

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

(bar-chart-bar-gap-set! _bconf val_)

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

(bar-chart-group-gap _bconf_)

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

(bar-chart-group-gap-set! _bconf val_)

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

(bar-chart-vlabel-width _bconf_)

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

(bar-chart-vlabel-width-set! _bconf val_)

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

(bar-chart-vindicator-width _bconf_)

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

(bar-chart-vindicator-width-set! _bconf val_)

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

(bar-chart-vline-lengths _bconf_)

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_)

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_)

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

(bar-chart-value-pad-set! _bconf val_)

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

(bar-chart-blabel-height _bconf_)

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_)

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_)

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

(bar-chart-glabel-height-set! _bconf val_)

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

(bar-chart-xaxis-overhead _bconf_)

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_)

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_)

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_)

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_)

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_)

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

(bar _label value ...) **(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_)

Returns the label of the given bar object bar.

(bar-color _bar_)

Returns the color of the given bar object bar.

(bar-values _bar_)

Returns the values of the given bar object bar.

(bar-group? _obj_)

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

(bar-group _label bar ..._)

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

(bar-group-label _group_)

Returns the label of the given bar group group.

(bar-group-bars _group_)

Returns the bars of the given bar group group.

(bar-segment _label col) **(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) **(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.

Last updated