7.2 Pict

8.18.0.15

7.2 Pict🔗

(require toolbox/pict)	package: toolbox-draw-lib
(require toolbox/pict/base)

The toolbox/pict/base module exports all of the bindings documented in this section. The toolbox/pict module re-exports everything from pict, pict/conditional, ppict/tag, and toolbox/pict/base, except exports from later modules shadow exports from earlier ones with the same name.

7.2.1 Constructors🔗

procedure
(arrowhead size [radians]) → pict?
size : (and/c rational? (not/c negative?))
radians : rational? = 0

Like arrowhead from pict, but only draws a fill, not a stroke (and radians is optional).

Example:

> (arrowhead 30)

procedure
(arrow-line [ #:arrow-size arrow-size
#:line-length line-length
#:line-width line-width]) → pict?
  arrow-size : (and/c rational? (not/c negative?)) = 10
  line-length : (and/c rational? (not/c negative?)) = 50
  line-width : (or/c (and/c rational? (not/c negative?)) #f) = 2

Draws a right-facing arrow built from an arrowhead of size arrow-size and a tail line of length line-length and stroke width line-width. If line-width is #f, the current pen width is used.

Example:

> (arrow-line)

7.2.2 Combiners🔗

procedure
(pin-over base dx dy pict [#:hole hole]) → pict?
  base : pict?
  dx : rational?
  dy : rational?
  pict : pict?
   hole :
(or/c (vector/c rational? rational?)
      (vector/c pict-path? pict-finder/c)
      pict-finder/c)
= #(0 0)
(pin-over base path find pict [#:hole hole]) → pict?
  base : pict?
  path : pict-path?
  find : pict-finder/c
  pict : pict?
   hole :
(or/c (vector/c rational? rational?)
      (vector/c pict-path? pict-finder/c)
      pict-finder/c)
= #(0 0)

Like pin-over from pict, but extended to accept the more general pict paths instead of tagless pict paths. Additionally, the hole argument specifies a “pinhole” within pict that controls how pict is aligned to the pin location:

If hole is a vector of two rational numbers, the numbers are used as x- and y-coordinates for the pinhole’s location, relative to the top-left corner of pict.
If hole is a vector of a pict path and a finder procedure, the finder procedure is used to locate a child of pict, and the resulting coordinates are used as the pinhole.
If hole is a finder procedure, it is equivalent to supplying the finder procedure with an empty pict path.

Examples:

> (define (bg-rect color)
    (filled-rectangle 30 30
                      #:draw-border? #f
                      #:color color))
> (define bg
    (vc-append (hc-append (bg-rect "light green")
                          (bg-rect "light blue"))
               (hc-append (bg-rect "light blue")
                          (bg-rect "light green"))))
> (define fg
    (disk 15 #:color "crimson"
          #:draw-border? #f))
> (pin-over bg '() cc-find fg)
> (pin-over bg '() cc-find fg #:hole rb-find)
> (pin-over bg '() ct-find fg #:hole ct-find)

procedure
(pin-under base dx dy pict [#:hole hole]) → pict?
  base : pict?
  dx : rational?
  dy : rational?
  pict : pict?
   hole :
(or/c (vector/c rational? rational?)
      (vector/c pict-path? pict-finder/c)
      pict-finder/c)
= #(0 0)
(pin-under base path find pict [#:hole hole]) → pict?
  base : pict?
  path : pict-path?
  find : pict-finder/c
  pict : pict?
   hole :
(or/c (vector/c rational? rational?)
      (vector/c pict-path? pict-finder/c)
      pict-finder/c)
= #(0 0)

Like pin-under from pict, but extended in the same ways as pin-over.

procedure
(line-append pict ...+) → pict?
pict : pict?

Creates a new pict by aligning the descent and ascent lines of each adjacent pair of picts. That is, each pict is vertically positioned such that its ascent line (as reported by pict-ascent) is aligned with the previous pict’s descent line (as reported by pict-descent). Each pict is horizontally positioned so that it immediately follows the previous pict’s last element (as reported by pict-last).

The alignment rules used by line-append make it useful for aligning multiline blocks, especially code that uses expression-based indentation.

Examples:

> (define (tt str)
    (text str 'modern 16))
> (line-append
   (vl-append
    (tt "(define some-example-with-a-long-first-line")
    (tt "  (values "))
   (vl-append
    (tt "(some-expression)")
    (tt "(another-expression)")
    (tt "note-the-close-paren!"))
   (tt ")"))

7.2.3 Drawing Adjusters🔗

procedure
(set-smoothing pict smoothing) → pict?
pict : pict?
smoothing : (or/c 'unsmoothed 'smoothed 'aligned)

Sets the anti-aliased smoothing mode used when drawing pict to smoothing. For an explanation of the different modes, see set-smoothing in dc<%>.

procedure
(set-brush pict [#:color color #:style style]) → pict?
  pict : pict?
  color : (or/c color? 'pen #f) = (make-color 0 0 0)
  style : (or/c brush-style/c #f) = 'solid

Sets the brush used while drawing pict. If any argument is #f, its value is inherited from whatever brush was installed by the enclosing context.

As a special case, if color is 'pen, the brush’s color is set to the current pen color. This is intended to be used to follow the convention used by pict constructors like filled-rectangle, which (for some reason) default to using the current pen color rather than the current brush color if no color is provided.

Examples:

> (define rect
    (dc (λ (dc x y)
          (send dc draw-rectangle x y 50 30))
        50 30))
> (set-brush rect #:color "red")
> (set-brush rect #:style 'fdiagonal-hatch)

procedure
(adjust-brush pict
[ #:color color
#:style style]) → pict?
  pict : pict?
  color : (or/c color? 'pen #f) = #f
  style : (or/c brush-style/c #f) = #f

Like set-brush, but argument values default to #f, so any unprovided arguments will be inherited from the current brush.

procedure
(set-pen pict
[ #:color color
#:width width
#:style style
#:cap cap
#:join join]) → pict?
  pict : pict?
  color : (or/c color? #f) = (make-color 0 0 0)
  width : (or/c (real-in 0 255) #f) = 0
  style : (or/c pen-style/c #f) = 'solid
  cap : (or/c pen-cap-style/c #f) = 'round
  join : (or/c pen-join-style/c #f) = 'round

Sets the pen used while drawing pict. If any argument is #f, its value is inherited from whatever pen was installed by the enclosing context.

Note that many pict constructors, like filled-rectangle, conventionally default (for some reason) to using the current pen color for the fill rather than the current brush color if no color is provided. For that reason, using set-pen to change the pen color can also affect the fill color of picts created that way.

Examples:

> (define rect
    (dc (λ (dc x y)
          (send dc draw-rectangle x y 50 30))
        50 30))
> (set-pen rect #:color "red" #:width 3)
> (set-pen rect #:style 'short-dash #:width 3)

procedure
(adjust-pen pict
[ #:color color
#:width width
#:style style
#:cap cap
#:join join]) → pict?
  pict : pict?
  color : (or/c color? #f) = #f
  width : (or/c (real-in 0 255) #f) = #f
  style : (or/c pen-style/c #f) = #f
  cap : (or/c pen-cap-style/c #f) = #f
  join : (or/c pen-join-style/c #f) = #f

Like set-pen, but argument values default to #f, so any unprovided arguments will be inherited from the current brush.

7.2.4 Bounding Box Adjusters🔗

procedure
(one-line pict) → pict?
pict : pict?

Drops the ascent line (as reported by pict-ascent) to the descent line, making the entire pict behave as a single line of text.

procedure
(refocus pict path) → pict?
pict : pict?
path : pict-path?

Like refocus from pict, but accepts an arbitrary pict path to locate the sub-pict to focus on.

Examples:

> (define p1 (filled-rectangle 15 30 #:color "sienna"))
> (define p2 (hc-append
p1
(filled-rectangle 15 30 #:color "darkkhaki")))
> (define p3 (filled-rectangle 50 50 #:color "khaki"))
> (define combined (cc-superimpose p3 p2))
> combined
> (refocus combined p2)
> (refocus combined (list p2 p1))

procedure
(refocus* pict paths) → pict?
pict : pict?
paths : (non-empty-listof pict-path?)

Like refocus, but shifts the bounding box to encompass all of the picts at the given paths. Unlike refocus, refocus* does not set pict-last.

Examples:

> (define p1 (disk 15 #:color "dark sea green"))
> (define p2 (filled-rectangle 15 15 #:color "cadet blue"))
> (define p3 (rotate (filled-rectangle 15 15 #:color "plum") (/ pi 4)))
> (define p4 (vc-append 7 (hc-append 12 p1 p2) p3))
> p4
> (refocus* p4 (list p1 p2))
> (refocus* p4 (list p1 p3))
> (refocus* p4 (list p2 p3))

procedure
(recenter pict x y) → pict?
  pict : pict?
  x : rational?
  y : rational?
(recenter pict path [find]) → pict?
  pict : pict?
  path : pict-path?
  find : pict-finder/c = cc-find

Insets pict so that the chosen point is its new center. In the first form, the x and y arguments specify a new center point as a coordinate offset from pict’s top-left corner. In the second form, the find procedure is used to locate a sub-pict at path in the same way as pin-over, and the result is used as the new center point.

Examples:

> (define p1 (filled-rectangle 15 15 #:color "slate blue"))
> (define p2 (disk 15 #:color "firebrick"))
> (define p3 (disk 15 #:color "forest green"))
> (define p2+p3 (hc-append 5 p2 p3))
> (frame (vc-append 5 p1 p2+p3))
> (frame (vc-append 5 p1 (recenter p2+p3 p3)))

procedure
(use-last pict path) → pict?
pict : pict?
path : pict-path?

Like use-last from pict, but accepts an arbitrary pict path instead of a tagless pict path.

procedure
(use-last* pict path) → pict?
pict : pict?
path : pict-path?

Like use-last* from pict, but accepts an arbitrary pict path instead of a sub-pict.

7.2.5 Paths and Finders🔗

procedure
(pict-path? v) → boolean?
v : any/c

Returns #t if v is a pict path, which is either a pict, a symbol, or a list of picts and symbols. Otherwise, returns #f.

This definition is broader than the one used by pict-path? from pict (which is provided by this library as tagless-pict-path?), as it allows pict path elements to be symbols in addition to picts. When a symbol is an element of a pict path, it refers to all children tagged with that symbol via tag-pict. Additionally, an empty list may be used as a pict path, which always refers to the root pict.

procedure
(tagless-pict-path? v) → boolean?
v : any/c

Returns #t if v is a tagless pict path, which is either a pict or a non-empty list of picts. As the name of this function suggests, a tagless pict path is a pict path that contains no symbolic tags (though it additionally requires that a list path be non-empty).

The tagless-pict-path? function is actually the same binding as pict-path? from pict, re-exported under a different name.

procedure
(ppath-cons elem path) → pict-path?
elem : (or/c pict? symbol?)
path : pict-path?

Prefixes path with elem to form a larger pict path.

Examples:

> (ppath-cons 'a '())
'a
> (ppath-cons 'a 'b)
'(a b)
> (ppath-cons 'a '(b c))
'(a b c)

procedure
(ppath-append path-a path-b) → pict-path?
path-a : pict-path?
path-b : pict-path?

Appends path-a and path-b to form a larger pict path.

Examples:

> (ppath-append 'a 'b)
'(a b)
> (ppath-append '(a b) 'c)
'(a b c)
> (ppath-append 'a '(b c))
'(a b c)
> (ppath-append '(a b) '(c d))
'(a b c d)

procedure
(find-child p path) → tagless-pict-path?
p : pict?
path : pict-path?

Finds a child pict with the given pict path and returns a (possibly more specific) tagless pict path to it. If there are multiple child picts with the given path, one is selected arbitrarily. If there are no child picts with the given path, an exn:fail:contract exception is raised.

procedure
(find-children p path) → (listof tagless-pict-path?)
p : pict?
path : pict-path?

Finds all child picts with the given pict path and returns a list of (possibly more specific) tagless pict paths to them.

procedure
(offset-find find dx dy) → pict-finder/c
  find : pict-finder/c
  dx : rational?
  dy : rational?

Returns a pict finder like find, except the returned x- and y-coordinates are offset by dx and dy, respectively.

value
pict-finder/c : chaperone-contract?
= (-> pict? tagless-pict-path? (values rational? rational?))

A contract that accepts pict finder procedures like lt-find. See also Pict Finders in the pict documentation.

7.2.6 Conditional Picts🔗

procedure
(pict-when show? p [#:launder? launder?]) → pict?
  show? : any/c
  p : pict?
  launder? : any/c = #f

Like (show p show?), except if show? is #f and launder? is not #f, launder is additionally applied to the result.

procedure
(pict-unless hide? p [#:launder? launder?]) → pict?
  hide? : any/c
  p : pict?
  launder? : any/c = #f

Like (hide p hide?), except that if hide? and launder? are both not #f, launder is additionally applied to the result.

contents ← prev up next →

1	Syntax
2	Data Structures
3	Logging
4	Formatting
5	Gregor
6	Database
7	Drawing
8	Web
	Index

7.2.1	Constructors
7.2.2	Combiners
7.2.3	Drawing Adjusters
7.2.4	Bounding Box Adjusters
7.2.5	Paths and Finders
7.2.6	Conditional Picts

7.1	Color
7.2	Pict