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

• '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 -- In unsmoothed mode, 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.

  In a smoothing mode, 'xor is equivalent to 'solid.

• 'hilite -- In unsmoothed mode, existing destination pixels are ``highlighted'' in a platform-specific way when the pen color is black. Under Windows for a color drawing context, the inverted RGB components of destination pixel are combined with the RGB components of the system-wide highlight color using a bitwise ``or'', and the combination is used. Under Mac OS X for a color drawing context, the inverted RGB components of the system-wide highlight color are subtracted from the RGB components of each destination pixel, and the difference (or 0 for a negative result) is used. Under X or for any monochrome drawing context, 'hilite is the same as 'xor. In a smoothing mode, 'hilite is treated like 'solid.

• The following special pen modes use the pen's color, and they only apply when a stipple is not used:

  • '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, 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%) -> pen% object

  
  

• (make-object pen% color width style) -> pen% object
     color : color% object
     width : real number in [0, 255]
     style : symbol in '(transparent solid xor hilite 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 : real number 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.

  
  

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