dc<%> : interface?

A 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 draw-rectangle, accept real number values as arguments, but the results are only well-defined when the drawing coordinates are in the range -16383 to 16383. This restriction applies to the coordinates both before and after offsets and scaling factors are applied.

(send a-dc clear) → void?

Clears the drawing region (fills it with the current background color, as determined by get-background).

(send a-dc draw-arc   x             y             width             height             start-radians             end-radians)   →   void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

start-radians : real?

end-radians : real?

Draws a counter-clockwise circular arc, a part of the ellipse inscribed in the rectangle specified by x (left), y (top), width, and height. The arc starts at the angle specified by start-radians (0 is three o’clock and half-pi is twelve o’clock) and continues counter-clockwise to end-radians. If start-radians and 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.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-bitmap   source             dest-x             dest-y            [ style             color             mask])   →   boolean?

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

Displays a bitmap. The dest-x and dest-y arguments are in DC coordinates.

For color bitmaps, the drawing style and color arguments are ignored. For monochrome bitmaps, 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 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 ok? must return true, otherwise an exn:fail:contract exception is raised. The bitmap to draw and the mask bitmap can be the same object, but if the drawing context is a bitmap-dc% object, both bitmaps must be distinct from the destination bitmap, otherwise an exn:fail:contract exception is raised.

If the mask bitmap is monochrome, drawing occurs in the target 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 "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 post-script-dc% output, the mask bitmap is currently ignored, and the 'solid style is treated the same as 'opaque. (However, mask bitmaps and 'solid drawing may become supported for post-script-dc% in the future.)

The result is #t if the bitmap is successfully drawn, #f otherwise (possibly because the bitmap’s ok? method returns #f).

See also draw-bitmap-section.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-bitmap-section   source             dest-x             dest-y             src-x             src-y             src-width             src-height            [ style             color             mask])   →   boolean?

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

Displays part of a bitmap.

The src-x, src-y, src-width, and src-height arguments specify a rectangle in the source bitmap to copy into this drawing context.

See draw-bitmap for information about dest-x, dest-y, style, color, and mask.

(send a-dc draw-ellipse x y width height) → void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

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.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-line x1 y1 x2 y2) → void?

x1 : real?

y1 : real?

x2 : real?

y2 : real?

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 1, the line is drawn centered over the start and end points.

See also set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-lines   points            [ xoffset             yoffset])   →   void?

points : (listof (is-a?/c point%))

xoffset : real? = 0

yoffset : real? = 0

Draws lines using a list of points, adding xoffset and yoffset to each point. The current pen is used for drawing the lines.

See also set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-path   path            [ xoffset             yoffset             fill-style])   →   void?

path : (is-a?/c dc-path%)

xoffset : real? = 0

yoffset : real? = 0

fill-style : (one-of/c 'odd-even 'winding) = 'odd-even

Draws the sub-paths of the given dc-path% object, adding xoffset and yoffset to each point. (See dc-path% for general information on paths and sub-paths.) 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 fill-style argument specifies the fill rule: 'odd-even or 'winding. In 'odd-even mode, a point is considered enclosed within the path if it is enclosed by an odd number of sub-path loops. In '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 'winding fill rule is not supported under Mac OS X and it is not supported when path contains multiple sub-paths; the 'winding fill rules is always supported when smoothing is enabled (see set-smoothing).

See also set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-point x y) → void?

x : real?

y : real?

Plots a single point using the current pen.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-polygon   points            [ xoffset             yoffset             fill-style])   →   void?

points : (listof (is-a?/c point%))

xoffset : real? = 0

yoffset : real? = 0

fill-style : (one-of/c 'odd-even 'winding) = 'odd-even

Draw a filled polygon using a list of points, adding xoffset and 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 fill-style argument specifies the fill rule: 'odd-even or 'winding. In 'odd-even mode, a point is considered enclosed within the polygon if it is enclosed by an odd number of loops. In '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 'winding fill rule is not supported under Mac OS X, except when smoothing is enabled (see set-smoothing).

