# (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).
```scheme
(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**\_**)**
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)
```scheme
(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**\_**)**
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 ...*****)*** \
\&#xNAN;*\*\*(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*****)*** \
\&#xNAN;*\*\*(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*****)*** \
\&#xNAN;*\*\*(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*.
```scheme
(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)
```
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).
```scheme
(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**\_**)**