pen%

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

• 'transparent -- Draws with no effect (on the outline of the drawn shape).
• 'solid -- Draws using the pen's color. If a (monochrome) stipple is installed into the pen, black pixels from the stipple are transferred to the destination using the brush's color, and white pixels from the stipple are not transferred.
• 'xor -- The pen's color or colored stipple is xor-ed with existing destination pixel values. The 'xor mapping is unspecified for arbitrary color combinations, but the mapping provides two guarantees:
  • Black-and-white drawing to a color or monochrome destination always works as expected: black xor white = black, white xor black = black, black xor black = white, and white xor white = white.
  • Performing the same drawing operation twice in a row with 'xor is equivalent to a no-op.

• The following special pen modes use the pen's color and only apply when a stipple is not installed:
  • 'dot
  • 'long-dash
  • 'short-dash
  • 'dot-dash
  • 'xor-dot
  • 'xor-long-dash
  • 'xor-short-dash
  • 'xor-dot-dash

To avoid creating multiple pens with the same characteristics, use the global pen-list% object the-pen-list.

A pen of size 0 uses the minimum visible size for the distination. In (unscaled) screens and bitmaps, this behaves the nearly same as a pen of size 1. In a post-script-dc%, a pen of size 0 typically draws a line thinner than 1.

• (make-object pen%) -> pen% object

  
  

• (make-object pen% color width style) -> pen% object
      color : color% object
      width : exact integer in [0, 255]
      style : symbol in '(transparent solid xor dot long-dash short-dash dot-dash xor-dot xor-long-dash xor-short-dash xor-dot-dash)

  Creates a pen using a color object.

  
  

• (make-object pen% color-name width style) -> pen% object
      color-name : string
      width : exact integer in [0, 255]
      style : symbol in '(transparent solid xor dot long-dash short-dash dot-dash xor-dot xor-long-dash xor-short-dash xor-dot-dash)

  Creates a pen using a color name; a color is found for the name through the global color-database<%> object the-color-database. If the color name is not known, the pen is initialized to black.

  
  

• get-cap
• get-color
• get-join
• get-stipple
• get-style
• get-width
• set-cap
• set-color
• set-join
• set-stipple
• set-style
• set-width