generate-grid-lines

generate-grid-lines 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 vertical-thickness minor-thickness minor-vertical-thickness left-thickness right-thickness top-thickness bottom-thickness major-x-step major-y-step color vertical-color major-color major-vertical-color left-color right-color top-color bottom-color) => list

Arguments

`x-offset`⇩, `y-offset`⇩	Non-negative real numbers.
`x-spacing`⇩, `y-spacing`⇩
	Positive real numbers.
`horizontal-count`⇩, `vertical-count`⇩
	`nil` or positive integers.
`width`⇩, `height`⇩	`nil` or positive real numbers.
`thickness`⇩, `vertical-thickness`⇩, `minor-thickness`⇩, `minor-vertical-thickness`⇩, `left-thickness`⇩, `right-thickness`⇩, `top-thickness`⇩, `bottom-thickness`⇩
	Positive real numbers. Each defaults to 1.
`major-x-step`⇩, `major-y-step`⇩
	`nil` or integers.
`color`⇩, `vertical-color`⇩, `major-color`⇩, `major-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 and y-offset specify the offset of the origin of the graph, which means the position of the first horizontal and vertical line respectively, and where the other horizontal and vertical lines start. 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 the 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 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 or vertical-count respectively is nil, to compute the value of horizontal-count or vertical-count, by truncating width or height by x-spacing or 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, vertical-thickness, minor-thickness, minor-vertical-thickness, left-thickness, right-thickness, top-thickness amd bottom-thickness specify the thickness of the lines. color, vertical-color, major-color,major-vertical-color, left-color, right-color, top-color and bottom-color specify the color of the lines. The default values for these arguments are shown in Default values for *-thickness and *-color arguments to generate-grid-lines:

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

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.
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.
The function generate-labels is intended to be useful to generate the labels.
x-offset and y-offset are useful for leaving space for the labels.
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.