2.3 Drawing Classes
2.3.1 bitmap%
2.3.2 bitmap-dc%
2.3.3 brush%
2.3.4 brush-list%
2.3.5 color%
2.3.6 color-database<%>
2.3.7 dc<%>
2.3.8 dc-path%
2.3.9 font%
2.3.10 font-list%
2.3.11 font-name-directory<%>
2.3.12 gl-config%
2.3.13 gl-context<%>
2.3.14 pen%
2.3.15 pen-list%
2.3.16 point%
2.3.17 post-script-dc%
2.3.18 printer-dc%
2.3.19 ps-setup%
2.3.20 region%
On this page:
get-cap
get-color
get-join
get-stipple
get-style
get-width
set-cap
set-color
set-join
set-stipple
set-style
set-width

pen% : class?

  superclass: object%

A pen is a drawing tool with a color, width, and style. A pen draws lines and outlines, such as the outline of a rectangle. On a monochrome display, all non-white pens are drawn as black.

In addition to its color, width, and style, a pen can have a stipple bitmap that is a 8 x 8 monochrome bitmap. This stipple is used only in unsmoothed mode (see set-smoothing) or in a PostScript drawing context. Painting with a stipple pen is similar to calling draw-bitmap with the stipple bitmap in region painted by the pen.

A pen’s style is one of the following:

To avoid creating multiple pens with the same characteristics, use the global pen-list% object the-pen-list, or provide a color, width, and style to set-pen in dc<%>.

A pen of size 0 uses the minimum line size for the destination drawing context. In (unscaled) canvases and bitmaps in unsmoothed mode, a zero-width pen behaves the nearly same as a pen of size 1. In a smoothing mode (including all post-script-dc% drawing), a pen of size 0 draws a line thinner than a pen of size 1. If the pen’s width is not an integer, then the width is truncated to an integer (even before scaling) in unsmoothed mode.

(make-object pen%)  (is-a?/c pen%)
(make-object pen% color width style)  (is-a?/c 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)
(make-object pen% color-name width style)  (is-a?/c pen%)
  color-name : string?
  width : (real-in 0 255)
  style : 
(one-of/c 'transparent 'solid 'xor 'dot 'hilite
          'long-dash 'short-dash 'dot-dash
          'xor-dot 'xor-long-dash 'xor-short-dash
          'xor-dot-dash)
When no argument are provided, the result is a solid black pen of width 0. Otherwise, the result is a pen with the given color, width, and style. For the case that the color is specified using a name, see color-database<%> for information about color names; if the name is not known, the pen’s color is black.

(send a-pen get-cap)  (one-of/c 'round 'projecting 'butt)
Returns the pen cap style (Windows unsmoothed, X unsmoothed, all smoothing). The default is 'round.

(send a-pen get-color)  (is-a?/c color%)
Returns the pen’s color object.

(send a-pen get-join)  (one-of/c 'round 'bevel 'miter)
Returns the pen join style (Windows unsmoothed, X unsmoothed, all smoothing). The default is 'round.

(send a-pen get-stipple)  (or/c (is-a?/c bitmap%) false/c)
Gets the current stipple bitmap, or returns #f if no stipple bitmap is installed.

(send a-pen get-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)
Returns the pen style. See pen% for information about possible styles.

(send a-pen get-width)  (real-in 0 255)
Returns the pen width.

(send a-pen set-cap cap-style)  void?
  cap-style : (one-of/c 'round 'projecting 'butt)
Sets the pen cap style (Windows unsmoothed, X unsmoothed, all smoothing). See get-cap for information about cap styles.

A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.

(send a-pen set-color color)  void?
  color : (is-a?/c color%)
(send a-pen set-color color-name)  void?
  color-name : string?
(send a-pen set-color red green blue)  void?
  red : (integer-in 0 255)
  green : (integer-in 0 255)
  blue : (integer-in 0 255)
Sets the pen color.

A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.

(send a-pen set-join join-style)  void?
  join-style : (one-of/c 'round 'bevel 'miter)
Sets the pen join style (Windows unsmoothed, X unsmoothed, all smoothing). See get-join for information about join styles.

A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.

(send a-pen set-stipple stipple)  void?
  stipple : (or/c (is-a?/c bitmap%) false/c)
Sets the pen stipple bitmap, which must be an 8 x 8 monochrome bitmap or #f, which turns off the stipple bitmap.

A bitmap cannot be used as a stipple if it is selected into a bitmap-dc% object; if the given bitmap is selected into a bitmap-dc% object, an exn:fail:contract exception is raised. A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.

A pen’s stipple is not used in a smoothing mode, except for a post-script-dc% (which is always in smoothed mode).

(send a-pen set-style style)  void?
  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)
Sets the pen style. See pen% for information about the possible styles.

A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.

(send a-pen set-width width)  void?
  width : (real-in 0 255)
Sets the pen width.

A pen cannot be modified if it was obtained from a pen-list% or while it is selected into a drawing context.