Function

Summary

Generate a grid of lines, to be used for drawing graphs of functions or bar charts.

Package

lw-gt

Signature

generate-grid-lines (&key x-offset y-offset x-spacing y-spacing horizontal-count vertical-count width height thickness major-x-step major-y-step vertical-thickness minor-thickness minor-vertical-thickness left-thickness right-thickness top-thickness bottom-thickness color vertical-color minor-color minor-vertical-color left-color right-color top-color bottom-color ) => list

Arguments

horizontal-count , vertical-count

nil or positive integers.

width , height

nil or positive real numbers.

x-offset , y-offset

Non-negative real numbers.

x-spacing , y-spacing

Positive real numbers.

major-x-step , major-y-step

nil or integers.

thickness , vertical-thickness , minor-thickness , minor-vertical-thickness , left-thickness , right-thickness , top-thickness , bottom-thickness

Positive real numbers. Each defaults to 1.

color , vertical-color , minor , minor-vertical-color , left-color , right-color , top-color , bottom-color

Colors in the standard definition. Each defaults to :gray.

Values

list

A list of drawing-objects.

Description

The function generate-grid-lines generates a grid of lines, to be used for drawing graphs of functions or bar charts.

generate-grid-lines returns a list of drawing-objects which when drawn display a grid of horizontal and vertical lines, according to the supplied specification.

The grid is made of vertical lines spaced regularly in the horizontal dimension, and horizontal lines spaced regularly in the vertical dimension. The specification of the graph is conceptual starting from 0 and increasing in both dimensions. This does not affect what values the graph shows, because these are defined by the labels which are produced separately (typically by generate-labels).

x-offset / y-offset specify the offset of the origin of the graph, which means the position of the first vertical/horizontal line respectively, and where the start point of the horizontal/vertical line respectively. The default value of both x-offset and y-offset is 0.

x-spacing and y-spacing specify the gaps in the horizontal and vertical dimensions respectively (that is, the distance between vertical/horizontal lines). The default value of both x-spacing and y-spacing is 1.

horizontal-count and vertical-count specify the numbers of lines in the horizontal and vertical dimensions respectively (that is, the number of vertical / horizontal lines).

The length of the horizontal (vertical) lines is computed by the product x-spacing * horizontal-count ( y-spacing * vertical-count ).

width and height are used only when horizontal-count / vertical-count respectively is nil, to compute the value of the horizontal-count / vertical-count , by truncating the width / height by the x-spacing / y-spacing .

major-x-step and major-y-step specify that each major-x-step 'th (horizontally) or major-y-step 'th (vertically) line is "major", which means drawn with (potentially) different thickness and color (see below).

thickness and the other *-thickness arguments specify the thickness of the lines. color and the other *-color arguments specify the color of the lines. All the *-thickness variables default, directly or indirectly, to the value of thickness , and the *-color arguments default to the value of color . Default values for *-thickness and *-color arguments to generate-grid-lines gives the details:

Default values for *-thickness and *-color arguments to generate-grid-lines

Argument	Default value
thickness	1
vertical-thickness	thickness
major-thickness	thickness
major-vertical-thickness	major-thickness
top-thickness	major-thickness
bottom-thickness	major-thickness
left-thickness	major-vertical-thickness
right-thickness	major-vertical-thickness
color	:gray
vertical-color	color
major-color	color
major-vertical-color	major-color
top-color	major-color
bottom-color	major-color
left-color	major-vertical-color
right-color	major-vertical-color

The top-* , bottom-* , left-* , right-* variables specify the values for the outer lines of the grid. The major-* variables specify the values for the major lines, the other variables specify the values for the ordinary lines. The vertical-* variables specify the values for the vertical lines, the other variables for the horizontal.

Notes

1. To actually be displayed, the result of generate-grid-lines must be in a hierarchy which is rooted in an objects-displayer or a pinboard-objects-displayer.
2. The result of generate-grid-lines is a list of drawing-object, so it is a valid "drawing-object-spec". It will be typically be grouped together with some other "drawing-object-specs", for example labels for the graph, by simply listing them, and then positioned and fitted by passing it to position-object or fit-object or position-and-fit-object.
3. The function generate-labels is intended to be useful to generate the labels.
4. x-offset and y-offset are useful for leaving space for the labels.
5. The units of the numbers that in the location of the lines are abstract, not pixels, and will typically correspond to the units of the data that the graph displays. They will be in pixels only if there is no fitting around the graph. For example, if you make the grid from 0 to 9 in the x dimension, and then fit to natural-width 10, that is you pass the result, or an object that contains the result in its hierarchy, to fit-object with the natural-width 10, the graph will take 90% of the width of the geometry-drawing-object that fit-object generated, whatever that is.

See also

drawing-object
generate-graph-from-graph-spec
Higher level - drawing graphs and bar charts