942 lines
33 KiB
Racket
942 lines
33 KiB
Racket
#lang scribble/doc
|
|
@(require "common.ss")
|
|
|
|
@definterface/title[dc<%> ()]{
|
|
|
|
A @scheme[dc<%>] object is a drawing context for drawing graphics and
|
|
text. It represents output devices in a generic way; e.g., a canvas
|
|
has a drawing context, as does a printer.
|
|
|
|
The drawing methods, such as @method[dc<%> draw-rectangle], accept
|
|
real number values as arguments, but the results are only well-defined
|
|
when the drawing coordinates are in the range @scheme[-16383] to
|
|
@scheme[16383]. This restriction applies to the coordinates both
|
|
before and after offsets and scaling factors are applied.
|
|
|
|
@defmethod[(clear)
|
|
void?]{
|
|
|
|
Clears the drawing region (fills it with the current background color,
|
|
as determined by @method[dc<%> get-background]).
|
|
|
|
}
|
|
|
|
@defmethod[(draw-arc [x real?]
|
|
[y real?]
|
|
[width (and/c real? (not/c negative?))]
|
|
[height (and/c real? (not/c negative?))]
|
|
[start-radians real?]
|
|
[end-radians real?])
|
|
void?]{
|
|
|
|
Draws a counter-clockwise circular arc, a part of the ellipse
|
|
inscribed in the rectangle specified by @scheme[x] (left), @scheme[y]
|
|
(top), @scheme[width], and @scheme[height]. The arc starts at the angle
|
|
specified by @scheme[start-radians] (@scheme[0] is three o'clock and
|
|
half-pi is twelve o'clock) and continues counter-clockwise to
|
|
@scheme[end-radians]. If @scheme[start-radians] and @scheme[end-radians] are
|
|
the same, a full ellipse is drawn.
|
|
|
|
The current pen is used for the arc. If the current brush is not
|
|
transparent, it is used to fill the wedge bounded by the arc plus
|
|
lines (not drawn) extending to the center of the inscribed ellipse.
|
|
|
|
If both the pen and brush are non-transparent, the wedge is filled
|
|
with the brush before the arc is drawn with the pen. The wedge and
|
|
arc meet so that no space is left between them, but the precise
|
|
overlap between the wedge and arc is platform- and size-specific.
|
|
Typically, the regions drawn by the brush and pen overlap. More
|
|
generally, the pen is centered over the outline of the arc, rounding
|
|
toward the center in unsmoothed mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(draw-bitmap [source (is-a?/c bitmap%)]
|
|
[dest-x real?]
|
|
[dest-y real?]
|
|
[style (one-of/c 'solid 'opaque 'xor) 'solid]
|
|
[color (is-a?/c color%) (send the-color-database find-color "black")]
|
|
[mask (or/c (is-a?/c bitmap%) false/c) #f])
|
|
boolean?]{
|
|
|
|
Displays a bitmap. The @scheme[dest-x] and @scheme[dest-y] arguments
|
|
are in DC coordinates.
|
|
|
|
For color bitmaps, the drawing style and color arguments are
|
|
ignored. For monochrome bitmaps, @method[dc<%> draw-bitmap] uses the
|
|
style and color arguments in the same way that a brush uses its style
|
|
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
|
|
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 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), at least on most platforms. (Non-monochrome masks
|
|
are collapsed to monochrome under X when the RENDER extension is not
|
|
available, and under Windows 95 and NT when @filepath{msing32.dll} is not
|
|
available.) Other combinations involving a non-monochrome mask (i.e.,
|
|
a non-grayscale mask or a monochrome bitmap to draw) produce
|
|
platform-specific results.
|
|
|
|
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.
|
|
|
|
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.)
|
|
|
|
The result is @scheme[#t] if the bitmap is successfully drawn,
|
|
@scheme[#f] otherwise (possibly because the bitmap's @method[bitmap%
|
|
ok?] method returns @scheme[#f]).
|
|
|
|
See also @method[dc<%> draw-bitmap-section].
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-bitmap-section [source (is-a?/c bitmap%)]
|
|
[dest-x real?]
|
|
[dest-y real?]
|
|
[src-x real?]
|
|
[src-y real?]
|
|
[src-width (and/c real? (not/c negative?))]
|
|
[src-height (and/c real? (not/c negative?))]
|
|
[style (one-of/c 'solid 'opaque 'xor) 'solid]
|
|
[color (is-a?/c color%) (send the-color-database find-color "black")]
|
|
[mask (or/c (is-a?/c bitmap%) false/c) #f])
|
|
boolean?]{
|
|
|
|
Displays part of a bitmap.
|
|
|
|
The @scheme[src-x], @scheme[src-y], @scheme[src-width], and
|
|
@scheme[src-height] arguments specify a rectangle in the source
|
|
bitmap to copy into this drawing context.
|
|
|
|
See @method[dc<%> draw-bitmap] for information about @scheme[dest-x],
|
|
@scheme[dest-y], @scheme[style], @scheme[color], and @scheme[mask].
|
|
|
|
}
|
|
|
|
@defmethod[(draw-ellipse [x real?]
|
|
[y real?]
|
|
[width (and/c real? (not/c negative?))]
|
|
[height (and/c real? (not/c negative?))])
|
|
void?]{
|
|
|
|
Draws an ellipse contained in a rectangle with the given top-left
|
|
corner and size. The current pen is used for the outline, and the
|
|
current brush is used for filling the shape.
|
|
|
|
If both the pen and brush are non-transparent, the ellipse is filled
|
|
with the brush before the outline is drawn with the pen. The filling
|
|
and outline meet so that no space is left between them, but the
|
|
precise overlap between the filling and outline is platform- and
|
|
size-specific. Typically, the regions drawn by the brush and pen
|
|
overlap. More generally, the pen is centered over the outline of the
|
|
ellipse, rounding toward the center in unsmoothed mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-line [x1 real?]
|
|
[y1 real?]
|
|
[x2 real?]
|
|
[y2 real?])
|
|
void?]{
|
|
|
|
Draws a line from one point to another. The current pen is used for
|
|
drawing the line.
|
|
|
|
In unsmoothed mode, the points correspond to pixels, and the line
|
|
covers both the start and end points. For a pen whose scaled width is
|
|
larger than @scheme[1], the line is drawn centered over the start and
|
|
end points.
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-lines [points (listof (is-a?/c point%))]
|
|
[xoffset real? 0]
|
|
[yoffset real? 0])
|
|
void?]{
|
|
|
|
Draws lines using a list of @scheme[points], adding @scheme[xoffset]
|
|
and @scheme[yoffset] to each point. The current pen is used for
|
|
drawing the lines.
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-path [path (is-a?/c dc-path%)]
|
|
[xoffset real? 0]
|
|
[yoffset real? 0]
|
|
[fill-style (one-of/c 'odd-even 'winding) 'odd-even])
|
|
void?]{
|
|
|
|
Draws the sub-paths of the given @scheme[dc-path%] object, adding
|
|
@scheme[xoffset] and @scheme[yoffset] to each point. The current pen
|
|
is used for drawing the path as a line, and the current brush is used
|
|
for filling the area bounded by the path.
|
|
|
|
If both the pen and brush are non-transparent, the path is filled with
|
|
the brush before the outline is drawn with the pen. The filling and
|
|
outline meet so that no space is left between them, but the precise
|
|
overlap between the filling and outline is platform- and
|
|
size-specific. Thus, the regions drawn by the brush and pen may
|
|
overlap. More generally, the pen is centered over the path, rounding
|
|
left and down in unsmoothed mode.
|
|
|
|
The @scheme[fill-style] argument specifies the fill rule:
|
|
@scheme['odd-even] or @scheme['winding]. In @scheme['odd-even] mode, a
|
|
point is considered enclosed within the path if it is enclosed by an
|
|
odd number of sub-path loops. In @scheme['winding] mode, a point is
|
|
considered enclosed within the path if it is enclosed by more or less
|
|
clockwise sub-path loops than counter-clockwise sub-path loops. In
|
|
unsmoothed mode, the @scheme['winding] fill rule is not supported
|
|
under Mac OS X and it is not supported when @scheme[path] contains
|
|
multiple sub-paths; the @scheme['winding] fill rules is always
|
|
supported when smoothing is enabled (see
|
|
@method[dc<%> set-smoothing]).
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-point [x real?]
|
|
[y real?])
|
|
void?]{
|
|
|
|
Plots a single point using the current pen.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-polygon [points (listof (is-a?/c point%))]
|
|
[xoffset real? 0]
|
|
[yoffset real? 0]
|
|
[fill-style (one-of/c 'odd-even 'winding) 'odd-even])
|
|
void?]{
|
|
|
|
Draw a filled polygon using a list of @scheme[points], adding
|
|
@scheme[xoffset] and @scheme[yoffset] to each point. The polygon is
|
|
automatically closed, so the first and last point can be
|
|
different. The current pen is used for drawing the outline, and the
|
|
current brush for filling the shape.
|
|
|
|
If both the pen and brush are non-transparent, the polygon is filled
|
|
with the brush before the outline is drawn with the pen. The filling
|
|
and outline meet so that no space is left between them, but the
|
|
precise overlap between the filling and outline is platform- and
|
|
shape-specific. Thus, the regions drawn by the brush and pen may
|
|
overlap. More generally, the pen is centered over the polygon lines,
|
|
rounding left and down in unsmoothed mode.
|
|
|
|
The @scheme[fill-style] argument specifies the fill rule:
|
|
@scheme['odd-even] or @scheme['winding]. In @scheme['odd-even] mode, a
|
|
point is considered enclosed within the polygon if it is enclosed by
|
|
an odd number of loops. In @scheme['winding] mode, a point is
|
|
considered enclosed within the polygon if it is enclosed by more or
|
|
less clockwise loops than counter-clockwise loops. The
|
|
@scheme['winding] fill rule is not supported under Mac OS X,
|
|
except when smoothing is enabled (see
|
|
@method[dc<%> set-smoothing]).
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(draw-rectangle [x real?]
|
|
[y real?]
|
|
[width (and/c real? (not/c negative?))]
|
|
[height (and/c real? (not/c negative?))])
|
|
void?]{
|
|
|
|
Draws a rectangle with the given top-left corner and size. The
|
|
current pen is used for the outline and the current brush for filling
|
|
the shape.
|
|
|
|
If both the pen and brush are non-transparent, the rectangle is filled
|
|
with the brush before the outline is drawn with the pen. In
|
|
unsmoothed mode, when the pen is size 0 or 1, the filling precisely
|
|
overlaps the entire outline. As a result, if a rectangle is drawn
|
|
with a size-0 or size-1 @scheme['xor] @scheme[pen%] and an
|
|
@scheme['xor] @scheme[brush%], the outline is xored twice (first by
|
|
the brush, then by the pen), leaving it unchanged. More generally,
|
|
the pen is centered over the outline of the rectangle, rounding
|
|
toward the center in unsmoothed mode.
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(draw-rounded-rectangle [x real?]
|
|
[y real?]
|
|
[width (and/c real? (not/c negative?))]
|
|
[height (and/c real? (not/c negative?))]
|
|
[radius real? -0.25])
|
|
void?]{
|
|
|
|
Draws a rectangle with the given top-left corner, and with the given
|
|
size. The corners are quarter-circles using the given radius. The
|
|
current pen is used for the outline and the current brush for filling
|
|
the shape.
|
|
|
|
If @scheme[radius] is positive, the value is used as the radius of the
|
|
rounded corner. If @scheme[radius] is negative, the absolute value is
|
|
used as the @italic{proportion} of the smallest dimension of the
|
|
rectangle.
|
|
|
|
If @scheme[radius] is less than @scheme[-0.5] or more than half of
|
|
@scheme[width] or @scheme[height], @|MismatchExn|.
|
|
|
|
If both the pen and brush are non-transparent, the rectangle is filled
|
|
with the brush before the outline is drawn with the pen. The filling
|
|
and outline meet so that no space is left between them, but the
|
|
precise overlap between the filling and outline is platform- and
|
|
size-specific. Thus, the regions drawn by the brush and pen may
|
|
partially overlap. More generally, the pen is centered over the
|
|
outline of the rounded rectangle, rounding toward the center in
|
|
unsmoothed mode.
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-spline [x1 real?]
|
|
[y1 real?]
|
|
[x2 real?]
|
|
[y2 real?]
|
|
[x3 real?]
|
|
[y3 real?])
|
|
void?]{
|
|
|
|
Draws a spline from (@scheme[x1], @scheme[y1]) to (@scheme[x3], @scheme[y3])
|
|
using (@scheme[x2], @scheme[y2]) as the control point.
|
|
|
|
See also @method[dc<%> set-smoothing] for information on the
|
|
@scheme['aligned] smoothing mode.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(draw-text [text string?]
|
|
[x real?]
|
|
[y real?]
|
|
[combine? any/c #f]
|
|
[offset nonnegative-exact-integer? 0]
|
|
[angle real? 0])
|
|
void?]{
|
|
|
|
Draws a text string at a specified point, using the current text font,
|
|
and the current text foreground and background colors. For unrotated
|
|
text, the specified point is used as the starting top-left point for
|
|
drawing characters (e.g, if ``W'' is drawn, the point is roughly the
|
|
location of the top-left pixel in the ``W''). Rotated text is rotated
|
|
around this point.
|
|
|
|
The @scheme[text] string is drawn starting from the @scheme[offset]
|
|
character, and continuing until the end of @scheme[text] or the first
|
|
null character.
|
|
|
|
If @scheme[combine?] is @scheme[#t], then @scheme[text] may be
|
|
measured with adjacent characters combined to ligature glyphs, with
|
|
Unicode combining characters as a single glyph, with kerning, with
|
|
right-to-left rendering of characters, etc. If @scheme[combine?] is
|
|
@scheme[#f], then the result is the same as if each character is
|
|
measured separately, and Unicode control characters are ignored.
|
|
|
|
The string is rotated by @scheme[angle] radians counter-clockwise. If
|
|
@scheme[angle] is not zero, then the text is always drawn in
|
|
transparent mode (see @method[dc<%> set-text-mode]).
|
|
|
|
The current brush and current pen settings for the DC have no effect
|
|
on how the text is drawn.
|
|
|
|
See @method[dc<%> get-text-extent] for information on the size of the
|
|
drawn text.
|
|
|
|
See also @method[dc<%> set-text-foreground], @method[dc<%>
|
|
set-text-background], and @method[dc<%> set-text-mode].
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(end-doc)
|
|
void?]{
|
|
|
|
Ends a document, relevant only when drawing to a printer or PostScript
|
|
device (including to a PostScript file).
|
|
|
|
For printer or PostScript output, an exception is raised if
|
|
@scheme[end-doc] is called when the document is not started with
|
|
@method[dc<%> start-doc], when a page is currently started by
|
|
@method[dc<%> start-page] and not ended with @method[dc<%> end-page],
|
|
or when the document has been ended already.
|
|
|
|
}
|
|
|
|
@defmethod[(end-page)
|
|
void?]{
|
|
|
|
Ends a single page, relevant only when drawing to a printer or
|
|
PostScript device (including to a PostScript file).
|
|
|
|
For printer or PostScript output, an exception is raised if
|
|
@scheme[end-page] is called when a page is not currently started by
|
|
@method[dc<%> start-page].
|
|
|
|
}
|
|
|
|
@defmethod[(get-alpha)
|
|
(real-in 0 1)]{
|
|
|
|
Gets the current opacity for drawing; see
|
|
@method[dc<%> set-alpha].
|
|
|
|
}
|
|
|
|
@defmethod[(get-background)
|
|
(is-a?/c color%)]{
|
|
|
|
Gets the color used for painting the background. See also
|
|
@method[dc<%> set-background].
|
|
|
|
}
|
|
|
|
@defmethod[(get-brush)
|
|
(is-a?/c brush%)]{
|
|
|
|
Gets the current brush. See also @method[dc<%> set-brush].
|
|
|
|
}
|
|
|
|
@defmethod[(get-char-height)
|
|
(and/c real? (not/c negative?))]{
|
|
|
|
Gets the height of a character using the current font.
|
|
|
|
Unlike most methods, this method can be called for a
|
|
@scheme[bitmap-dc%] object without a bitmap installed.
|
|
|
|
}
|
|
|
|
@defmethod[(get-char-width)
|
|
(and/c real? (not/c negative?))]{
|
|
|
|
Gets the average width of a character using the current font.
|
|
|
|
Unlike most methods, this method can be called for a
|
|
@scheme[bitmap-dc%] object without a bitmap installed.
|
|
|
|
}
|
|
|
|
@defmethod[(get-clipping-region)
|
|
(or/c (is-a?/c region%) false/c)]{
|
|
|
|
Gets the current clipping region, returning @scheme[#f] if the drawing
|
|
context is not clipped (i.e., the clipping region is the entire
|
|
drawing region).
|
|
|
|
}
|
|
|
|
@defmethod[(get-font)
|
|
(is-a?/c font%)]{
|
|
|
|
Gets the current font. See also @method[dc<%> set-font].
|
|
|
|
}
|
|
|
|
@defmethod[(get-gl-context)
|
|
(or/c (is-a?/c gl-context<%>) false/c)]{
|
|
|
|
Returns a @scheme[gl-context<%>] object for this drawing context
|
|
if it supports OpenGL, @scheme[#f] otherwise.
|
|
|
|
See @scheme[gl-context<%>] for more information.
|
|
|
|
}
|
|
|
|
@defmethod[(get-origin)
|
|
(values real? real?)]{
|
|
|
|
Returns the device origin, i.e., the location in device coordinates of
|
|
@math{(0,0)} in logical coordinates.
|
|
|
|
See also @method[dc<%> set-origin].
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(get-pen)
|
|
(is-a?/c pen%)]{
|
|
|
|
Gets the current pen. See also @method[dc<%> set-pen].
|
|
|
|
}
|
|
|
|
@defmethod[(get-scale)
|
|
(values real? real?)]{
|
|
|
|
Returns the scaling factor that maps logical coordinates to device
|
|
coordinates.
|
|
|
|
See also @method[dc<%> set-scale].
|
|
|
|
}
|
|
|
|
@defmethod[(get-size)
|
|
(values nonnegative-real? nonnegative-real?)]{
|
|
|
|
Gets the size of the destination drawing area. For a @scheme[dc<%>]
|
|
object obtained from a @scheme[canvas<%>], this is the (virtual
|
|
client) size of the destination window; for a @scheme[bitmap-dc%]
|
|
object, this is the size of the selected bitmap (or 0 if no bitmap is
|
|
selected); for a @scheme[post-script-dc%] or @scheme[printer-dc%]
|
|
drawing context, this gets the horizontal and vertical size of the
|
|
drawing area.
|
|
|
|
}
|
|
|
|
@defmethod[(get-smoothing)
|
|
(one-of/c 'unsmoothed 'smoothed 'aligned)]{
|
|
|
|
Returns the current smoothing mode. See @method[dc<%> set-smoothing].
|
|
|
|
}
|
|
|
|
@defmethod[(get-text-background)
|
|
(is-a?/c color%)]{
|
|
|
|
Gets the current text background color. See also @method[dc<%>
|
|
set-text-background].
|
|
|
|
}
|
|
|
|
@defmethod[(get-text-extent [string string?]
|
|
[font (or/c (is-a?/c font%) false/c) #f]
|
|
[combine? any/c #f]
|
|
[offset nonnegative-exact-integer? 0])
|
|
(values nonnegative-real?
|
|
nonnegative-real?
|
|
nonnegative-real?
|
|
nonnegative-real?)]{
|
|
|
|
|
|
Returns the size of @scheme[str] at it would be drawn in the drawing
|
|
context, starting from the @scheme[offset] character of @scheme[str],
|
|
and continuing until the end of @scheme[str] or the first null
|
|
character. The @scheme[font] argument specifies the font to use in
|
|
measuring the text; if it is @scheme[#f], the current font of the
|
|
drawing area is used. (See also @method[dc<%> set-font].)
|
|
|
|
The result is four real numbers:
|
|
|
|
@itemize{
|
|
|
|
@item{the total width of the text (depends on both the font and the
|
|
text);}
|
|
|
|
@item{the total height of the font (depends only on the font);}
|
|
|
|
@item{the distance from the baseline of the font to the bottom of the
|
|
descender (included in the height, depends only on the font); and}
|
|
|
|
@item{extra vertical space added to the font by the font designer
|
|
(included in the height, and often zero; depends only on the font).}
|
|
|
|
}
|
|
|
|
The returned width and height define a rectangle is that guaranteed to
|
|
contain the text string when it is drawn, but the fit is not
|
|
necessarily tight. Some undefined number of pixels on the left,
|
|
right, top, and bottom of the drawn string may be ``whitespace,''
|
|
depending on the whims of the font designer and the platform-specific
|
|
font-scaling mechanism.
|
|
|
|
If @scheme[combine?] is @scheme[#t], then @scheme[text] may be drawn
|
|
with adjacent characters combined to ligature glyphs, with Unicode
|
|
combining characters as a single glyph, with kerning, with
|
|
right-to-left ordering of characters, etc. If @scheme[combine?] is
|
|
@scheme[#f], then the result is the same as if each character is
|
|
drawn separately, and Unicode control characters are ignored.
|
|
|
|
Unlike most methods, this method can be called for a
|
|
@scheme[bitmap-dc%] object without a bitmap installed.
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(get-text-foreground)
|
|
(is-a?/c color%)]{
|
|
|
|
Gets the current text foreground color. See also @method[dc<%>
|
|
set-text-foreground].
|
|
|
|
}
|
|
|
|
@defmethod[(get-text-mode)
|
|
(one-of/c 'solid 'transparent)]{
|
|
Reports how text is drawn; see
|
|
@method[dc<%> set-text-mode] .
|
|
|
|
}
|
|
|
|
@defmethod[(glyph-exists? [c char]
|
|
[font (or/c (is-a?/c font%) false/c) #f])
|
|
boolean?]{
|
|
|
|
Returns @scheme[#t] if the given character has a corresponding glyph
|
|
for this drawing context, @scheme[#f] otherwise.
|
|
|
|
Due to automatic font substitution when drawing or measuring text, the
|
|
result of this method does not depend on the given font, which merely
|
|
provides a hint for the glyph search. If the font is @scheme[#f], the
|
|
drawing context's current font is used. The result depends on the
|
|
type of the drawing context, but the result for @scheme[canvas%]
|
|
@scheme[dc<%>] instances and @scheme[bitmap-dc%] instances is always
|
|
the same for a given platform and a given set of installed fonts.
|
|
|
|
See also @method[font% screen-glyph-exists?] .
|
|
|
|
}
|
|
|
|
@defmethod[(ok?)
|
|
boolean?]{
|
|
|
|
Returns @scheme[#t] if the drawing context is usable.
|
|
|
|
}
|
|
|
|
@defmethod[(set-alpha [opacity (real-in 0 1)])
|
|
void?]{
|
|
|
|
Determines the opacity of drawing, under certain conditions:
|
|
|
|
@itemize{
|
|
|
|
@item{pen- and brush-based drawing when @method[dc<%> get-smoothing]
|
|
produces @scheme['smoothed] or @scheme['aligned], and when the
|
|
drawing context is not an instance of @scheme[post-script-dc%];
|
|
and}
|
|
|
|
@item{text drawing for most platforms (Mac OS X, X with
|
|
Xft/fontconfig; transparency approximated under Windows by
|
|
fading the drawing color), and when the drawing context is not
|
|
an instance of @scheme[post-script-dc].}
|
|
|
|
}
|
|
|
|
A value of @scheme[0.0] corresponds to completely transparent (i.e.,
|
|
invisible) drawing, and @scheme[1.0] corresponds to completely opaque
|
|
drawing. For intermediate values, drawing is blended with the existing
|
|
content of the drawing context.}
|
|
|
|
@defmethod[(set-background [color (is-a?/c color%)])
|
|
void?]{
|
|
|
|
Sets the background color for drawing in this object (e.g., using
|
|
@method[dc<%> clear] or using a stippled @scheme[brush%] with the mode
|
|
@scheme['opaque]). For monochrome drawing, all non-black colors are
|
|
treated as white.
|
|
|
|
}
|
|
|
|
@defmethod*[([(set-brush [brush (is-a?/c brush%)])
|
|
void?]
|
|
[(set-brush [color (is-a?/c color%)]
|
|
[style (one-of/c 'transparent 'solid 'opaque
|
|
'xor 'hilite 'panel
|
|
'bdiagonal-hatch 'crossdiag-hatch
|
|
'fdiagonal-hatch 'cross-hatch
|
|
'horizontal-hatch 'vertical-hatch)])
|
|
void?]
|
|
[(set-brush [color-name string?]
|
|
[style (one-of/c 'transparent 'solid 'opaque
|
|
'xor 'hilite 'panel
|
|
'bdiagonal-hatch 'crossdiag-hatch
|
|
'fdiagonal-hatch 'cross-hatch
|
|
'horizontal-hatch 'vertical-hatch)])
|
|
void?])]{
|
|
|
|
Sets the current brush for drawing in this object. While a brush is
|
|
selected into a drawing context, it cannot be modified. When a color
|
|
and style are given, the arguments are as for @xmethod[brush-list%
|
|
find-or-create-brush].
|
|
|
|
}
|
|
|
|
|
|
@defmethod[(set-clipping-rect [x real?]
|
|
[y real?]
|
|
[width (and/c real? (not/c negative?))]
|
|
[height (and/c real? (not/c negative?))])
|
|
void?]{
|
|
|
|
Sets the clipping region to a rectangular region.
|
|
|
|
See also @method[dc<%> set-clipping-region] and @method[dc<%>
|
|
get-clipping-region].
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(set-clipping-region [rgn (or/c (is-a?/c region%) false/c)])
|
|
void?]{
|
|
|
|
Sets the clipping region for the drawing area, turning off all
|
|
clipping within the drawing region if @scheme[#f] is provided.
|
|
|
|
The clipping region must be reset after changing a @scheme[dc<%>]
|
|
object's origin or scale (unless it is @scheme[#f]); see
|
|
@scheme[region%] for more information.
|
|
|
|
See also @method[dc<%> set-clipping-rect] and @method[dc<%>
|
|
get-clipping-region].
|
|
|
|
}
|
|
|
|
@defmethod[(set-font [font (is-a?/c font%)])
|
|
void?]{
|
|
|
|
Sets the current font for drawing text in this object.
|
|
|
|
}
|
|
|
|
@defmethod[(set-origin [x real?]
|
|
[y real?])
|
|
void?]{
|
|
|
|
Sets the device origin, i.e., the location in device coordinates of
|
|
@math{(0,0)} in logical coordinates.
|
|
|
|
Changing a @scheme[dc<%>] object's origin or scale does not affect
|
|
@scheme[region%] objects that were previously created. See
|
|
@scheme[region%] for more information.
|
|
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod*[([(set-pen [pen (is-a?/c pen%)])
|
|
void?]
|
|
[(set-pen [color (is-a?/c color%)]
|
|
[width (real-in 0 255)]
|
|
[style (one-of/c 'transparent 'solid 'xor 'hilite
|
|
'dot 'long-dash 'short-dash 'dot-dash
|
|
'xor-dot 'xor-long-dash 'xor-short-dash
|
|
'xor-dot-dash)])
|
|
void?]
|
|
[(set-pen [color-name string?]
|
|
[width (real-in 0 255)]
|
|
[style (one-of/c 'transparent 'solid 'xor 'hilite
|
|
'dot 'long-dash 'short-dash 'dot-dash
|
|
'xor-dot 'xor-long-dash 'xor-short-dash
|
|
'xor-dot-dash)])
|
|
void?])]{
|
|
|
|
Sets the current pen for this object. When a color, width, and style
|
|
are given, the arguments are as for @xmethod[pen-list%
|
|
find-or-create-pen].
|
|
|
|
The current pen does not affect text drawing; see also @method[dc<%>
|
|
set-text-foreground].
|
|
|
|
While a pen is selected into a drawing context, it cannot be modified.
|
|
|
|
}
|
|
|
|
@defmethod[(set-scale [x-scale (and/c real? (not/c negative?))]
|
|
[y-scale (and/c real? (not/c negative?))])
|
|
void?]{
|
|
|
|
Sets a scaling factor that maps logical coordinates to device coordinates.
|
|
|
|
Changing a @scheme[dc<%>] object's origin or scale does not affect
|
|
@scheme[region%] objects that were previously created. See
|
|
@scheme[region%] for more information.
|
|
|
|
@|DrawSizeNote|
|
|
|
|
}
|
|
|
|
@defmethod[(set-smoothing [mode (one-of/c 'unsmoothed 'smoothed 'aligned)])
|
|
void?]{
|
|
|
|
Enables or disables anti-aliased smoothing of lines, curves,
|
|
rectangles, rounded rectangles, ellipses, polygons, paths, and clear
|
|
operations. (Text smoothing is not affected by this method, and is
|
|
instead controlled through the @scheme[font%] object.)
|
|
|
|
Smoothing is supported under Windows only when Microsoft's
|
|
@filepath{gdiplus.dll} is installed (which is always the case for Windows
|
|
XP). Smoothing is supported under Mac OS X always. Smoothing is
|
|
supported under X only when Cairo is installed when MrEd is compiled.
|
|
Smoothing is never supported for black-and-white contexts. Smoothing
|
|
is always supported (and cannot be disabled) for PostScript output.
|
|
|
|
The smoothing mode is either @scheme['unsmoothed], @scheme['smoothed],
|
|
or @scheme['aligned]. Both @scheme['aligned] and @scheme['smoothed]
|
|
are smoothing modes.
|
|
|
|
In @scheme['smoothed] mode for a canvas or bitmap drawing context,
|
|
integer drawing coordinates correspond to the boundary between
|
|
pixels, and pen-based drawing is centered over a given line or
|
|
curve. Thus, drawing with pen width @scheme[1] from @math{(0, 10)} to
|
|
@math{(10, 10)} draws a 2-pixel wide line with @math{50%} opacity.
|
|
|
|
The @scheme['aligned] smoothing mode is like @scheme['smoothed], but
|
|
it paints pixels more like @scheme['unsmoothed] mode. Since it aligns
|
|
shapes to pixel boundaries, @scheme['aligned] mode often produces
|
|
better results than @scheme['smoothed], but the results depend on the
|
|
application. The @scheme['aligned] mode is defined in terms of
|
|
@scheme['smoothed] mode, except that drawing coordinates are rounded
|
|
down (via @scheme[floor], after scaling and origin translation). For
|
|
line drawing, coordinates are then shifted right and down by the
|
|
@scheme[floor] of half a pen width. In addition, for pen drawing
|
|
through @method[dc<%> draw-rectangle], @method[dc<%> draw-ellipse],
|
|
@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%)])
|
|
void?]{
|
|
|
|
Sets the current text background color for this object. The text
|
|
background color is painted behind text that is drawn with
|
|
@method[dc<%> draw-text], but only for the @scheme['solid] text mode
|
|
(see @method[dc<%> set-text-mode]).
|
|
|
|
For monochrome drawing, all non-white colors are treated as black.
|
|
|
|
}
|
|
|
|
@defmethod[(set-text-foreground [color (is-a?/c color%)])
|
|
void?]{
|
|
|
|
Sets the current text foreground color for this object, used for
|
|
drawing text with
|
|
@method[dc<%> draw-text].
|
|
|
|
For monochrome drawing, all non-black colors are treated as
|
|
white.
|
|
|
|
}
|
|
|
|
@defmethod[(set-text-mode [mode (one-of/c 'solid 'transparent)])
|
|
void?]{
|
|
|
|
Determines how text is drawn:
|
|
|
|
@itemize{
|
|
|
|
@item{@scheme['solid] --- Before text is drawn, the destination area
|
|
is filled with the text background color (see @method[dc<%>
|
|
set-text-background]).}
|
|
|
|
@item{@scheme['transparent] --- Text is drawn directly over any
|
|
existing image in the destination, as if overlaying text
|
|
written on transparent film.}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
@defmethod[(start-doc [message string?])
|
|
boolean?]{
|
|
|
|
Starts a document, relevant only when drawing to a printer or
|
|
PostScript device (including to a PostScript file). For some
|
|
platforms, the @scheme[message] string is displayed in a dialog until
|
|
@method[dc<%> end-doc] is called.
|
|
|
|
For printer or PostScript output, an exception is raised if
|
|
@scheme[start-doc] has been called already (even if @method[dc<%>
|
|
end-doc] has been called as well). Furthermore, drawing methods raise
|
|
an exception if not called while a page is active as determined by
|
|
@method[dc<%> start-doc] and @method[dc<%> start-page].
|
|
|
|
}
|
|
|
|
@defmethod[(start-page)
|
|
void?]{
|
|
|
|
Starts a page, relevant only when drawing to a printer or PostScript
|
|
device (including to a PostScript file).
|
|
|
|
For printer or PostScript output, an exception is raised if
|
|
@scheme[start-doc] is called when a page is already started, or when
|
|
@method[dc<%> start-doc] has not been called, or when @method[dc<%>
|
|
end-doc] has been called already. In addition, in the case of
|
|
PostScript output, Encapsulated PostScript (EPS) cannot contain
|
|
multiple pages, so calling @scheme[start-page] a second time for a
|
|
@scheme[post-script-dc%] instance raises an exception; to create
|
|
PostScript output with multiple pages, supply @scheme[#f] as the
|
|
@scheme[as-eps] initialization argument for @scheme[post-script-dc%].
|
|
|
|
}
|
|
|
|
@defmethod[(try-color [try (is-a?/c color%)]
|
|
[result (is-a?/c color%)])
|
|
void?]{
|
|
|
|
Determines the actual color used for drawing requests with the given
|
|
color. The @scheme[result] color is set to the RGB values that are
|
|
actually produced for this drawing context to draw the color
|
|
@scheme[try].
|
|
|
|
}}
|