See also set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-rectangle x y width height) → void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

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 'xor pen% and an 'xor 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 set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-rounded-rectangle   x             y             width             height            [ radius])   →   void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

radius : real? = -0.25

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 radius is positive, the value is used as the radius of the rounded corner. If radius is negative, the absolute value is used as the proportion of the smallest dimension of the rectangle.

If radius is less than -0.5 or more than half of width or height, an exn:fail:contract exception is raised.

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 set-smoothing for information on the 'aligned smoothing mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-spline x1 y1 x2 y2 x3 y3) → void?

x1 : real?

y1 : real?

x2 : real?

y2 : real?

x3 : real?

y3 : real?

Draws a spline from (x1, y1) to (x3, y3) using (x2, y2) as the control point.

See also set-smoothing for information on the 'aligned smoothing mode. See also dc-path% and draw-path for drawing more complex curves.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc draw-text   text             x             y            [ combine?             offset             angle])   →   void?

text : string?

x : real?

y : real?

combine? : any/c = #f

offset : exact-nonnegative-integer? = 0

angle : real? = 0

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 text string is drawn starting from the offset character, and continuing until the end of text or the first null character.

If combine? is #t, then 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 combine? is #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 angle radians counter-clockwise. If angle is not zero, then the text is always drawn in transparent mode (see set-text-mode).

The current brush and current pen settings for the DC have no effect on how the text is drawn.

See get-text-extent for information on the size of the drawn text.

See also set-text-foreground, set-text-background, and set-text-mode.

Restrictions on the magnitude of drawing coordinates are described with dc<%>.

(send a-dc 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 end-doc is called when the document is not started with start-doc, when a page is currently started by start-page and not ended with end-page, or when the document has been ended already.

(send a-dc 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 end-page is called when a page is not currently started by start-page.

(send a-dc get-alpha) → (real-in 0 1)

Gets the current opacity for drawing; see set-alpha.

(send a-dc get-background) → (is-a?/c color%)

Gets the color used for painting the background. See also set-background.

(send a-dc get-brush) → (is-a?/c brush%)

Gets the current brush. See also set-brush.

(send a-dc 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 bitmap-dc% object without a bitmap installed.

(send a-dc 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 bitmap-dc% object without a bitmap installed.

(send a-dc get-clipping-region)

→ (or/c (is-a?/c region%) false/c)

Gets the current clipping region, returning #f if the drawing context is not clipped (i.e., the clipping region is the entire drawing region).

(send a-dc get-font) → (is-a?/c font%)

Gets the current font. See also set-font.

(send a-dc get-gl-context)

→ (or/c (is-a?/c gl-context<%>) false/c)

Returns a gl-context<%> object for this drawing context if it supports OpenGL, #f otherwise.

See gl-context<%> for more information.

(send a-dc get-origin)   →   real?   real?

Returns the device origin, i.e., the location in device coordinates of (0,0) in logical coordinates.

See also set-origin.

(send a-dc get-pen) → (is-a?/c pen%)

Gets the current pen. See also set-pen.

(send a-dc get-scale)   →   real?   real?

Returns the scaling factor that maps logical coordinates to device coordinates.

See also set-scale.

(send a-dc get-size)   →   nonnegative-real?   nonnegative-real?

Gets the size of the destination drawing area. For a dc<%> object obtained from a canvas<%>, this is the (virtual client) size of the destination window; for a bitmap-dc% object, this is the size of the selected bitmap (or 0 if no bitmap is selected); for a post-script-dc% or printer-dc% drawing context, this gets the horizontal and vertical size of the drawing area.

(send a-dc get-smoothing)

→ (one-of/c 'unsmoothed 'smoothed 'aligned)

Returns the current smoothing mode. See set-smoothing.

(send a-dc get-text-background) → (is-a?/c color%)

Gets the current text background color. See also set-text-background.

(send a-dc get-text-extent   string            [ font             combine?             offset])   →   nonnegative-real? nonnegative-real? nonnegative-real? nonnegative-real?

string :