(lispkit draw chart bar)

Last updated 5 months ago

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

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

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

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

Returns the font defined by the given legend configuration lconf.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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.

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

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

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

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

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

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

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

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

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

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

Constructing Bar Charts

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

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

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.

Returns the label of the given bar object bar.

Returns the color of the given bar object bar.

Returns the values of the given bar object bar.

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

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

Returns the label of the given bar group group.

Returns the bars of the given bar group group.

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

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)

Last updated 5 months ago