#lang scribble/doc @(require "common.ss") @defclass/title[pen% 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 @method[dc<%> set-smoothing]) or in a PostScript drawing context. Painting with a stipple pen is similar to calling @method[dc<%> draw-bitmap] with the stipple bitmap in region painted by the pen. A pen's style is one of the following: @itemize[ @item{@indexed-scheme['transparent] --- Draws with no effect (on the outline of the drawn shape).} @item{@indexed-scheme['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.} @item{@indexed-scheme['xor] --- In unsmoothed mode, the pen's color or colored stipple is xor-ed with existing destination pixel values. The @scheme['xor] mapping is unspecified for arbitrary color combinations, but the mapping provides two guarantees: @itemize[ @item{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.} @item{Performing the same drawing operation twice in a row with @scheme['xor] is equivalent to a no-op.} ] In a smoothing mode, @scheme['xor] is equivalent to @scheme['solid].} @item{@indexed-scheme['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, @scheme['hilite] is the same as @scheme['xor]. In a smoothing mode, @scheme['hilite] is treated like @scheme['solid].} @item{The following special pen modes use the pen's color, and they only apply when a stipple is not used: @itemize[ @item{@indexed-scheme['dot]} @item{@indexed-scheme['long-dash]} @item{@indexed-scheme['short-dash]} @item{@indexed-scheme['dot-dash]} @item{@indexed-scheme['xor-dot]} @item{@indexed-scheme['xor-long-dash]} @item{@indexed-scheme['xor-short-dash]} @item{@indexed-scheme['xor-dot-dash]} ]} ] To avoid creating multiple pens with the same characteristics, use the global @scheme[pen-list%] object @indexed-scheme[the-pen-list], or provide a color, width, and style to @xmethod[dc<%> set-pen]. A pen of size @scheme[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 @scheme[1]. In a smoothing mode (including all @scheme[post-script-dc%] drawing), a pen of size @scheme[0] draws a line thinner than a pen of size @scheme[1]. If the pen's width is not an integer, then the width is truncated to an integer (even before scaling) in unsmoothed mode. @defconstructor*/make[(() ([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)]) ([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 @scheme[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 @scheme[color-database<%>] for information about color names; if the name is not known, the pen's color is black. } @defmethod[(get-cap) (one-of/c 'round 'projecting 'butt)]{ Returns the pen cap style (Windows unsmoothed, X unsmoothed, all smoothing). The default is @scheme['round]. } @defmethod[(get-color) (is-a?/c color%)]{ Returns the pen's color object. } @defmethod[(get-join) (one-of/c 'round 'bevel 'miter)]{ Returns the pen join style (Windows unsmoothed, X unsmoothed, all smoothing). The default is @scheme['round]. } @defmethod[(get-stipple) (or/c (is-a?/c bitmap%) false/c)]{ Gets the current stipple bitmap, or returns @scheme[#f] if no stipple bitmap is installed. } @defmethod[(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 @scheme[pen%] for information about possible styles. } @defmethod[(get-width) (real-in 0 255)]{ Returns the pen width. } @defmethod[(set-cap [cap-style (one-of/c 'round 'projecting 'butt)]) void?]{ Sets the pen cap style (Windows unsmoothed, X unsmoothed, all smoothing). See @method[pen% get-cap] for information about cap styles. A pen cannot be modified if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. } @defmethod*[([(set-color [color (is-a?/c color%)]) void?] [(set-color [color-name string?]) void?] [(set-color [red (integer-in 0 255)] [green (integer-in 0 255)] [blue (integer-in 0 255)]) void?])]{ Sets the pen color. A pen cannot be modified if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. } @defmethod[(set-join [join-style (one-of/c 'round 'bevel 'miter)]) void?]{ Sets the pen join style (Windows unsmoothed, X unsmoothed, all smoothing). See @method[pen% get-join] for information about join styles. A pen cannot be modified if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. } @defmethod[(set-stipple [stipple (or/c (is-a?/c bitmap%) false/c)]) void?]{ Sets the pen stipple bitmap, which must be an 8 x 8 monochrome bitmap or @scheme[#f], which turns off the stipple bitmap. A bitmap cannot be used as a stipple if it is selected into a @scheme[bitmap-dc%] object; if the given bitmap is selected into a @scheme[bitmap-dc%] object, @|MismatchExn|. A pen cannot be modified if it was obtained from a @scheme[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 @scheme[post-script-dc%] (which is always in smoothed mode). } @defmethod[(set-style [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)]) void?]{ Sets the pen style. See @scheme[pen%] for information about the possible styles. A pen cannot be modified if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. } @defmethod[(set-width [width (real-in 0 255)]) void?]{ Sets the pen width. A pen cannot be modified if it was obtained from a @scheme[pen-list%] or while it is selected into a drawing context. }}