diff --git a/collects/scribblings/draw/brush-class.scrbl b/collects/scribblings/draw/brush-class.scrbl index fcc7463411..b41f60e65f 100644 --- a/collects/scribblings/draw/brush-class.scrbl +++ b/collects/scribblings/draw/brush-class.scrbl @@ -4,15 +4,13 @@ @defclass/title[brush% object% ()]{ A brush is a drawing tool with a color and a style that is used for - filling in areas, such as the interior of a rectangle or ellipse. On - a monochrome display, all non-white brushes are drawn as black. + filling in areas, such as the interior of a rectangle or ellipse. In + a monochrome destination, all non-white brushes are drawn as black. In addition to its color and style, a brush can have a stipple bitmap. - This stipple is used only in unsmoothed mode (see @method[dc<%> - set-smoothing]) or in a PostScript drawing context. Painting with a + Painting with a stipple brush is similar to calling @method[dc<%> draw-bitmap] with - the stipple bitmap in the filled region, except that the bitmap may - not be scaled in the same way (depending on the platform and device). + the stipple bitmap in the filled region. A brush's style is one of the following: @@ -27,34 +25,19 @@ A brush's style is one of the following: brush's color, and white pixels from the stipple are not transferred.} - @item{@indexed-scheme['opaque] --- Same as @scheme['solid], except when a - monochrome stipple is installed for unsmoothed or PostScript - drawing; in that case, white pixels from the stipple are + @item{@indexed-scheme['opaque] --- The same as @scheme['solid] for a color + stipple. For a monochrome stipple, white pixels from + the stipple are transferred to the destination using the destination's background color.} - @item{@indexed-scheme['xor] --- In a smoothing mode or if a color - stipple is installed, @scheme['xor] is treated as - @scheme['solid]. Otherwise, the brush's color or colored - (monochrome) stipple is xor-ed with existing destination pixel - values. The @scheme['xor] mapping is unspecified for arbitrary - color combinations, but the mapping provides two guarantees: + @item{@indexed-scheme['xor] --- The same as @racket['solid], accepted + only for partial backward compatibility.} - @itemize[ + @item{@indexed-scheme['hilite] --- Draws with black and a @racket[0.3] alpha.} - @item{Black-and-white drawing to a color or monochrome - destination always works as expected: black xor white = black, - white xor black = black, black xor black = white, and white xor - white = white.} - - @item{Performing the same drawing operation twice in a row with - @scheme['xor] is equivalent to a no-op.} - - ]} - - @item{@indexed-scheme['hilite] --- Draws with black and a 30% alpha.} - - @item{@indexed-scheme['panel] --- the same as @scheme['solid].} + @item{@indexed-scheme['panel] --- The same as @scheme['solid], accepted + only for partial backward compatibility.} @item{The following modes correspond to built-in stipples drawn in @scheme['solid] mode: @@ -68,9 +51,8 @@ A brush's style is one of the following: @item{@indexed-scheme['vertical-hatch] --- vertical lines} ] - However, when a specific stipple is installed into the brush - for when drawing with a smoothing mode into a non-PostScript - context, the above modes are ignored and @scheme['solid] is + However, when a specific stipple is installed into the brush, + the above modes are ignored and @scheme['solid] is used, instead.} ] @@ -96,8 +78,7 @@ To avoid creating multiple brushes with the same characteristics, use [stipple (or/c #f (is-a?/c bitmap%)) #f])]{ -When no argument are provided, the result is a solid black brush. - Otherwise, the result is a brush with the given color, style, and stipple. For +Creates a brush with the given color, style, and stipple. For the case that the color is specified using a name, see @scheme[color-database<%>] for information about color names; if the name is not known, the brush's color is black. @@ -148,7 +129,7 @@ For the case that the color is specified using a string, see } -@defmethod[(set-stipple [bitmap (or/c (is-a?/c bitmap%) false/c)]) +@defmethod[(set-stipple [bitmap (or/c (is-a?/c bitmap%) #f)]) void?]{ Sets or removes the stipple bitmap, where @scheme[#f] removes the @@ -161,9 +142,6 @@ A bitmap cannot be used as a stipple if it is selected into a modified if it was obtained from a @scheme[brush-list%] or while it is selected into a drawing context. -A pen's stipple is not used in a smoothing mode, except for a - @scheme[post-script-dc%] (which is always in a smoothing mode). - } @defmethod[(set-style [style (one-of/c 'transparent 'solid 'opaque diff --git a/collects/scribblings/draw/dc-intf.scrbl b/collects/scribblings/draw/dc-intf.scrbl index 4668ba8295..c870723184 100644 --- a/collects/scribblings/draw/dc-intf.scrbl +++ b/collects/scribblings/draw/dc-intf.scrbl @@ -88,7 +88,7 @@ If both the pen and brush are non-transparent, the wedge is filled [mask (or/c (is-a?/c bitmap%) false/c) #f]) boolean?]{ -Displays a bitmap. The @scheme[dest-x] and @scheme[dest-y] arguments +Displays the @racket[source] bitmap. The @scheme[dest-x] and @scheme[dest-y] arguments are in DC coordinates. For color bitmaps, the drawing style and color arguments are @@ -97,30 +97,33 @@ For color bitmaps, the drawing style and color arguments are and color settings to draw a monochrome stipple (see @scheme[brush%] for more information). -If a mask bitmap is supplied, it must have the same width and height - as the bitmap to display, and its @method[bitmap% ok?] must return - true, otherwise @|MismatchExn|. The bitmap to draw and the mask +If a @racket[mask] bitmap is supplied, it must have the same width and height + as @racket[source], and its @method[bitmap% ok?] must return + true, otherwise @|MismatchExn|. The @racket[source] bitmap and @racket[mask] bitmap can be the same object, but if the drawing context is a @scheme[bitmap-dc%] object, both bitmaps must be distinct from the destination bitmap, otherwise @|MismatchExn|. -If the mask bitmap is monochrome, drawing occurs in the target - @scheme[dc<%>] only where the mask bitmap contains black pixels. +If the @racket[mask] bitmap is monochrome, drawing occurs in the + target @scheme[dc<%>] only where the mask bitmap contains black + pixels (independent of @racket[style], which controls how the white + pixels of a monochrome @racket[source] are handled). -If the mask bitmap is grayscale and the bitmap to draw is not - monochrome, then the blackness of each mask pixel controls the - opacity of the drawn pixel (i.e., the mask acts as an inverted alpha - channel). If a mask bitmap is color, the component values of a given - pixel are averaged to arrive at a gray value for the pixel. +If the @racket[mask] bitmap is grayscale, then the blackness of each + mask pixel controls the opacity of the drawn pixel (i.e., the mask + acts as an inverted alpha channel). If the @racket[mask] bitmap is + color, the component values of a given pixel are averaged to arrive + at an @racket[alpha] value for the pixel. -The current brush, current pen, current text, and current alpha - settings for the DC have no effect on how the bitmap is drawn, but - the bitmap is scaled if the DC has a scale. +The current brush, current pen, and current text for the DC have no + effect on how the bitmap is drawn, but the bitmap is scaled if the DC + has a scale, and the DC's alpha setting determines the opacity of the + drawn pixels (in combination with an alpha channel of @racket[bitmap] + and any given @racket[mask]). -For @scheme[post-script-dc%] output, the mask bitmap is currently - ignored, and the @scheme['solid] style is treated the same as - @scheme['opaque]. (However, mask bitmaps and @scheme['solid] drawing - may become supported for @scheme[post-script-dc%] in the future.) +For @scheme[post-script-dc%] and @racket[pdf-dc%] output, opacity from + an alpha channel in @racket[bitmap] or from @racket[mask] is + rounded to full transparency or opacity. The result is @scheme[#t] if the bitmap is successfully drawn, @scheme[#f] otherwise (possibly because the bitmap's @method[bitmap% @@ -987,15 +990,6 @@ The @scheme['aligned] smoothing mode is like @scheme['smoothed], but @method[dc<%> draw-rounded-rectangle], and @method[dc<%> draw-arc], the given width and height are each decreased by @math{1.0}. -In either smoothing mode, brush and pen stipples are ignored (except - for PostScript drawing), and @scheme['hilite] and @scheme['xor] - drawing modes are treated as @scheme['solid]. If smoothing is not - supported, then attempting to set the smoothing mode to - @scheme['smoothed] or @scheme['aligned] will have no effect, and - @method[dc<%> get-smoothing] will always return - @scheme['unsmoothed]. Similarly, @method[dc<%> get-smoothing] for a - @scheme[post-script-dc%] always returns @scheme['smoothed]. - } @defmethod[(set-text-background [color (is-a?/c color%)]) diff --git a/collects/scribblings/draw/pen-class.scrbl b/collects/scribblings/draw/pen-class.scrbl index 4e0b063f53..60e15f5720 100644 --- a/collects/scribblings/draw/pen-class.scrbl +++ b/collects/scribblings/draw/pen-class.scrbl @@ -4,13 +4,11 @@ @defclass/title[pen% object% ()]{ A pen is a drawing tool with a color, width, and style. A pen draws - lines and outlines, such as the outline of a rectangle. On a - monochrome display, all non-white pens are drawn as black. + lines and outlines, such as the outline of a rectangle. In a + monochrome destination, all non-white pens are drawn as black. In addition to its color, width, and style, a pen can have a stipple - bitmap that is a 8 x 8 monochrome bitmap. This stipple is used only - in unsmoothed mode (see @method[dc<%> set-smoothing]) or in a - PostScript drawing context. Painting with a stipple pen is similar to + bitmap. Painting with a stipple pen is similar to calling @method[dc<%> draw-bitmap] with the stipple bitmap in region painted by the pen. @@ -27,36 +25,10 @@ A pen's style is one of the following: brush's color, and white pixels from the stipple are not transferred.} - @item{@indexed-scheme['xor] --- In unsmoothed mode, the pen's color - or colored stipple is xor-ed with existing destination pixel - values. The @scheme['xor] mapping is unspecified for arbitrary - color combinations, but the mapping provides two guarantees: - @itemize[ + @item{@indexed-scheme['xor] --- The same as @racket['solid], accepted + only for partial backward compatibility.} - @item{Black-and-white drawing to a color or monochrome - destination always works as expected: black xor white = black, - white xor black = black, black xor black = white, and white xor - white = white.} - - @item{Performing the same drawing operation twice in a row with - @scheme['xor] is equivalent to a no-op.} - - ] - In a smoothing mode, @scheme['xor] is equivalent to @scheme['solid].} - - @item{@indexed-scheme['hilite] --- In unsmoothed mode, existing - destination pixels are ``highlighted'' in a platform-specific - way when the pen color is black. Under Windows for a color - drawing context, the inverted RGB components of destination - pixel are combined with the RGB components of the system-wide - highlight color using a bitwise ``or'', and the combination is - used. Under Mac OS X for a color drawing context, the - inverted RGB components of the system-wide highlight color are - subtracted from the RGB components of each destination pixel, - and the difference (or 0 for a negative result) is used. Under - X or for any monochrome drawing context, @scheme['hilite] is the - same as @scheme['xor]. In a smoothing mode, @scheme['hilite] is - treated like @scheme['solid].} + @item{@indexed-scheme['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: @@ -78,15 +50,9 @@ To avoid creating multiple pens with the same characteristics, use the provide a color, width, and style to @xmethod[dc<%> set-pen]. A pen of size @scheme[0] uses the minimum line size for the - destination drawing context. In (unscaled) canvases and bitmaps in - unsmoothed mode, a zero-width pen behaves the nearly same as a pen of - size @scheme[1]. In a smoothing mode (including all - @scheme[post-script-dc%] drawing), a pen of size @scheme[0] draws a - line thinner than a pen of size @scheme[1]. If the pen's width is not - an integer, then the width is truncated to an integer (even before - scaling) in unsmoothed mode. - - + destination drawing context. In (unscaled) canvases and bitmaps, + a zero-width pen behaves the nearly same as a pen of + size @scheme[1]. @defconstructor[([color (or/c string? (is-a?/c color%)) "black"] @@ -103,8 +69,7 @@ A pen of size @scheme[0] uses the minimum line size for the [stipple (or/c #f (is-a?/c bitmap%)) #f])]{ -When no argument are provided, the result is a solid black pen of - width @scheme[0]. Otherwise, the result is a pen with the given +Creates a pen with the given color, width, style, cap style, join style, and stipple. For the case that the color is specified using a name, see @scheme[color-database<%>] for information about @@ -115,8 +80,7 @@ When no argument are provided, the result is a solid black pen of @defmethod[(get-cap) (one-of/c 'round 'projecting 'butt)]{ -Returns the pen cap style (Windows unsmoothed, X unsmoothed, all - smoothing). The default is @scheme['round]. +Returns the pen cap style. The default is @scheme['round]. } @@ -130,8 +94,7 @@ Returns the pen's color object. @defmethod[(get-join) (one-of/c 'round 'bevel 'miter)]{ -Returns the pen join style (Windows unsmoothed, X unsmoothed, all - smoothing). The default is @scheme['round]. +Returns the pen join style. The default is @scheme['round]. } @@ -164,8 +127,7 @@ Returns the pen width. @defmethod[(set-cap [cap-style (one-of/c 'round 'projecting 'butt)]) void?]{ -Sets the pen cap style (Windows unsmoothed, X unsmoothed, all - smoothing). See @method[pen% get-cap] for information about cap +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%] @@ -192,8 +154,7 @@ A pen cannot be modified if it was obtained from a @defmethod[(set-join [join-style (one-of/c 'round 'bevel 'miter)]) void?]{ -Sets the pen join style (Windows unsmoothed, X unsmoothed, all - smoothing). See @method[pen% get-join] for information about join +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 @@ -201,11 +162,10 @@ A pen cannot be modified if it was obtained from a } -@defmethod[(set-stipple [stipple (or/c (is-a?/c bitmap%) false/c)]) +@defmethod[(set-stipple [stipple (or/c (is-a?/c bitmap%) #f)]) void?]{ -Sets the pen stipple bitmap, which must be an 8 x 8 monochrome bitmap - or @scheme[#f], which turns off the stipple bitmap. +Sets the pen stipple bitmap, where @scheme[#f] turns off the stipple bitmap. A bitmap cannot be used as a stipple if it is selected into a @scheme[bitmap-dc%] object; if the given bitmap is selected into a @@ -213,9 +173,6 @@ A bitmap cannot be used as a stipple if it is selected into a if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. -A pen's stipple is not used in a smoothing mode, except for a - @scheme[post-script-dc%] (which is always in smoothed mode). - } @defmethod[(set-style [style (one-of/c 'transparent 'solid 'xor 'hilite