6.4  brush%

A brush is a drawing tool with a color and a style that is used for filling in areas, such as the interior of a rectangle or ellipse. On a monochrome display, all non-white brushes are drawn as black.

In addition to its color and style, a brush can have a stipple bitmap. This stipple is used only in unsmoothed mode (see set-smoothing) or in a PostScript drawing context. Painting with a stipple brush is similar to calling draw-bitmap with the stipple bitmap in the filled region, except that the bitmap may not be scaled in the same way (depending on the platform and device).

A brush's style is one of the following:

• 'transparent -- Draws with no effect (on the interior of the drawn shape).

• 'solid -- Draws using the brush's color. If a monochrome stipple is installed into the brush, black pixels from the stipple are transferred to the destination using the brush's color, and white pixels from the stipple are not transferred.

• 'opaque -- Same as 'solid, except when a monochrome stipple is installed for unsmoothed or PostScript drawing; in that case, white pixels from the stipple are transferred to the destination using the destination's background color.

• 'xor -- In a smoothing mode or if a color stipple is installed, 'xor is treated as 'solid. Otherwise, the brush's color or colored (monochrome) stipple is xored 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.

• 'hilite -- In unsmoothed mode, existing destination pixels are ``highlighted'' in a platform-specific way when the brush color is black. Under Windows and X for a color drawing context, the inverted RGB components of destination pixel are combined with the RGB components of the system-wide highlight color<sup>12</sup> 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. For any monochrome drawing context, 'hilite is the same as 'xor. For PostScript output, 'hilite uses a stipple that is an array of small dots (essentially a halftone), otherwise 'hilite is treated like 'solid in a smoothing mode.

• 'panel -- In unsmoothed mode, draws with the same color and pattern as a top-level panel background, if the brush's color is the same as the color returned by get-panel-background and if the brush has no stipple. To create a canvas% object that is drawn like a control, use the 'transparent canvas style instead, because certain kinds of nested panels have different background colors (e.g., a tab-panel% under Mac OS X). In a smoothing mode, 'panel is treated as 'solid.

• The following modes correspond to built-in stipples drawn in 'solid mode:

  • 'bdiagonal-hatch -- diagonal lines, top-left to bottom-right

  • 'crossdiag-hatch -- crossed diagonal lines

  • 'fdiagonal-hatch -- diagonal lines, top-right to bottom-left

  • 'cross-hatch -- crossed horizontal and vertical lines

  • 'horizontal-hatch -- horizontal lines

  • 'vertical-hatch -- vertical lines

  However, when a specific stipple is installed into the brush for when drawing with a smoothing mode into a non-PostScript context, the above modes are ignored and 'solid is used, instead.

To draw outline shapes (such as unfilled boxes and ellipses), use the 'transparent brush style. See set-style for more information about styles.

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

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

  Creates a solid black brush.

  
  

• (make-object brush% color style) -> brush% object
     color : color% object
     style : symbol in '(transparent solid opaque xor hilite panel bdiagonal-hatch crossdiag-hatch fdiagonal-hatch cross-hatch horizontal-hatch vertical-hatch)

  Creates a brush with the given color and style.

  
  

• (make-object brush% color-name style) -> brush% object
     color-name : string
     style : symbol in '(transparent solid opaque xor hilite panel bdiagonal-hatch crossdiag-hatch fdiagonal-hatch cross-hatch horizontal-hatch vertical-hatch)

  Creates a brush with the given color and style, where the color is specified using a name; see color-database<%> for information about color names. If the name is not known, the brush's color is set to black.

  
  

Methods
    get-color
    get-stipple
    get-style
    set-color
    set-stipple
    set-style