From d265231452b400994ef84980ba85bf35960b512e Mon Sep 17 00:00:00 2001 From: Robby Findler Date: Wed, 30 Mar 2011 09:41:03 -0500 Subject: [PATCH] added some examples for pen cap and join styles --- collects/scribblings/draw/common.rkt | 2 + collects/scribblings/draw/pen-class.scrbl | 136 +++++++++++++++++----- 2 files changed, 108 insertions(+), 30 deletions(-) diff --git a/collects/scribblings/draw/common.rkt b/collects/scribblings/draw/common.rkt index 33d197fa0e..7af675239f 100644 --- a/collects/scribblings/draw/common.rkt +++ b/collects/scribblings/draw/common.rkt @@ -1,12 +1,14 @@ (module common racket/base (require scribble/manual scribble/basic + scribble/eval racket/class racket/contract "blurbs.ss" (only-in "../reference/mz.ss" AllUnix exnraise)) (provide (all-from-out scribble/manual) (all-from-out scribble/basic) + (all-from-out scribble/eval) (all-from-out racket/class) (all-from-out racket/contract) (all-from-out "blurbs.ss") diff --git a/collects/scribblings/draw/pen-class.scrbl b/collects/scribblings/draw/pen-class.scrbl index e95b307706..a040e9643b 100644 --- a/collects/scribblings/draw/pen-class.scrbl +++ b/collects/scribblings/draw/pen-class.scrbl @@ -1,5 +1,11 @@ #lang scribble/doc -@(require "common.ss") +@(require "common.rkt" + (for-label slideshow/pict)) + +@(define pen-eval (make-base-eval)) +@(interaction-eval + #:eval pen-eval + (require racket/draw slideshow/pict racket/class)) @defclass/title[pen% object% ()]{ @@ -16,48 +22,48 @@ A pen's style is one of the following: @itemize[ - @item{@indexed-scheme['transparent] --- Draws with no effect (on the + @item{@indexed-racket['transparent] --- Draws with no effect (on the outline of the drawn shape).} - @item{@indexed-scheme['solid] --- Draws using the pen's color. If a + @item{@indexed-racket['solid] --- Draws using the pen's color. If a (monochrome) stipple is installed into the pen, black pixels from the stipple are transferred to the destination using the brush's color, and white pixels from the stipple are not transferred.} - @item{@indexed-scheme['xor] --- The same as @racket['solid], accepted + @item{@indexed-racket['xor] --- The same as @racket['solid], accepted only for partial backward compatibility.} - @item{@indexed-scheme['hilite] --- Draws with black and a @racket[0.3] alpha.} + @item{@indexed-racket['hilite] --- Draws with black and a @racket[0.3] alpha.} @item{The following special pen modes use the pen's color, and they only apply when a stipple is not used: @itemize[ - @item{@indexed-scheme['dot]} - @item{@indexed-scheme['long-dash]} - @item{@indexed-scheme['short-dash]} - @item{@indexed-scheme['dot-dash]} - @item{@indexed-scheme['xor-dot]} - @item{@indexed-scheme['xor-long-dash]} - @item{@indexed-scheme['xor-short-dash]} - @item{@indexed-scheme['xor-dot-dash]} + @item{@indexed-racket['dot]} + @item{@indexed-racket['long-dash]} + @item{@indexed-racket['short-dash]} + @item{@indexed-racket['dot-dash]} + @item{@indexed-racket['xor-dot]} + @item{@indexed-racket['xor-long-dash]} + @item{@indexed-racket['xor-short-dash]} + @item{@indexed-racket['xor-dot-dash]} ]} ] To avoid creating multiple pens with the same characteristics, use the - global @scheme[pen-list%] object @indexed-scheme[the-pen-list], or + global @racket[pen-list%] object @indexed-racket[the-pen-list], or provide a color, width, and style to @xmethod[dc<%> set-pen]. When drawing in @racket['smoothed] or @racket['aligned] mode, a pen's size is truncated after scaling to an integral size. A pen of size - @scheme[0] (after truncation, if applicable) uses a non-zero, + @racket[0] (after truncation, if applicable) uses a non-zero, scale-insensitive line size for the destination drawing context: @racket[1/4] unit (after scaling) for @racket[post-script-dc%] or @racket[pdf-dc%] contexts in @racket['smoothed] mode, or @racket[1] unit (after scaling) for any other context. For example, in unscaled canvas and bitmap contexts, a zero-width pen behaves the same as a - pen of size @scheme[1]. + pen of size @racket[1]. @defconstructor[([color (or/c string? (is-a?/c color%)) "black"] @@ -77,7 +83,7 @@ When drawing in @racket['smoothed] or @racket['aligned] mode, a pen's Creates a pen with the given color, width, style, cap style (see @method[pen% get-cap]), join style (see @method[pen% get-join]), and stipple. For the case that the color is specified using a name, see - @scheme[color-database<%>] for information about color names; if the + @racket[color-database<%>] for information about color names; if the name is not known, the pen's color is black. } @@ -88,12 +94,41 @@ Creates a pen with the given color, width, style, cap style (see Returns the pen cap style, which determines the shape of a line at each of its ending points when drawn by @method[dc<%> draw-line] or at the non-connecting ends of lines when drawn by @method[dc<%> draw-lines] or -@method[dc<%> draw-path]. The default is @scheme['round], which draws the +@method[dc<%> draw-path]. The default is @racket['round], which draws the end of a line as a semi-circle. The @racket['projecting] style draws a square in place of the semi-circle (i.e., past the point at which the line stops). The @racket['butt] style ends the line with a straight edge, instead of projecting past the ending point of the line. +This code draws three diagonal lines, one with each of the possible caps +(@racket['round], @racket['butt], and then @racket['projecting]) and puts +a little red dot on the end points of the line. + +@examples[#:eval + pen-eval + (define (plot-line dc x1 y1 x2 y2 cap) + (send dc set-pen + (send the-pen-list find-or-create-pen + "black" 40 'solid cap)) + (send dc draw-line x1 y1 x2 y2) + (send dc set-brush "red" 'solid) + (send dc set-pen "black" 1 'transparent) + (send dc draw-ellipse (- x1 4) (- y1 4) 8 8) + (send dc draw-ellipse (- x2 4) (- y2 4) 8 8)) + + (dc + (λ (dc dx dy) + (define old-pen (send dc get-pen)) + (define old-brush (send dc get-brush)) + + (plot-line dc 20 30 80 90 'round) + (plot-line dc 100 30 160 90 'butt) + (plot-line dc 180 30 240 90 'projecting) + + (send dc set-pen old-pen) + (send dc set-brush old-brush)) + 270 120)] + } @defmethod[(get-color) @@ -112,18 +147,58 @@ draw-rectangle], @method[dc<%> draw-polygon], or @method[dc<%> draw-path]. The join style fills the space that would be left at the outside corner of two lines if they were draw separately with @racket['butt] line endings. The default join style is -@scheme['round], which fills under an arc that lines up with the +@racket['round], which fills under an arc that lines up with the outside of each of the two lines. The @racket['bevel] style fills in the gap without adding extra pixels (i.e., it makes a blunt corner). The @racket['miter] style fills the gap by adding pixels that would be covered by both lines if they were extended past the corner -(i.e., it makes a sharp corner).} +(i.e., it makes a sharp corner). + +This code shows the three join styles +(@racket['round], @racket['bevel] and then @racket['miter]) +by drawing a sequence +of lines, first with a sharp corner and then with a right-angle. +Each of the end points of the lines i with a red dot. + +@examples[#:eval + pen-eval + (define points '((100 . 100) + (0 . 0) + (0 . 100) + (40 . 100))) + + (define (connect-points dc dx dy join) + (send dc set-pen + (send the-pen-list find-or-create-pen + "black" 40 'solid 'round join)) + (send dc draw-lines points dx dy) + (send dc set-brush "red" 'solid) + (send dc set-pen "black" 1 'transparent) + (for ([pt (in-list points)]) + (send dc draw-ellipse + (+ dx (car pt) -4) (+ dy (cdr pt) -4) + 8 8))) + + (dc + (λ (dc dx dy) + (define old-pen (send dc get-pen)) + (define old-brush (send dc get-brush)) + + (connect-points dc 20 50 'round) + (connect-points dc 180 50 'bevel) + (connect-points dc 340 50 'miter) + + (send dc set-pen old-pen) + (send dc set-brush old-brush)) + 460 170)] + +} @defmethod[(get-stipple) (or/c (is-a?/c bitmap%) #f)]{ -Gets the current stipple bitmap, or returns @scheme[#f] if no stipple +Gets the current stipple bitmap, or returns @racket[#f] if no stipple bitmap is installed. } @@ -134,7 +209,7 @@ Gets the current stipple bitmap, or returns @scheme[#f] if no stipple 'xor-dot 'xor-long-dash 'xor-short-dash 'xor-dot-dash)]{ -Returns the pen style. See @scheme[pen%] for information about +Returns the pen style. See @racket[pen%] for information about possible styles. } @@ -152,7 +227,7 @@ Returns the pen width. Sets the pen cap style. See @method[pen% get-cap] for information about cap styles. -A pen cannot be modified if it was obtained from a @scheme[pen-list%] +A pen cannot be modified if it was obtained from a @racket[pen-list%] or while it is selected into a drawing context. } @@ -169,7 +244,7 @@ A pen cannot be modified if it was obtained from a @scheme[pen-list%] Sets the pen color. A pen cannot be modified if it was obtained from a - @scheme[pen-list%] or while it is selected into a drawing context. + @racket[pen-list%] or while it is selected into a drawing context. } @@ -180,18 +255,18 @@ Sets the pen join style. See @method[pen% get-join] for information about join styles. A pen cannot be modified if it was obtained from a - @scheme[pen-list%] or while it is selected into a drawing context. + @racket[pen-list%] or while it is selected into a drawing context. } @defmethod[(set-stipple [bitmap (or/c (is-a?/c bitmap%) #f)]) void?]{ -Sets the pen stipple bitmap, where @scheme[#f] turns off the stipple bitmap. +Sets the pen stipple bitmap, where @racket[#f] turns off the stipple bitmap. If @racket[bitmap] is modified while is associated with a pen, the effect on the pen is unspecified. A pen cannot be modified if it was - obtained from a @scheme[pen-list%] or while it is selected into a + obtained from a @racket[pen-list%] or while it is selected into a drawing context. } @@ -202,11 +277,11 @@ If @racket[bitmap] is modified while is associated with a pen, the 'xor-dot-dash)]) void?]{ -Sets the pen style. See @scheme[pen%] for information about the +Sets the pen style. See @racket[pen%] for information about the possible styles. A pen cannot be modified if it was obtained from a - @scheme[pen-list%] or while it is selected into a drawing context. + @racket[pen-list%] or while it is selected into a drawing context. } @@ -216,7 +291,8 @@ A pen cannot be modified if it was obtained from a Sets the pen width. A pen cannot be modified if it was obtained from a - @scheme[pen-list%] or while it is selected into a drawing context. + @racket[pen-list%] or while it is selected into a drawing context. }} +@close-eval[pen-eval]