From 323c74fd091fe4d92983b203025684430b69faec Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 29 Jan 2012 08:40:44 -0500 Subject: [PATCH] added docs for a&d args of slideshow's dc procedure Based on John Clements's correction Also, improve some cross references. --- collects/scribblings/slideshow/picts.scrbl | 53 ++++++++++++++-------- 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/collects/scribblings/slideshow/picts.scrbl b/collects/scribblings/slideshow/picts.scrbl index f3ded6765d..cc808e6f1a 100644 --- a/collects/scribblings/slideshow/picts.scrbl +++ b/collects/scribblings/slideshow/picts.scrbl @@ -50,7 +50,7 @@ The size information for a pict is computed when the pict is created. This strategy supports programs that create new picts though arbitrarily complex computations on the size and shape of existing picts. The functions @racket[pict-width], @racket[pict-height], -@racket[pict-descent], and @racket[pict-ascent] extract bounding-box +@racket[pict-descent], and @racket[pict-ascent] extract bounding box information from a pict. A pict is a convertible datatype through the @racketmodname[file/convertible] @@ -74,7 +74,7 @@ A @racket[pict] structure is normally not created directly with The @racket[draw] field contains the pict's drawing information in an internal format. Roughly, the drawing information is a procedure that takes a @racket[dc<%>] drawing context and an offset for the pict's -top-left corner (i.e., it's bounding box's top left corner relative to +top-left corner (i.e., it's @tech{bounding box}'s top left corner relative to the @racket[dc<%>] origin). The state of the @racket[dc<%>] is intended to affect the pict's drawing; for example, the pen and brush will be set for a suitable default drawing mode, and the @@ -124,26 +124,35 @@ A @racket[child] structure is normally not created directly with pict?])]{ Creates an arbitrary self-rendering pict. The arguments to the -rendering procedure will be a device context and top-left location for +rendering procedure will be a drawing context and top-left location for drawing. + +The @racket[w] and @racket[h] arguments determine the width and height +of the resulting pict's @tech{bounding box}. In the three-argument case, the +descent is @math{0} and the ascent is @racket[h] for the bounding +box; in the five-argument case, @racket[a] and @racket[d] are used +as the bounding box's ascent and descent. 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 dc will be set. The text mode will be transparent, but +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.} + @defproc*[([(blank [size real? 0]) pict?] [(blank [w real?] [h real?]) pict?] [(blank [w real?] [a real?] [d real?]) pict?] [(blank [w real?] [h real?] [a real?] [d real?]) pict?])]{ Creates a pict that draws nothing. The one-argument case supplies a -value used for both the width and height. In the one- and two-argument +value used for both the width and height of the resulting pict's +@tech{bounding box}. In the one- and two-argument case, the ascent and descent are @math{0} for the resulting pict's bounding box; in the three-argument case, the height is computed by adding the given ascent and descent.} + @defproc[(text [content string?] [style text-style/c null] [size (integer-in 1 255) 12] @@ -191,7 +200,7 @@ The given @racket[size] is in pixels, but it is ignored if a The @racket[angle] is in radians, and positive values rotate counter-clockwise. For a non-zero @racket[angle], the resulting -pict's bounding box covers the rotated text, and the descent is zero +pict's @tech{bounding box} covers the rotated text, and the descent is zero and the ascent is the height.} @@ -200,7 +209,8 @@ and the ascent is the height.} [(vline [w real?] [h real?] [#:segment seg-length (or/c #f real?) #f]) pict?])]{ -Straight lines, centered within their bounding boxes.} +Straight lines, centered within their @tech{bounding box}es.} + @defproc[(frame [pict pict?] [#:segment seg-length (or/c #f real?) #f] @@ -270,12 +280,14 @@ If the bitmap cannot be loaded, if the given @racket[bitmap%] object is not valid, or if the @racket[bitmap-draft-mode] parameter is set to @racket[#t], the result pict draws the word ``bitmap failed''.} + @defproc*[([(arrow [size real?] [radians real?]) pict?] [(arrowhead [size real?] [radians real?]) pict?])]{ Creates an arrow or arrowhead in the specific direction within a @racket[size] by @racket[size] pict. Points on the arrow may extend -slightly beyond the bounding box.} +slightly beyond the @tech{bounding box}.} + @defproc*[([(pip-line [dx real?] [dy real?] [size real?]) pict?] [(pip-arrow-line [dx real?] [dy real?] [size real?]) pict?] @@ -456,7 +468,7 @@ comparing the last-element bottom-right corners.} [pict pict?]) pict?])]{ -Creates a pict with the same bounding box, ascent, and descent as +Creates a pict with the same @tech{bounding box}, ascent, and descent as @racket[base], but with @racket[pict] placed on top. The @racket[dx] and @racket[dy] arguments specify how far right and down the second pict's corner is from the first pict's corner. Alternately, the @@ -511,7 +523,7 @@ horizontal or vertical placement of each cell in the column or row.} @defproc*[([(scale [pict pict?] [factor real?]) pict?] [(scale [pict pict?] [w-factor real?] [h-factor real?]) pict?])]{ -Scales a pict drawing, as well as its @tech{bounding-box}. The drawing +Scales a pict drawing, as well as its @tech{bounding box}. The drawing is scaled by adjusting the destination @racket[dc<%>]'s scale while drawing the original @racket[pict].} @@ -520,7 +532,7 @@ drawing the original @racket[pict].} Rotates a pict's drawing by @racket[theta] radians counter-clockwise. -The bounding box of the resulting pict is the box encloses the rotated +The @tech{bounding box} of the resulting pict is the box encloses the rotated corners of @racket[pict] (which inflates the area of the bounding box, unless @racket[theta] is a multiple of half of @racket[pi]). The ascent and descent lines of the result's bounding box are the @@ -577,6 +589,7 @@ contexts and cases when semi-transparent drawing works.} Clips a pict's drawing to its @tech{bounding box}.} + @defproc*[([(inset/clip [pict pict?] [amt real?]) pict?] [(inset/clip [pict pict?] [h-amt real?] [v-amt real?]) pict?] [(inset/clip [pict pict?] [l-amt real?] [t-amt real?] @@ -585,6 +598,7 @@ Clips a pict's drawing to its @tech{bounding box}.} Insets and clips the pict's drawing to its @tech{bounding box}. Usually, the inset amounts are negative.} + @defform*[[(scale/improve-new-text pict-expr scale-expr) (scale/improve-new-text pict-expr x-scale-expr y-scale-expr)]]{ @@ -598,7 +612,7 @@ black-and-white colors.} @; ------------------------------------------------------------------------ -@section{Bounding-Box Adjusters} +@section{Bounding Box Adjusters} @defproc*[([(inset [pict pict?] [amt real?]) pict?] [(inset [pict pict?] [h-amt real?] [v-amt real?]) pict?] @@ -617,12 +631,12 @@ Truncates @racket[pict]'s @tech{bounding box} by removing the descent part.} @defproc[(lift-above-baseline [pict pict?] [amt real?]) pict?]{ Lifts @racket[pict] relative to its baseline, extending the -@tech{bounding-box} height if necessary.} +@tech{bounding box} height if necessary.} @defproc[(drop-below-ascent [pict pict?] [amt real?]) pict?]{ Drops @racket[pict] relative to its ascent line, extending the -@tech{bounding-box} height if necessary.} +@tech{bounding box} height if necessary.} @defproc[(baseless [pict pict?]) pict?]{ @@ -636,11 +650,13 @@ preserving all the drawing of @racket[pict]). The last element, as reported by @racket[pict-last] is also set to @racket[(or (pict-last sub-pict) sub-pict)].} + @defproc[(panorama [pict pict?]) pict?]{ -Shifts the given pict's bounding box to enclose the bounding boxes of +Shifts the given pict's @tech{bounding box} to enclose the bounding boxes of all sub-picts (even @racket[launder]ed picts).} + @defproc[(use-last [pict pict?] [sub-pict pict-path?]) pict?]{ Returns a pict like @racket[pict], but with the last element (as @@ -691,9 +707,10 @@ be within the second element, and so on.} Returns @racket[#t] if @racket[v] is a @racket[pict] or a non-empty list of @racket[pict]s.} + @defproc[(launder [pict pict?]) pict?]{ -Creates a pict that has the same drawing and bounding box of +Creates a pict that has the same drawing and @tech{bounding box} of @racket[pict], but which hides all of its sub-picts so that they cannot be found with functions like @racket[lt-find]. If @racket[pict] has a last-line pict, then the laundered pict has a fresh last-line @@ -811,7 +828,7 @@ used to roun the balloon's corners. As usual, if it is less than @racket[1], then it acts as a ratio of the balloon's width or height. The result is a balloon, not a pict. The @racket[balloon-pict] -function extracts a pict whose bounding box does not include the +function extracts a pict whose @tech{bounding box} does not include the spike, but includes the rest of the image, and the @racket[balloon-point-x] and @racket[balloon-point-y] functions extract the location of the spike point. More typically, the @@ -847,7 +864,7 @@ to the location specified by either @racket[x] and @racket[y] @racket[at-pict] with @racket[find]. The @racket[find] function uses its arguments like @racket[lt-find]. -The resulting pict has the same bounding box, descent, and ascent as +The resulting pict has the same @tech{bounding box}, descent, and ascent as @racket[base], even if the balloon extends beyond the bounding box.}