33.5 Progressive Picts and Slides

33.5.1 Progressive Picts

(require unstable/gui/ppict)

A progressive pict or “ppict” is a kind of pict that has an associated “pict placer,” which generally represents a position and alignment. New picts can be placed on the progressive pict by calling ppict-add, and the placer can be updated by calling ppict-go. The ppict-do form provides a compact notation for sequences of those two operations.

A #:go fragment changes the current placer. A #:set fragment replaces the current pict state altogether with a new computed pict. A #:next fragment saves a pict including only the contents emitted so far (but whose alignment takes into account picts yet to come). A #:alt fragment saves the current pict state, executes the sub-sequence that follows, saves the result (as if the sub-sequence ended with #:next), then restores the saved pict state before continuing.

The elem-exprs are interpreted by the current placer. A numeric elem-expr usually represents a spacing change, but some placers do not support them. A spacing change only affects added picts up until the next placer is installed; when a new placer is installed, the spacing is reset, usually to 0.

The ppict-do-state form tracks the current state of the pict. It is updated before a #:go or #:set fragment or before a sequence of elem-exprs. It is not updated in the middle of a chain of elem-exprs, however.

Examples:

> (define circles-down-1     (ppict-do base               #:go (grid 2 2 2 1 'ct)               10               (circle 20)               (circle 20)               30               (circle 20))) > circles-down-1 > (define circles-down-2     (ppict-do circles-down-1               (colorize (circle 20) "red")               40               (colorize (circle 20) "red"))) > (inset circles-down-2 20) ; draws outside its bounding box > (inset (clip circles-down-2) 20) > (ppict-do base             #:go (coord 0 0 'lt)             (tag-pict (circle 20) 'circA)             #:go (coord 1 1 'rb)             (tag-pict (circle 20) 'circB)             #:set (let ([p ppict-do-state])                     (pin-arrow-line 10 p                                     (find-tag p 'circA) rb-find                                     (find-tag p 'circB) lt-find))) > (let-values ([(final intermediates)                 (ppict-do* base                            #:go (coord 1/4 1/2 'cb)                            (text "shapes:")                            #:go (coord 1/2 1/2 'lb)                            #:alt [(circle 20)]                            #:alt [(rectangle 20 20)]                            (text "and more!"))])     (append intermediates (list final))) '(  )

More examples of ppict-do are scattered throughout this section.

An elem that is a real number changes the spacing for subsequent additions. A elem that is #f is discarded; it is permitted as a convenience for conditionally including sub-picts. Note that #f is not equivalent to (blank 0), since the latter will cause spacing to be added around it.

Additions are aligned according to align, a symbol whose name consists of a horizontal alignment character followed by a vertical alignment character. For example, if align is 'lt, the pict is placed so that its left-top corner is at the reference point; if align is 'rc, the pict is placed so that the center of its bounding box’s right edge coincides with the reference point.

By default, if there are multiple picts to be placed, they are vertically appended, aligned according to the horizontal component of align. For example, if align is 'cc, the default composer is vc-append; for 'lt, the default composer is vl-append. The spacing is initially 0.

Examples:

> (ppict-do base             #:go (coord 1/2 1/2 'rb)             (colorize (circle 20) "red")             #:go (coord 1/2 1/2 'lt)             (colorize (circle 20) "darkgreen")) > (ppict-do base             #:go (coord 1 0 'rt #:abs-x -5 #:abs-y 10)             50 ; change spacing             (text "abc")             (text "12345")             0  ; and again             (text "ok done")) > (ppict-do base             #:go (coord 0 0 'lt #:compose ht-append)             (circle 10)             (circle 20)             (circle 30))

Uses of grid can be translated into uses of coord, but the translation depends on the alignment. For example, (grid 2 2 1 1 'lt) is equivalent to (coord 0 0 'lt), but (grid 2 2 1 1 'rt) is equivalent to (coord 1/2 0 'rt).

Examples:

> (define none-for-me-thanks     (ppict-do base               #:go (grid 2 2 1 1 'lt)               (text "You do not like")               (colorize (text "green eggs and ham?") "darkgreen"))) > none-for-me-thanks > (ppict-do none-for-me-thanks             #:go (grid 2 2 2 1 'rb)             (colorize (text "I do not like them,") "red")             (text "Sam-I-am."))

When a list picts is to be placed, their bounding boxes are normalized to the maximum width and height of all picts in the list; each pict is centered in its new bounding box. The picts are then cascaded so there is step-x space between each of the picts’ left edges; there is also step-x space between the base pict’s left edge and the first pict’s left edge. Similarly for step-y and the vertical spacing.

If step-x or step-y is 'auto, the spacing between the centers of the picts to be placed is determined automatically so that the inter-pict spacing is the same as the spacing between the last pict and the base.

Examples:

> (ppict-do base             #:go (cascade)             (colorize (filled-rectangle 100 100) "red")             (colorize (filled-rectangle 100 100) "blue")) > (ppict-do base             #:go (cascade 40 20)             (colorize (filled-rectangle 100 100) "red")             (colorize (filled-rectangle 100 100) "blue"))

Example:

> (ppict-do base             #:go (tile 2 2)             (circle 50)             (rectangle 50 50)             (jack-o-lantern 50)             (standard-fish 50 30 #:color "red"))

Example:

> (ppict-do base             #:go (cascade)             (tag-pict (standard-fish 40 20 #:direction 'right #:color "red") 'red-fish)             (tag-pict (standard-fish 50 30 #:direction 'left #:color "blue") 'blue-fish)             #:go (at-find-pict 'red-fish rc-find 'lc #:abs-x 10)             (text "red fish"))

Example:

> (ppict-do base             #:go (cascade)             (tag-pict (standard-fish 40 20 #:direction 'right #:color "red") 'red-fish)             (tag-pict (standard-fish 50 30 #:direction 'left #:color "blue") 'blue-fish)             #:go (merge-refpoints (coord 1 0 'rc)                                   (at-find-pict 'red-fish))             (text "red fish"))

33.5.2 Progressive Slides

(require unstable/gui/pslide)

Note that like slide but unlike ppict-do*, the number of slides produced is one greater than the number of #:next uses; that is, a slide is created for the final pict.

Remember to include gap-size after updating the current placer if you want slide-like spacing.

Example:

> (pslide #:go (coord 0 0 'lt)           (t "You do not like")           (colorize (t "green eggs and ham?") "darkgreen")           #:next           #:go (coord 1 1 'rb)           (colorize (t "I do not like them,") "red")           (t "Sam-I-am."))

Note that the text is not flush against the sides of the slide, because pslide uses a base pict the size of the client area, excluding the margins.