All Manuals > CAPI User Guide and Reference Manual > 23 LW-GT Reference Entries

NextPrevUpTopContentsIndex

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


CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017

NextPrevUpTopContentsIndex