Advanced Program Output Facilities

The advanced Showcase facilities for program output are divided into three areas:

o Advanced Presentation Output Facilities

o Redisplay Facilities

o Facilities for Writing Formatted Output Macros 6.2.1 Advanced Presentation Output Facilities

Several macros, listed below, are provided for doing advanced presentation output:

Advanced Presentation Output Facilities

dw:with-output-to-presentation-recording-string dw:with-replayable-output

dw:with-resortable-output

The first, dw:with-output-to-recording-string, is the presentation-system equivalent of the Common Lisp macro with-output-to-string. It works similarly, but you can subsequently output the string as a presentation, not just a string.

dw:with-replayable-output and dw:with-resortable-output are closely related, the latter being a special case of the former. dw:with-replayable-output lets you present all of the output generated in the body of the macro as a single presentation. This presentation is "replayable"; that is, it can be input as a whole, internally re-arranged in some fashion, and presented again as the same object.

dw:with-resortable-output takes a sequence and a sorting predicate, and

constructs a dw:with-replayable-output macro to implement the sorting function.

Users can click on the presented sequence and have it redisplayed in a different order.

To see an example of this, run the Show Processes command in a Lisp Listener.

With the mouse cursor somewhere over the output display, press the SUPER and SHI FT keys and notice that the entire display is enclosed in a single box,

indicating that it is a single presentation.

The top mouse documentation line informs you that the Edit viewspecs handler is available on s-sh-~louse-M. Invoke the handler and a menu appears indicating what your choices are for sorting the displayed processes. Select one and watch the resort.

The following example is a function for presenting a resortable display of network servers. It is implemented similarly to the Show Processes command.

(defun format-servers (&optional (sort-by :none)) (fresh-line)

(dw:with-resortable-output

«servers sort-by :copy-of neti:*servers*) (: none #' ignore)

(:protocol (lambda (s-1 s-2) (string< .

(string (neti:server-protocol-name s-1)) (string (neti:server-protocol-name s-2))))) (:medium (lambda (s-1 s-2)

(string<

(string (neti:server-medium-type s-1)) (string (neti:server-medium-type s-2))))) (:arguments (lambda (s-1 s-2)

o

« (neti:server-number-of-arguments s-1) (neti:server-number-of-arguments s-2))))) (formatting-table ()

(formatting-column-headings () (with-character-face (:italic)

(with-underlining () (formatting-cell ()

(write-string "protocol")) (formatting-cell ()

(write-string "medium")) (formatting-cell ()

(write-string "no. of arguments"))))) (loop for server in servers do

(formatting-row () (formatting-cell ()

(format t "-a"

(neti:server-protocol-name server))) (formatting-cell ()

(format t "-a"

(neti:server-medium-type server))) (formatting-cell (*standard-output* :align :right)

(format t "-a"

(neti:server-number-of-arguments server))))))))

6.2.2 Redisplay Facilities

A set of inter-related facilities is provided for creating redisplayable output and doing incremental redisplay. The facilities are listed in the following table:

Redisplay Facilities

dw:redisplayable-present dw:redisplayable-format

dw:independently-redisplayable-format dw:with-redisplayable-output

dw:redisplayer dw:do-redisplay

Redisplayable output is similar to ordinary output in the actual display; it differs in that, in addition to being output to a window for display, the output value is also stored in an output cache uniquely identified with that display. When the window is redisplayed, the new output value is first compared to the cached value and, if different, the cache is updated with the new value for display. This has efficiency advantages compared with non-cached output.

Incremental redisplay refers to the redisplay of individual pieces of the output to a window, rather than redisplaying the window as a whole. It works in the manner described above, except that each redisplayed piece of the window output is

associated with its own output cache.

The first four facilities listed in the redisplay category are for creating

redisplayable output. dw:redisplayable-present is used like present but creates a redisplayable presentation. Similarly, dw:redisplayable-format works as format does, but generates redisplayable output. dw:independently-redisplayable-format is like the previous function, except that each argument in the format-control string gets cached separately; hence its usefulness for incremental redisplay.

Finally, the macro dw:with-redisplayable-output lets you make any output-producing code produce redisplayable output.

How you do redisplay once you have functions producing redisplayable output depends on whether you are taking advantage of dw:define-program-framework.

If you are, then making a program pane use your redisplay function is simply a matter of supplying that function via the :redisplay-function keyword. If, additionally, incremental redisplay is what you want, then specify so with the :incremental-redisplay keyword.

If you are doing redisplay outside of dw:define-program-framework, then you need to create a redisplay object that you can pass to dw:do-redisplay, which, as its name says, does the redisplay. Creating a redisplay object is the job of dw:redisplayer; use this macro to enclose your redisplay function.

For examples showing the coordinated use of these facilities for incremental redisplay, see the file sys: exampl es; i ncremental-redi spl ay. 1 i sp.

6.2.3 Facilities for Writing Formatted Output Macros Facilities for Writing Formatted Output Macros

dw:continuation-output-size

dw:named-value-snapshot-continuation

The two facilities listed above help you write your own output formatting macros.

Given a continuation (usually a closure) and a stream,

dw:continuation-output-size tells you how much room, in spaces or pixels, the continuation will require on the stream. This is useful, for example, for making windows no larger than necessary to accommodate formatted displays. The reference documentation for this facility includes an example,: See the function dw:continuation-output-size, page 209.

dw:named-value-snapshot-continuation is a macro that makes separate bindings for free variables referenced in its body; that is, it "snapshots" the free variables at the time the closure is constructed. This provides lexical separation between variables in the inner loops of a formatting function and variables with the same names in the outer loops. The reference documentation for

dw:named-value-snapshot-continuation contains additional details on when and how to use this facility, including examples: See the macro

dw:named-value-snapshot-continuation, page 252.