On this page:
dc
unsafe-dc
blank
text
hline
vline
frame
ellipse
circle
filled-ellipse
disk
rectangle
filled-rectangle
rounded-rectangle
filled-rounded-rectangle
bitmap
arrow
arrowhead
pip-line
pip-arrow-line
pip-arrows-line
pin-line
pin-arrow-line
pin-arrows-line
text-style/  c
bitmap-draft-mode

2 Basic Pict Constructors

procedure

(dc draw w h [a d])  pict?

  draw : (-> (is-a?/c dc<%>) real? real? any)
  w : real?
  h : real?
  a : real? = h
  d : real? = 0
Creates an arbitrary self-rendering pict. The arguments to the rendering procedure will be a drawing context and top-left location for drawing.

The w, h, a, and d arguments determine the width, height, ascent, and descent of the of the resulting pict’s bounding box respectively.

When the rendering procedure is called, the current pen and brush will be 'solid and in the pict’s color and linewidth, and the scale and offset of the drawing context will be set. The text mode will be transparent, but the font and text colors are not guaranteed to be anything in particular.

Example:
> (dc (λ (dc dx dy)
        (define old-brush (send dc get-brush))
        (define old-pen (send dc get-pen))
        (send dc set-brush
          (new brush% [style 'fdiagonal-hatch]
                      [color "darkslategray"]))
        (send dc set-pen
          (new pen% [width 3] [color "slategray"]))
        (define path (new dc-path%))
        (send path move-to 0 0)
        (send path line-to 50 0)
        (send path line-to 25 50)
        (send path close)
        (send dc draw-path path dx dy)
        (send dc set-brush old-brush)
        (send dc set-pen old-pen))
    50 50)

image

The draw is called during the dynamic extent of the call to dc as part of the contract checking.

Specifically, the pre-condition portion of the contract for dc concocts a dc<%> object with a random initial state, calls the draw argument with that dc<%> and then checks to make sure that draw the state of the dc<%> object is the same as it was before draw was called.

Example:
> (dc (λ (dc dx dy)
        (send dc set-brush "red" 'solid)
        (send dc set-pen "black" 1 'transparent)
        (send dc draw-ellipse dx dy 50 50))
      50 50)

dc: contract violation;

 draw proc does not restore the dc state after being called

      draw: #<procedure>

  in: (->i

       ((draw

         (-> (is-a?/c dc<%>) real? real? any))

        (w real?)

        (h real?))

       ((d (or/c #f real?)) (a (or/c #f real?)))

       #:pre/name

       (draw)

       "draw proc does not restore the dc state after being

called"

       (... draw)

       (p pict?))

  contract from: <pkgs>/pict-lib/pict/main.rkt

  blaming: top-level

   (assuming the contract is correct)

  at: <pkgs>/pict-lib/pict/main.rkt:83.3

Changed in version 1.3 of package pict-lib: The draw argument is now called by the #:pre condition of dc.

procedure

(unsafe-dc draw w h [a d])  pict?

  draw : (-> (is-a?/c dc<%>) real? real? any)
  w : real?
  h : real?
  a : real? = h
  d : real? = 0
Like dc, except that the draw procedure is not called during the precondition contract checking.

procedure

(blank [size])  pict?

  size : real? = 0
(blank w h)  pict?
  w : real?
  h : real?
(blank w a d)  pict?
  w : real?
  a : real?
  d : real?
(blank w h a d)  pict?
  w : real?
  h : real?
  a : real?
  d : real?
Creates a pict that draws nothing. The one-argument case supplies a value used for both the width and height of the resulting pict’s bounding box. In the one- and two-argument case, the ascent and descent are 0 for the resulting pict’s bounding box; in the three-argument case, the height is computed by adding the given ascent and descent.

Example:
> (blank 50)

image

procedure

(text content [style size angle])  pict?

  content : string?
  style : text-style/c = null
  size : (integer-in 1 1024) = 12
  angle : real? = 0
Creates a pict that draws text. For creating text picts within a slide presentation, see t. The size of the resulting pict may depend on the value of dc-for-text-size.

The style argument must be one of the following:

If both 'combine and 'no-combine are specified, the first one in style takes precedence. Similarly, if both 'aligned and 'unaligned are specified, the first one in style takes precedence. If 'caps is specified, the angle must be zero.

The given size is in pixels, but it is ignored if a font% object is provided in the text-style.

The angle is in radians, and positive values rotate counter-clockwise. For a non-zero angle, the resulting pict’s bounding box covers the rotated text, and the descent is zero and the ascent is the height.

Examples:
> (text "tom collins")

image

> (text "g & t" (cons 'bold 'roman))

image

> (text "martini" null 13 (/ pi 2))

image

procedure

(hline w h [#:segment seg-length])  pict?

  w : real?
  h : real?
  seg-length : (or/c #f real?) = #f
(vline w h [#:segment seg-length])  pict?
  w : real?
  h : real?
  seg-length : (or/c #f real?) = #f
Straight lines, centered within their bounding boxes.

Examples:
> (hline 40 5)

image

> (hline 40 30)

image

> (vline 5 40 #:segment 5)

image

procedure

(frame pict    
  [#:segment seg-length    
  #:color color    
  #:line-width width])  pict?
  pict : pict-convertible?
  seg-length : (or/c #f real?) = #f
  color : (or/c #f string? (is-a?/c color%)) = #f
  width : (or/c #f real?) = #f
Frames a given pict. If the color or line width are provided, the override settings supplied by the context.

Examples:
> (frame (circle 30))

image

> (frame (circle 30) #:segment 5)

image

> (frame (circle 30) #:color "chartreuse" #:line-width 3)

image

procedure

(ellipse w    
  h    
  [#:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
(circle diameter    
  [#:border-color border-color    
  #:border-width border-width])  pict?
  diameter : real?
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
(filled-ellipse w    
  h    
  [#:draw-border? draw-border?    
  #:color color    
  #:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  draw-border? : any/c = #t
  color : (or/c #f string? (is-a?/c color%)) = #f
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
(disk diameter    
  [#:draw-border? draw-border?    
  #:color color    
  #:border-color border-color    
  #:border-width border-width])  pict?
  diameter : (and/c rational? (not/c negative?))
  draw-border? : any/c = #t
  color : (or/c #f string? (is-a?/c color%)) = #f
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
Unfilled and filled ellipses.

If draw-border? is #f, then the pen is set to be transparent before drawing the ellipse. The color, border-color and border-width arguments control the fill color, color of the border, and width of the border, respectively. If these arguments are #f, values set using linewidth and colorize are used instead. Passing non-#f values as border-color or border-width when draw-border? is #f results in a contract violation.

Examples:
> (ellipse 40 30)

image

> (circle 30)

image

> (filled-ellipse 30 40)

image

> (disk 30)

image

> (disk 40 #:color "Chartreuse" #:border-color "Medium Aquamarine" #:border-width 5)

image

Changed in version 1.4 of package pict-lib: Added #:color, #:border-color and #:border-width arguments.

procedure

(rectangle w    
  h    
  [#:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
(filled-rectangle w    
  h    
  [#:draw-border? draw-border?    
  #:color color    
  #:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  draw-border? : any/c = #t
  color : (or/c #f string? (is-a?/c color%)) = #f
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
Unfilled and filled rectangles.

If draw-border? is #f, then the pen is set to be transparent before drawing the rectangle. The color, border-color and border-width arguments control the fill color, color of the border, and width of the border, respectively. If these arguments are #f, values set using linewidth and colorize are used instead. Passing non-#f values as border-color or border-width when draw-border? is #f results in a contract violation.

Examples:
> (rectangle 50 50)

image

> (filled-rectangle 50 80)

image

> (filled-rectangle 60 70 #:color "Thistle" #:border-color "Gainsboro" #:border-width 10)

image

Changed in version 1.4 of package pict-lib: Added #:color, #:border-color and #:border-width arguments.

procedure

(rounded-rectangle w    
  h    
  [corner-radius    
  #:angle angle    
  #:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  corner-radius : real? = -0.25
  angle : real? = 0
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
(filled-rounded-rectangle w    
  h    
  [corner-radius    
  #:angle angle    
  #:draw-border? draw-border?    
  #:color color    
  #:border-color border-color    
  #:border-width border-width])  pict?
  w : real?
  h : real?
  corner-radius : real? = -0.25
  angle : real? = 0
  draw-border? : any/c = #t
  color : (or/c #f string? (is-a?/c color%)) = #f
  border-color : (or/c #f string? (is-a?/c color%)) = #f
  border-width : (or/c #f real?) = #f
Unfilled and filled rectangles with rounded corners. The corner-radius is used to determine how much rounding occurs in the corners. If it is a positive number, then it determines the radius of a circle touching the edges in each corner, and the rounding of the rectangle follow the edge of those circles. If it is a negative number, then the radius of the circles in the corners is the absolute value of the corner-radius times the smaller of width and height.

The angle determines how much the rectangle is rotated, in radians.

If draw-border? is #f, then the pen is set to be transparent before drawing the rectangle. The color, border-color and border-width arguments control the fill color, color of the border, and width of the border, respectively. If these arguments are #f, values set using linewidth and colorize are used instead. Passing non-#f values as border-color or border-width when draw-border? is #f results in a contract violation.

Examples:
> (rounded-rectangle 40 40 -0.3 #:angle (/ pi 4))

image

> (filled-rounded-rectangle 50 40)

image

> (filled-rounded-rectangle 70 30 #:color "Burlywood" #:border-color "Bisque" #:border-width 8)

image

Changed in version 1.4 of package pict-lib: Added #:color, #:border-color and #:border-width arguments.

procedure

(bitmap img)  pict

  img : 
(or/c path-string?
      (is-a?/c bitmap%)
      pict-convertible?
      convertible?)
Returns a pict that displays a bitmap. When a path is provided, the image is loaded with the 'unknown/mask flag, which means that a mask bitmap is generated if the file contains a mask.

If the bitmap cannot be loaded, if the given bitmap% object is not valid, or if the bitmap-draft-mode parameter is set to #t, the result pict draws the words “bitmap failed”.

If img is both convertible and pict convertible, then the pict conversion is used. If both apply, the pict conversion is used. If pict conversion is used, the pict is drawn into a bitmap and the result of bitmap draws that bitmap. If convertible is used, it is used with the 'png-bytes conversion mode.

procedure

(arrow size radians)  pict?

  size : real?
  radians : real?
(arrowhead size radians)  pict?
  size : real?
  radians : real?
Creates an arrow or arrowhead in the specific direction within a size by size pict. Points on the arrow may extend slightly beyond the bounding box.

Examples:
> (arrow 30 0)

image

> (arrow 30 (/ pi 2))

image

> (arrowhead 30 0)

image

procedure

(pip-line dx dy size)  pict?

  dx : real?
  dy : real?
  size : real?
(pip-arrow-line dx dy size)  pict?
  dx : real?
  dy : real?
  size : real?
(pip-arrows-line dx dy size)  pict?
  dx : real?
  dy : real?
  size : real?
Creates a line (with some number of arrowheads) as a zero-sized pict suitable for use with pin-over. The 0-sized picture contains the starting point.

The size is used for the arrowhead size. Even though pip-line creates no arrowheads, it accepts the size argument for consistency with the other functions.

procedure

(pin-line pict    
  src    
  find-src    
  dest    
  find-dest    
  [#:start-angle start-angle    
  #:end-angle end-angle    
  #:start-pull start-pull    
  #:end-pull end-pull    
  #:line-width line-width    
  #:color color    
  #:alpha alpha    
  #:style style    
  #:under? under?    
  #:label label    
  #:x-adjust-label x-adjust-label    
  #:y-adjust-label y-adjust-label])  pict?
  pict : pict-convertible?
  src : pict-path?
  find-src : (pict-convertible? pict-path? . -> . (values real? real?))
  dest : pict-path?
  find-dest : (pict-convertible? pict-path? . -> . (values real? real?))
  start-angle : (or/c real? #f) = #f
  end-angle : (or/c real? #f) = #f
  start-pull : real? = 1/4
  end-pull : real? = 1/4
  line-width : (or/c #f real?) = #f
  color : (or/c #f string? (is-a?/c color%)) = #f
  alpha : (real-in 0.0 1.0) = #f
  style : 
(or/c 'transparent 'solid 'xor 'hilite
      'dot 'long-dash 'short-dash 'dot-dash
      'xor-dot 'xor-long-dash 'xor-short-dash
      'xor-dot-dash #f)
 = #f
  under? : any/c = #f
  label : pict? = (blank)
  x-adjust-label : real? = 0
  y-adjust-label : real? = 0
(pin-arrow-line arrow-size    
  pict    
  src    
  find-src    
  dest    
  find-dest    
  [#:start-angle start-angle    
  #:end-angle end-angle    
  #:start-pull start-pull    
  #:end-pull end-pull    
  #:line-width line-width    
  #:color color    
  #:alpha alpha    
  #:style style    
  #:under? under?    
  #:label label    
  #:x-adjust-label x-adjust-label    
  #:y-adjust-label y-adjust-label    
  #:solid? solid?    
  #:hide-arrowhead? hide-arrowhead?])  pict?
  arrow-size : real?
  pict : pict-convertible?
  src : pict-path?
  find-src : (pict-convertible? pict-path? . -> . (values real? real?))
  dest : pict-path?
  find-dest : (pict-convertible? pict-path? . -> . (values real? real?))
  start-angle : (or/c real? #f) = #f
  end-angle : (or/c real? #f) = #f
  start-pull : real? = 1/4
  end-pull : real? = 1/4
  line-width : (or/c #f real?) = #f
  color : (or/c #f string? (is-a?/c color%)) = #f
  alpha : (real-in 0.0 1.0) = #f
  style : 
(or/c 'transparent 'solid 'xor 'hilite
      'dot 'long-dash 'short-dash 'dot-dash
      'xor-dot 'xor-long-dash 'xor-short-dash
      'xor-dot-dash #f)
 = #f
  under? : any/c = #f
  label : pict? = (blank)
  x-adjust-label : real? = 0
  y-adjust-label : real? = 0
  solid? : any/c = #t
  hide-arrowhead? : any/c = #f
(pin-arrows-line arrow-size    
  pict    
  src    
  find-src    
  dest    
  find-dest    
  [#:start-angle start-angle    
  #:end-angle end-angle    
  #:start-pull start-pull    
  #:end-pull end-pull    
  #:line-width line-width    
  #:color color    
  #:alpha alpha    
  #:style style    
  #:under? under?    
  #:label label    
  #:x-adjust-label x-adjust-label    
  #:y-adjust-label y-adjust-label    
  #:solid? solid?    
  #:hide-arrowhead? hide-arrowhead?])  pict?
  arrow-size : real?
  pict : pict-convertible?
  src : pict-path?
  find-src : (pict-convertible? pict-path? . -> . (values real? real?))
  dest : pict-path?
  find-dest : (pict-convertible? pict-path? . -> . (values real? real?))
  start-angle : (or/c real? #f) = #f
  end-angle : (or/c real? #f) = #f
  start-pull : real? = 1/4
  end-pull : real? = 1/4
  line-width : (or/c #f real?) = #f
  color : (or/c #f string? (is-a?/c color%)) = #f
  alpha : (real-in 0.0 1.0) = #f
  style : 
(or/c 'transparent 'solid 'xor 'hilite
      'dot 'long-dash 'short-dash 'dot-dash
      'xor-dot 'xor-long-dash 'xor-short-dash
      'xor-dot-dash #f)
 = #f
  under? : any/c = #f
  label : pict-convertible? = (blank)
  x-adjust-label : real? = 0
  y-adjust-label : real? = 0
  solid? : any/c = #t
  hide-arrowhead? : any/c = #f
Adds a line or line-with-arrows onto pict, using one of the pict-finding functions (e.g., lt-find) to extract the source and destination of the line.

If under? is true, then the line and arrows are added under the existing pict drawing, instead of on top. If solid? is false, then the arrowheads are hollow instead of filled.

The start-angle, end-angle, start-pull, and end-pull arguments control the curve of the line (and the defaults produce a straight line):

The line-width, color, alpha, and style arguments apply to the added line.

When the hide-arrowhead? argument is a true value, then space for an arrowhead is kept around the line, but the arrowhead itself is not drawn.

When the label argument is non-false, the given pict is used as a label for the line, and moved by (x-adjust-label, y-adjust-label).

Examples:
(define pict-a (rectangle 40 40))
(define pict-b (circle 40))
(define combined (hc-append 200 pict-a pict-b))
> (pin-line combined
            pict-a cc-find
            pict-b cc-find)

image

> (pin-arrow-line 30 combined
                  pict-a rc-find
                  pict-b lc-find
                  #:line-width 3
                  #:style 'long-dash
                  #:color "medium goldenrod"
                  #:label (text "From Square to Circle"))

image

> (pin-arrows-line 30 combined
                   pict-a rc-find
                   pict-b lc-find
                   #:start-angle (/ pi 11)
                   #:end-angle (- (/ pi 11))
                   #:solid? #f)

image

Changed in version 1.4 of package pict-lib: Added #:label, #:x-adjust-label and #:y-adjust-label arguments.

A contract that matches the second argument of text.

parameter

(bitmap-draft-mode)  boolean?

(bitmap-draft-mode on?)  void?
  on? : any/c
A parameter that determines whether bitmap loads/uses a bitmap.