8 dc<%>

▼ |  | The Racket Drawing Toolkit

1 | Overview
2 | bitmap%
3 | bitmap-dc%
4 | brush%
5 | brush-list%
6 | color%
7 | color-database<%>
8 | dc<%>
9 | dc-path%
10 | font%
11 | font-list%
12 | font-name-directory<%>
13 | gl-config%
14 | gl-context<%>
15 | linear-gradient%
16 | pdf-dc%
17 | pen%
18 | pen-list%
19 | point%
20 | post-script-dc%
21 | ps-setup%
22 | radial-gradient%
23 | record-dc%
24 | region%
25 | svg-dc%
26 | Drawing Functions
27 | Drawing Contracts
28 | Signature and Unit
29 | Unsafe Libraries
30 | Drawing Conveniences
31 | Platform Dependencies
| Bibliography
| Index

On this page:

cache-font-metrics-key
clear
copy
draw-arc
draw-bitmap
draw-bitmap-section
draw-ellipse
draw-line
draw-lines
draw-path
draw-point
draw-polygon
draw-rectangle
draw-rounded-rectangle
draw-spline
draw-text
end-doc
end-page
erase
flush
get-alpha
get-background
get-backing-scale
get-brush
get-char-height
get-char-width
get-clipping-region
get-device-scale
get-font
get-gl-context
get-initial-matrix
get-origin
get-pen
get-path-bounding-box
get-rotation
get-scale
get-size
get-smoothing
get-text-background
get-text-extent
get-text-foreground
get-text-mode
get-transformation
glyph-exists?
ok?
resume-flush
rotate
scale
set-alignment-scale
set-alpha
set-background
set-brush
set-clipping-rect
set-clipping-region
set-font
set-initial-matrix
set-origin
set-pen
set-rotation
set-scale
set-smoothing
set-text-background
set-text-foreground
set-text-mode
set-transformation
start-doc
start-page
suspend-flush
transform
translate
try-color

top contents ← prev up next →

interface 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.

> method (send a-dc cache-font-metrics-key) → exact-integer?

Returns an integer that, if not 0, corresponds to a particular kind of device and scaling factor, such that text-extent information (from get-text-extent, get-char-height, etc.) is the same. The key is valid across all dc<%> instances, even among different classes.

A 0 result indicates that the current configuration of a-dc does not fit into a common category, and so no key is available for caching text-extent information.

> method (send a-dc clear) → void?

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

> method (send a-dc copy x y width height x2 y2) → void?
> x : real?
> y : real?
> width : (and/c real? (not/c negative?))
> height : (and/c real? (not/c negative?))
> x2 : real?
> y2 : real?

Copies the rectangle defined by x, y, width, and height of the drawing context to the same drawing context at the position specified by x2 and y2. The source and destination regions can overlap.

Changed in version 1.12 of package draw-lib: Allow overlapping source and destination.

