axis

[Function]
  `(``axis` prototype {keyword value}*`)`

Returns a new axis for controlling the horizontal or vertical dimension of a plotter display according to its prototype and keyword arguments. Prototype is the keyword name of an axis prototype: a preallocated instance of `axis` or `log-axis` that serves as a template for instantiating new axes with similar characteristics. Plotter defines a few prototypes to cover the most common display configurations (Table 1); the defaxis macro can be used to create new axis prototypes.

Table 1. Predefined axis prototypes and their default characteristics.

prototype | minimum | maximum | increment | ticks-per-increment | labeler
--- | --- | --- | --- | --- | ---
`:normalized` | 0 | 1 | 1/4 | 5 | "~,2F"
`:percentage` | 0 | 100 | 25 | 5 | func 1
`:seconds` | 0 |  | 1 | 4 | "~,2F"
`:milliseconds` | 0 |  | 1000 | 4 | func
`:keynum` | 0 | 132 | 12 | 12 | func
`:frequency` | 0 | 22050 |  | 1 | "~,2F"
`:hertz`2 | 8.176 | 16744.035 | 2 | 12 | "~,2F"
`nil`3 | 0 |  |  | 1 | "~,1F"

1 Where func is (lambda (n) (prin1-to-string (floor n))).
2 The `:hertz` prototype is an instance of the log-axis class and treats its increment as the logarithmic base for its display.
3 The prototype `nil` provides defaults for axes created without a prototype.

Following the prototype name comes zero or more keyword initializations as appropriate for the class of the new axis. These initializations override any default value that the axis would otherwise receive from prototype. See the documentation on axis and log-axis for a discussion of available keyword arguments.

#### Examples:

Example 1. Creating customized axes for a plotter display.

    ;; create a percentage axis with % sign in labels.
    (axis :percentage :labeler "~D%")

    ;;; display 30 seconds with ticks every half second.
    (axis :seconds :maximum 30 :ticks-per-increment 2)

Example 2. How to redefine slots of an existing prototype.

    ;;; reset ticks-per-increment in the :normalized prototype.
    (setf (slot-value (find-prototype ':normalized)
                      'ticks-per-increment)
          5)

#### See also:

- `defaxis` [Macro]
- Plotter [Topic]