CLIM 2 Specification — 19 Bordered Output

19 Bordered Output

CLIM provides a mechanism for surrounding arbitrary output with some kind of a border. The programmer annotates some output-generating code with an advisory macro that describes the type of border to be drawn. The following code produces the output shown in Figure 19.1. [annotate]

For example, the following produces three pieces of output, surrounded by a rectangular, highlighted with a dropshadow, and underlined, respectively. [annotate]

(defun border-test (stream)
  (fresh-line stream)
  (surrounding-output-with-border (stream :shape :rectangle)
    (format stream "This is some output with a rectangular border"))
  (terpri stream) (terpri stream)
  (surrounding-output-with-border (stream :shape :drop-shadow)
    (format stream "This has a drop-shadow under it"))
  (terpri stream) (terpri stream)
  (surrounding-output-with-border (stream :shape :underline)
    (format stream "And this output is underlined")))

Figure 19.1: Examples of bordered output.

surrounding-output-with-border (&optional stream &rest drawing-options &key shape (move-cursor t)) &body body [Macro]

Binds the local environment in such a way the output of body will be surrounded by a border of the specified shape. Every implementation must support the shapes :rectangle (the default), :oval, :drop-shadow, and :underline. :rectangle draws a rectangle around the bounding rectangle of the output. :oval draws an oval around the bounding rectangle of the output. :drop-shadow draws a "drop shadow" around the lower right edge of the bounding rectangle of the output. :underline draws a thin line along the baseline of all of the text in the output, but does not draw anything underneath non-textual output. drawing-options is a list of drawing options that are passed to the function that draws the border. [annotate]

If the boolean move-cursor is true (the default), then the text cursor will be moved so that it immediately follows the lower right corner of the bordered output. [annotate]

stream is an output recording stream to which output will be done. The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-output* is used. body may have zero or more declarations as its first forms. [annotate]

There are several strategies for implementing borders. One strategy is to create a "border output record" that contains the output records produced by the output of body, plus one or more output records that represent the border. Another strategy might be to arrange to call the border drawer at the approriate times without explicitly recording it. [annotate]

[annotate]

define-border-type shape arglist &body body [Macro]

Defines a new kind of border named shape. arglist must be a subset of the "canonical" arglist below (using string-equal to do the comparison):
(&key stream record left top right bottom)
[annotate]

Note: I believe it should read "superset of the 'canonical' arglist". [edit]-- Gilbert Baumann 2003-06-08 04:05Z

arglist may include other keyword arguments that serve as the drawing options. [annotate]

body is the code that actually draws the border. It has lexical access to stream, record, left, top, right, and bottom, which are respectively, the stream being drawn on, the output record being surrounded, and the coordinates of the left, top, right, and bottom edges of the bounding rectangle of the record. body may have zero or more declarations as its first forms. [annotate]

[annotate]