> > method
> > (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. In unsmoothed or aligned mode, the path for the outline is adjusted by shrinking the bounding ellipse width and height by, after scaling, one drawing unit divided by the alignment scale.

> > method
> > (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 : (or/c 'solid 'opaque 'xor) = 'solid
> | color |  | : |  | (is-a?/c color%)
> |  |  | = |  | (send the-color-database find-color "black")
> mask : (or/c (is-a?/c bitmap%) #f) = #f

Displays the source 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 source, and its ok? must return true, otherwise an exn:fail:contract exception is raised. The source bitmap and 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.

The effect of mask on drawing depends on the type of the mask bitmap:

- If the mask bitmap is monochrome, drawing occurs in the target dc<%> only where the mask bitmap contains black pixels (independent of style, which controls how the white pixels of a monochrome source are handled).

- If the mask bitmap is color with an alpha channel, its alpha channel is used as the mask for drawing source, and its color channels are ignored.

- If the mask bitmap is color without an alpha channel, the color components of a given pixel are averaged to arrive at an inverse alpha value for the pixel. In particular, if the 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).

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 source, any given mask, and the alpha component of color when source is monochrome).

For post-script-dc% and pdf-dc% output, opacity from an alpha channel in source, from mask, or from color is rounded to full transparency or opacity.

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.

> > method
> > (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 : (or/c 'solid 'opaque 'xor) = 'solid
> | color |  | : |  | (is-a?/c color%)
> |  |  | = |  | (send the-color-database find-color "black")
> mask : (or/c (is-a?/c bitmap%) #f) = #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.

> method (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.

Brush filling and pen 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. In unsmoothed or aligned mode, the path for the outline is adjusted by, after scaling, shrinking the ellipse width and height by one drawing unit divided by the alignment scale.

> method (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.

> > method
> > (send a-dc draw-lines |  | points |  |  |  |
> > | [ | xoffset |  |  |  |
> > |  | yoffset]) |  | → |  | void?
> | points |  | : |  |
> (or/c (listof (is-a?/c point%))
> (listof (cons/c real? real?)))
> xoffset : real? = 0
> yoffset : real? = 0

Draws lines using a list points of points, adding xoffset and yoffset to each point and using the pen’s join style to connect a line and the next line at the shared point. A pair is treated as a point where the car of the pair is the x-value and the cdr is the y-value. The current pen is used for drawing the lines.

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

> > method
> > (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 : (or/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.

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

> method (send a-dc draw-point x y) → void?
> x : real?
> y : real?

Plots a single point using the current pen.

> > method
> > (send a-dc draw-polygon |  | points |  |  |  |
> > | [ | xoffset |  |  |  |
> > |  | yoffset |  |  |  |
> > |  | fill-style]) |  | → |  | void?
> | points |  | : |  |
> (or/c (listof (is-a?/c point%))
> (listof (cons/c real? real?)))
> xoffset : real? = 0
> yoffset : real? = 0
> fill-style : (or/c 'odd-even 'winding) = 'odd-even

Draw a filled polygon using a list points of points, adding xoffset and yoffset to each point. A pair is treated as a point where the car of the pair is the x-value and the cdr is the y-value. 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.

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

> method (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 or aligned mode, when the pen is size 0 or 1, the filling precisely overlaps the entire outline. More generally, in unsmoothed or aligned mode, the path for the outline is adjusted by shrinking the rectangle width and height by, after scaling, one drawing unit divided by the alignment scale.

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

> > method
> > (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 both the pen and brush are non-transparent, the rectangle is filled with the brush before the outline is drawn with the pen.

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.

Brush filling and pen 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. In unsmoothed or aligned mode, the path for the outline is adjusted by, after scaling, shrinking the rectangle width and height by one drawing unit divided by the alignment scale.

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

> method (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.

> > method
> > (send a-dc draw-text |  | text |  |  |  |
> > |  | x |  |  |  |
> > |  | y |  |  |  |
> > | [ | combine-mode |  |  |  |
> > |  | offset |  |  |  |
> > |  | angle]) |  | → |  | void?
> text : string?
> x : real?
> y : real?
> combine-mode : 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-mode is #f, then the result is the same as if each character is drawn separately, and Unicode control characters are ignored. If combine-mode is 'grapheme, then the result is the same as if each Unicode grapheme cluster is drawn separately, but multiple characters of text that form a grapheme cluster may be drawn as a single glyph. Otherwise, for combine-mode as any true value except 'grapheme, text may be drawn with adjacent characters combined to form ligature glyphs, with Unicode combining characters as a single glyph, with kerning, with right-to-left rendering of characters, etc.

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.

Changed in version 1.20 of package draw-lib: Changed to treat combine-mode as 'graheme different than other true values.

> method (send a-dc end-doc) → void?

Ends a document, relevant only when drawing to a printer, PostScript, PDF, or SVG device.

For relevant devices, 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.

> method (send a-dc end-page) → void?

Ends a single page, relevant only when drawing to a printer, PostScript, PDF, or SVG device.

For relevant devices, an exception is raised if end-page is called when a page is not currently started by start-page.

> method (send a-dc erase) → void?

For a drawing context that has an alpha channel, erase sets all alphas to zero. Similarly, for a transparent canvas, erase erases all drawing to allow the background window to show through. For other drawing contexts that have no alpha channel or transparency, erase fills the drawing context with white.

> method (send a-dc flush) → void?

Calls the flush in canvas<%> method for canvas<%> output, and has no effect for other kinds of drawing contexts.

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

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

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

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

> method (send a-dc get-backing-scale) → (>/c 0.0)

Returns the backing scale of the drawing context’s destination.

Added in version 1.12 of package draw-lib.

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

Gets the current brush. See also set-brush.

> method (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.

> method (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.

> method (send a-dc get-clipping-region) → (or/c (is-a?/c region%) #f)

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

> > method
> > (send a-dc get-device-scale) |  | → |  |
> > (and/c real? (not/c negative?))
> > (and/c real? (not/c negative?))

Gets an “external” scaling factor for drawing coordinates to the target device. For most DCs, the result is 1.0 and 1.0.

A post-script-dc% or pdf-dc% object returns scaling factors determined via get-scaling in ps-setup% at the time that the DC was created. A printer-dc% may also have a user-configured scaling factor.

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

Gets the current font. See also set-font.

> method (send a-dc get-gl-context) → (or/c (is-a?/c gl-context<%>) #f)

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

See gl-context<%> for more information.

> method (send a-dc get-initial-matrix)
> → (vector/c real? real? real? real? real? real?)

Returns a transformation matrix that converts logical coordinates to device coordinates. The matrix applies before additional origin offset, scaling, and rotation.

The vector content corresponds to a transformation matrix in the following order:

- xx: a scale from the logical x to the device x

- yx: a scale from the logical y added to the device x

- xy: a scale from the logical x added to the device y

- yy: a scale from the logical y to the device y

- x0: an additional amount added to the device x

- y0: an additional amount added to the device y

See also set-initial-matrix and get-transformation.

> > method
> > (send a-dc get-origin) |  | → |  |
> > real? |  | real?

Returns the device origin, i.e., the location in device coordinates of (0,0) in logical coordinates. The origin offset applies after the initial transformation matrix, but before scaling and rotation.

See also set-origin and get-transformation.

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

Gets the current pen. See also set-pen.

> method (send a-dc get-path-bounding-box path type)
> | → |  |
> real? |  | real? |  | real? |  | real?
> path : (is-a?/c dc-path%)
> type : (or/c 'path 'stroke 'fill)

Returns a rectangle that encloses the path’s points. The return values are the left, top, width, and, height of the rectangle. The numbers are in logical coordinates.

For the type 'stroke the rectangle covers the area that would be affected (“inked”) when drawn with the current pen by draw-path in the drawing context (with a transparent brush). If the pen width is zero, then an empty rectangle will be returned. The size and clipping of the drawing context is ignored.

For the type 'fill the rectangle covers the area that would be affected (“inked”) by draw-path in the drawing context (with a non-transparent pen and brush). If the line width is zero, then an empty rectangle will be returned. The size and clipping of the drawing context are ignored.

For the type 'path the rectangle covers the path, but the pen and brush are ignored. The size and clipping of the drawing context are also ignored. More precisely: The result is defined as the limit of the bounding boxes returned by the 'stroke type for line widths approaching 0 with a round pen cap. The “limit process” stops when an empty rectangle is returned. This implies that zero-area segments contributes to the rectangle.

For all types if the path is empty, then an empty rectangle (values 0 0 0 0) will be returned.

> method (send a-dc get-rotation) → real?

Returns the rotation of logical coordinates in radians to device coordinates. Rotation applies after the initial transformation matrix, origin offset, and scaling.

See also set-rotation and get-transformation.

> > method
> > (send a-dc get-scale) |  | → |  |
> > real? |  | real?

Returns the scaling factor that maps logical coordinates to device coordinates. Scaling applies after the initial transformation matrix and origin offset, but before rotation.

See also set-scale and get-transformation.

> > method
> > (send a-dc get-size) |  | → |  |
> > (and/c real? (not/c negative?))
> > (and/c real? (not/c negative?))

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.

> method (send a-dc get-smoothing)
> → (or/c 'unsmoothed 'smoothed 'aligned)

Returns the current smoothing mode. See set-smoothing.

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

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

> > method
> > (send a-dc get-text-extent |  | string |
> > | [ | font |
> > |  | combine-mode |
> > |  | offset]) |
> | → |  |
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> (and/c real? (not/c negative?))
> string : string?
> font : (or/c (is-a?/c font%) #f) = #f
> combine-mode : any/c = #f
> offset : exact-nonnegative-integer? = 0

Returns the size of str as it would be drawn in the drawing context, starting from the offset character of str, and continuing until the end of str or the first null character. The font argument specifies the font to use in measuring the text; if it is #f, the current font of the drawing area is used. (See also set-font.)

The result is four real numbers:

- the total width of the text (depends on both the font and the text);

- the total height of the font (depends only on the font);

- the distance from the baseline of the font to the bottom of the descender (included in the height, depends only on the font); and

- 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 combine-mode is #f, then the result is the same as if each character is measured separately, and Unicode control characters are ignored. If combine-mode is 'grapheme, then the result is the same as if each Unicode grapheme cluster is measured separately, but multiple characters of text that form a grapheme cluster may be measured as a single glyph. Otherwise, for combine-mode as any true value except 'grapheme, text may be measured with adjacent characters combined to form ligature glyphs, with Unicode combining characters as a single glyph, with kerning, with right-to-left rendering of characters, etc.

Unlike most methods, this method can be called for a bitmap-dc% object without a bitmap installed.

Examples:

> > (define text-size-dc (new bitmap-dc% [bitmap (make-object bitmap% 1 1)]))
> > (send text-size-dc get-text-extent "Pickles")
> 54.0
> 19.0
> 4.0
> 0.0

Changed in version 1.20 of package draw-lib: Changed to treat combine-mode as 'graheme different than other true values.

> method (send a-dc get-text-foreground) → (is-a?/c color%)

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

> method (send a-dc get-text-mode) → (or/c 'solid 'transparent)

Reports how text is drawn; see set-text-mode.

> method (send a-dc get-transformation)
> | → |  |
> (vector/c (vector/c real? real? real? real? real? real?)
> real? real? real? real? real?)

Returns the current transformation setting of the drawing context in a form that is suitable for restoration via set-transformation.

The vector content is as follows:

- the initial transformation matrix; see get-initial-matrix;

- the X and Y origin; see get-origin;

- the X and Y scale; see get-origin;

- a rotation; see get-rotation.

> method (send a-dc glyph-exists? c) → boolean?
> c : char?

Returns #t if the given character has a corresponding glyph for this drawing context, #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 #f, the drawing context’s current font is used. The result depends on the type of the drawing context, but the result for canvas% dc<%> instances and bitmap-dc% instances is always the same for a given platform and a given set of installed fonts.

See also screen-glyph-exists? .

> method (send a-dc ok?) → boolean?

Returns #t if the drawing context is usable.

> method (send a-dc resume-flush) → void?

Calls the resume-flush in canvas<%> method for canvas<%> output, and has no effect for other kinds of drawing contexts.

> method (send a-dc rotate angle) → void?
> angle : real?

Adds a rotation of angle radians to the drawing context’s current transformation.

Afterward, the drawing context’s transformation is represented in the initial transformation matrix, and the separate origin, scale, and rotation settings have their identity values.

> method (send a-dc scale x-scale y-scale) → void?
> x-scale : real?
> y-scale : real?

Adds a scaling of x-scale in the X-direction and y-scale in the Y-direction to the drawing context’s current transformation.

Afterward, the drawing context’s transformation is represented in the initial transformation matrix, and the separate origin, scale, and rotation settings have their identity values.

> method (send a-dc set-alignment-scale scale) → void?
> scale : (>/c 0.0)

Sets the drawing context’s alignment scale, which determines how drawing coordinates and pen widths are adjusted for unsmoothed or aligned drawing (see set-smoothing).

The default alignment scale is 1.0, which means that drawing coordinates and pen sizes are aligned to integer values.

An alignment scale of 2.0 aligns drawing coordinates to half-integer values. A value of 2.0 could be suitable for a bitmap-dc% whose destination is a bitmap with a backing scale of 2.0, since half-integer values correspond to pixel boundaries. Even when a destinate context has a backing scale of 2.0, however, an alignment scale of 1.0 may be desirable to maintain consistency with drawing contexts that have a backing scale and alignment scale of 1.0.

Added in version 1.1 of package draw-lib.

> method (send a-dc set-alpha opacity) → void?
> opacity : (real-in 0 1)

Determines the opacity of drawing. A value of 0.0 corresponds to completely transparent (i.e., invisible) drawing, and 1.0 corresponds to completely opaque drawing. For intermediate values, drawing is blended with the existing content of the drawing context. A color (e.g. for a brush) also has an alpha value; it is combined with the drawing context’s alpha by multiplying.

> method (send a-dc set-background color) → void?
> color : (is-a?/c color%)
> (send a-dc set-background color-name) → void?
> color-name : string?

Sets the background color for drawing in this object (e.g., using clear or using a stippled brush% with the mode 'opaque). For monochrome drawing, all non-black colors are treated as white.

> method (send a-dc set-brush brush) → void?
> brush : (is-a?/c brush%)
> (send a-dc set-brush color style) → void?
> color : (is-a?/c color%)
> | style |  | : |  |
> (or/c 'transparent 'solid 'opaque
> 'xor 'hilite 'panel
> 'bdiagonal-hatch 'crossdiag-hatch
> 'fdiagonal-hatch 'cross-hatch
> 'horizontal-hatch 'vertical-hatch)
> (send a-dc set-brush color-name style) → void?
> color-name : string?
> | style |  | : |  |
> (or/c 'transparent 'solid 'opaque
> 'xor 'hilite 'panel
> 'bdiagonal-hatch 'crossdiag-hatch
> 'fdiagonal-hatch 'cross-hatch
> 'horizontal-hatch 'vertical-hatch)

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 find-or-create-brush in brush-list%.

> > method
> > (send a-dc set-clipping-rect |  | x |  |  |  |
> > |  | y |  |  |  |
> > |  | width |  |  |  |
> > |  | height) |  | → |  | void?
> x : real?
> y : real?
> width : (and/c real? (not/c negative?))
> height : (and/c real? (not/c negative?))

Sets the clipping region to a rectangular region.

See also set-clipping-region and get-clipping-region.

> method (send a-dc set-clipping-region rgn) → void?
> rgn : (or/c (is-a?/c region%) #f)

Sets the clipping region for the drawing area, turning off all clipping within the drawing region if #f is provided.

The clipping region must be reset after changing a dc<%> object’s origin or scale (unless it is #f); see region% for more information.

See also set-clipping-rect and get-clipping-region.

> method (send a-dc set-font font) → void?
> font : (is-a?/c font%)

Sets the current font for drawing text in this object.

> method (send a-dc set-initial-matrix m) → void?
> m : (vector/c real? real? real? real? real? real?)

Set a transformation matrix that converts logical coordinates to device coordinates. The matrix applies before additional origin offset, scaling, and rotation.

See get-initial-matrix for information on the matrix as represented by a vector m.

See also transform, which adds a transformation to the current transformation, instead of changing the transformation composition in the middle.

> method (send a-dc set-origin x y) → void?
> x : real?
> y : real?

Sets the device origin, i.e., the location in device coordinates of (0,0) in logical coordinates. The origin offset applies after the initial transformation matrix, but before scaling and rotation.

See also translate, which adds a translation to the current transformation, instead of changing the transformation composition in the middle.

> method (send a-dc set-pen pen) → void?
> pen : (is-a?/c pen%)
> (send a-dc set-pen color width style) → void?
> color : (is-a?/c color%)
> width : (real-in 0 255)
> | style |  | : |  |
> (or/c 'transparent 'solid 'xor 'hilite
> 'dot 'long-dash 'short-dash 'dot-dash
> 'xor-dot 'xor-long-dash 'xor-short-dash
> 'xor-dot-dash)
> (send a-dc set-pen color-name width style) → void?
> color-name : string?
> width : (real-in 0 255)
> | style |  | : |  |
> (or/c 'transparent 'solid 'xor 'hilite
> 'dot 'long-dash 'short-dash 'dot-dash
> 'xor-dot 'xor-long-dash 'xor-short-dash
> 'xor-dot-dash)

Sets the current pen for this object. When a color, width, and style are given, the arguments are as for find-or-create-pen in pen-list%.

The current pen does not affect text drawing; see also set-text-foreground.

While a pen is selected into a drawing context, it cannot be modified.

> method (send a-dc set-rotation angle) → void?
> angle : real?

Set the rotation of logical coordinates in radians to device coordinates. Rotation applies after the initial transformation matrix, origin offset, and scaling.

See also rotate, which adds a rotation to the current transformation, instead of changing the transformation composition.

> method (send a-dc set-scale x-scale y-scale) → void?
> x-scale : real?
> y-scale : real?

Sets a scaling factor that maps logical coordinates to device coordinates. Scaling applies after the initial transformation matrix and origin offset, but before rotation. Negative scaling factors have the effect of flipping.

See also scale, which adds a scale to the current transformation, instead of changing the transformation composition in the middle.

> method (send a-dc set-smoothing mode) → void?
> mode : (or/c 'unsmoothed 'smoothed 'aligned)

Enables or disables anti-aliased smoothing for drawing. (Text smoothing is not affected by this method, and is instead controlled through the font% object.)

The smoothing mode is either 'unsmoothed, 'smoothed, or 'aligned. Both 'aligned and 'smoothed are smoothing modes that enable anti-aliasing, while both 'unsmoothed and 'aligned adjust drawing coordinates to match pixel boundaries. For most applications that draw to the screen or bitmaps, 'aligned mode is the best choice.

Conceptually, 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 1 from (0, 10) to (10, 10) in 'smoothed mode draws a 2-pixel wide line with 50% opacity.

In 'unsmoothed and 'aligned modes, drawing coordinates are truncated based on the alignment scale of the drawing context. Specifically, when the alignment scale is 1.0, drawing coordinates are truncated to integer coordinates. More generally, drawing coordinates are shifted toward zero so that the result multipled by the alignment scale is integral. For line drawing, coordinates are further shifted based on the pen width and the alignment scale, where the shift corrsponds to half of the pen width (reduced to a value such that its multiplication times the alignment scale times two produces an integer). In addition, for pen drawing through draw-rectangle, draw-ellipse, draw-rounded-rectangle, and draw-arc, the given width and height are each decreased by 1.0 divided by the alignment scale.

> method (send a-dc set-text-background color) → void?
> color : (is-a?/c color%)
> (send a-dc set-text-background color-name) → void?
> color-name : string?

Sets the current text background color for this object. The text background color is painted behind text that is drawn with draw-text, but only for the 'solid text mode (see set-text-mode).

For monochrome drawing, all non-white colors are treated as black.

> method (send a-dc set-text-foreground color) → void?
> color : (is-a?/c color%)
> (send a-dc set-text-foreground color-name) → void?
> color-name : string?

Sets the current text foreground color for this object, used for drawing text with draw-text.

For monochrome drawing, all non-black colors are treated as white.

> method (send a-dc set-text-mode mode) → void?
> mode : (or/c 'solid 'transparent)

Determines how text is drawn:

- 'solid — Before text is drawn, the destination area is filled with the text background color (see set-text-background).

- 'transparent — Text is drawn directly over any existing image in the destination, as if overlaying text written on transparent film.

> method (send a-dc set-transformation t) → void?
> | t |  | : |  |
> (vector/c (vector/c real? real? real? real? real? real?)
> real? real? real? real? real?)

Sets the draw context’s transformation. See get-transformation for information about t.

> method (send a-dc start-doc message) → void?
> message : string?

Starts a document, relevant only when drawing to a printer, PostScript, PDF, or SVG device. For some platforms, the message string is displayed in a dialog until end-doc is called.

For relevant devices, an exception is raised if start-doc has been called already (even if end-doc has been called as well). Furthermore, drawing methods raise an exception if not called while a page is active as determined by start-doc and start-page.

> method (send a-dc start-page) → void?

Starts a page, relevant only when drawing to a printer, PostScript, SVG, or PDF device.

Relevant devices, an exception is raised if start-page is called when a page is already started, or when start-doc has not been called, or when end-doc has been called already. In addition, in the case of PostScript output, Encapsulated PostScript (EPS) cannot contain multiple pages, so calling start-page a second time for a post-script-dc% instance raises an exception; to create PostScript output with multiple pages, supply #f as the as-eps initialization argument for post-script-dc%.

> method (send a-dc suspend-flush) → void?

Calls the suspend-flush in canvas<%> method for canvas<%> output, and has no effect for other kinds of drawing contexts.

> method (send a-dc transform m) → void?
> m : (vector/c real? real? real? real? real? real?)

Adds a transformation by m to the drawing context’s current transformation.

See get-initial-matrix for information on the matrix as represented by a vector m.

Afterward, the drawing context’s transformation is represented in the initial transformation matrix, and the separate origin, scale, and rotation settings have their identity values.

> method (send a-dc translate dx dy) → void?
> dx : real?
> dy : real?

Adds a translation of dx in the X-direction and dy in the Y-direction to the drawing context’s current transformation.

Afterward, the drawing context’s transformation is represented in the initial transformation matrix, and the separate origin, scale, and rotation settings have their identity values.

> method (send a-dc try-color try result) → void?
> try : (is-a?/c color%)
> result : (is-a?/c color%)

Determines the actual color used for drawing requests with the given color. The result color is set to the RGB values that are actually produced for this drawing context to draw the color try.
top contents ← prev up next →