dc, pen, and brush doc corrections related to v5.1 changes
This commit is contained in:
Matthew Flatt
parent
dedb207a86
commit
93126d1546
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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%)])
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user