DUIM-DCs Library

Overview

The DUIM-DCs library provides color support to the DUIM library. The library contains a single module, duim-dcs, from which all the interfaces described in this chapter are exposed. DUIM-DCs Module contains complete reference entries for each exposed interface.

Throughout this chapter, a drawing context consists of the combination of ink, color, brush, pen, palette, and shapes that make up patterns and images.

The class hierarchy for DUIM-DCs

A number of base classes are exposed in the DUIM-DCs library, each of which is a subclass of <object>. They are shown in the following table

<object>

<pen>

<brush>

<palette>

<ink>

See Subclasses of <ink>

<text-style>

<device-font>

  • <pen> This is protocol class for pens. A pen is used to draw 1 dimensional graphics such as lines or outline, using a specific color or pattern.

  • <brush> The protocol class for brushes. Brushes are used to fill in 2 dimensional areas with a specific color or pattern.

  • <palette> The protocol class for palettes. A palette provides a set of colors which can be made available to an application.

  • <ink> This class can be thought of as anything that can be drawn. As the name implies, an ink describes the color and opacity features used by a given pen or brush. That is, the pen and brush define the drawing style (outlining or filling, respectively), and an ink is used to describe the color or pattern that is drawn. This class has a number of subclasses, described in Subclasses of <ink>.

  • <text-style> The protocol class for text styles. A text style is a portable way of describing the appearance of a piece of text on screen (its font family, size, weight, and so on) in an abstract fashion. Because the fonts available on a particular computer may not necessarily match the fonts available on the computer of the programmer, DUIM provides a portable model which allows the most suitable font on the user’s machine to be chosen at run-time.

  • <device-font> The protocol class for device-specific fonts, that is, fonts that are resident on a particular device. This is a direct subclass of <text-style>.

Subclasses of <ink>

A number of subclasses of <ink> are exposed by the DUIM-DCs library, as follows:

  • <color> The class of all colors available on the system. This is a direct subclass of <ink>.

  • <image> The class of all images, such as icons and bitmap images. Images may often be acquired from an outside source, such as a file on disk. This is a direct subclass of <ink>.

  • <stencil> A stencil is a special kind of pattern that contains only opacities, that is, it provides a layer of transparency. This can be useful, for instance, when overlaying a color onto an image, so as to provide the impression of shading. This is a direct subclass of <image>.

  • <pattern> A pattern is a bounded rectangular arrangement of color, like a checkerboard. Drawing a pattern draws a different design in each rectangular cell of the pattern. This is a direct subclass of <stencil>.

Error classes provided by DUIM-DCs

Two error classes are provided by the DUIM-DCs library, both of which are immediate subclasses of <error>.

  • <color-not-found> This class of error is signalled when a color is requested but is not available on the user’s system.

  • <palette-full> This class of error is signalled when an attempt is made to add a color to a palette, and the palette cannot accept any more colors. The number of colors in a palette depends on the color depth of the connected monitor.

DUIM-DCs Module

This section contains a complete reference of all the interfaces that are exported from the duim-dcs module.

\= Generic function

Returns #t if two objects are equal.

Signature:

= color1 color2 => boolean

Signature:

= pen1 pen2 => boolean

Signature:

= brush1 brush2 => boolean

Signature:

= text-style1 text-style2 => value

Parameters:

  • color1 – An instance of type <color>.

  • color2 – An instance of type <color>.

  • pen1 – An instance of type <pen>.

  • pen2 – An instance of type <pen>.

  • brush1 – An instance of type <brush>.

  • brush2 – An instance of type <brush>.

  • text-style1 – An instance of type <text-style>.

  • text-style2 – An instance of type <text-style>.

Values:
Discussion:

Returns #t if two objects are equal.

add-colors Generic function

Adds one or more colors to a palette and returns the updated palette.

Signature:

add-colors palette #rest colors => palette

Parameters:

  • palette – An instance of type <palette>.

  • colors – Instances of type <color>.

Values:
Discussion:

Adds colors to palette and returns the updated palette.

$background Constant

An indirect ink that uses the medium’s background design.

Type:

<ink>

Discussion:

An indirect ink that uses the medium’s background design.

See also:

$black Constant

The usual definition of black.

Type:

<color>

Discussion:

The usual definition black, the absence of all colors. In the rgb color model, its value is 000.

See also:

$blue Constant

The usual definition of the color blue.

Type:

<color>

Discussion:

The usual definition of the color blue.

See also:

$boole-clr Constant

The logical operator that is always 0.

Type:

<integer>

Discussion:

The logical operator that is always 0. It is a suitable first argument to the boole function.

$boole-set Constant

The logical operator that is always 1.

Type:

<integer>

Discussion:

The logical operator that is always 1. It is a suitable first argument to the boole function.

$boole-1 Constant

The logical operator that is always the same as the first integer argument to the boole function.

Type:

<integer>

Discussion:

The logical operator that is always the same as the first integer argument to the boole function. It is a suitable first argument to the boole function.

$boole-2 Constant

The logical operator that is always the same as the second integer argument to the boole function.

Type:

<integer>

Discussion:

The logical operator that is always the same as the second integer argument to the boole function. It is a suitable first argument to the boole function.

$boole-c1 Constant

The logical operator that is always the same as the complement of the first integer argument to the boole function.

Type:

<integer>

Discussion:

The logical operator that is always the same as the complement of the first integer argument to the boole function. It is a suitable first argument to the boole function.

$boole-c2 Constant

The logical operator that is always the same as the complement of the second integer argument to the boole function.

Type:

<integer>

Discussion:

The logical operator that is always the same as the complement of the second integer argument to the boole function. It is a suitable first argument to the boole function.

$boole-and Constant

The logical operator and.

Type:

<integer>

Discussion:

The logical operator and. It is a suitable first argument to the boole function.

$boole-ior Constant

The logical operator inclusive or.

Type:

<integer>

Discussion:

The logical operator inclusive or. It is a suitable first argument to the boole function.

$boole-xor Constant

The logical operator exclusive or.

Type:

<integer>

Discussion:

The logical operator exclusive or. It is a suitable first argument to the boole function.

$boole-eqv Constant

The logical operator equivalence (exclusive nor).

Type:

<integer>

Discussion:

The logical operator equivalence (exclusive nor). It is a suitable first argument to the boole function.

$boole-nand Constant

The logical operator not-and.

Type:

<integer>

Discussion:

The logical operator not-and. It is a suitable first argument to the boole function.

$boole-nor Constant

The logical operator not-or.

Type:

<integer>

Discussion:

The logical operator not-or. It is a suitable first argument to the boole function.

$boole-andc1 Constant

The logical operator that is the and of the complement of the first integer argument to the boole function with the second.

Type:

<integer>

Discussion:

The logical operator that is the and of the complement of the first integer argument to the boole function with the second. It is a suitable first argument to the boole function.

$boole-andc2 Constant

The logical operator that is the and of the first integer argument to the boole function with the second with the complement of the second.

Type:

<integer>

Discussion:

The logical operator that is and of the first integer argument to the boole function with the complement of the second. It is a suitable first argument to the boole function.

$boole-orc1 Constant

The logical operator that is the or of the complement of the first integer argument to the boole function with the second.

Type:

<integer>

Discussion:

The logical operator that is the or of the complement of the first integer argument to the boole function with the second. It is a suitable first argument to the boole function.

$boole-orc2 Constant

The logical operator that is the or of the first integer argument to the boole function with the second with the complement of the second.

Type:

<integer>

Discussion:

The logical operator that is or of the first integer argument to the boole function with the complement of the second. It is a suitable first argument to the boole function.

$bricks-stipple Constant

A stipple pattern for use in creating a patterned brush with horizontal and vertical lines in the pattern of the mortar in a brick wall.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with horizontal and vertical lines in the pattern of the mortar in a brick wall.

See also:

<brush> Abstract Instantiable Class

The protocol class for brushes.

Superclasses:

<object>

Init-Keywords:

  • foreground – An instance of type <ink>.

  • background – An instance of type <ink>.

  • mode – An instance of type <integer>.

  • fill-style – An instance of type false-or(<integer>). Default value: #f.

  • fill-rule – An instance of type false-or(<integer>). Default value: #f.

  • tile – An instance of type false-or(<integer>). Default value: #f.

  • stipple – An instance of type false-or(<integer>). Default value: #f.

  • ts-x – An instance of false-or(<integer>). Default value: #f.

  • ts-y – An instance of false-or(<integer>). Default value: #f.

Discussion:

The protocol class for brushes.

Operations:

The following operations are exported from the DUIM-DCs module.

See also:

brush? Generic function

Returns #t if its argument is a brush.

Signature:

brush? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if its argument is a brush.

brush-background Generic function

Returns the ink that is the background color of a brush.

Signature:

brush-background brush => ink

Parameters:

  • brush – An instance of type <brush>.

Values:

  • ink – An instance of type <ink>.

Discussion:

Returns the ink that is the background color of brush.

See also:

brush-fill-rule Generic function

Returns the fill rule of the brush.

Signature:

brush-fill-rule brush => fill-rule

Parameters:

  • brush – An instance of type <brush>.

Values:

  • fill-rule – An instance of type fill-rule or <boolean>.

Discussion:

Returns the fill rule for brush, or #f if brush does not have a fill rule.

See also:

brush-fill-style Generic function

Returns the fill style of the brush.

Signature:

brush-fill-style brush => fill-style

Parameters:

  • brush – An instance of type <brush>.

Values:

  • fill-style – An instance of fill-style or <boolean>.

Discussion:

Returns the fill style of brush, or #f, if brush does not have a fill style.

See also:

brush-foreground Generic function

Returns the ink that is the foreground color of a brush.

Signature:

brush-foreground brush => ink

Parameters:

  • brush – An instance of type <brush>.

Values:

  • ink – An instance of type <ink>.

Discussion:

Returns the ink that is the foreground color of brush.

See also:

brush-mode Generic function

Returns an integer representing the drawing mode of a brush.

Signature:

brush-mode brush => integer

Parameters:

  • brush – An instance of type <brush>.

Values:
Discussion:

Returns an integer representing the drawing mode of brush.

See also:

brush-stipple Generic function

Returns the stipple pattern of a brush.

Signature:

brush-stipple brush => stipple

Parameters:

  • brush – An instance of type <brush>.

Values:

  • stipple – A (stipple) or #f.

Discussion:

Returns the stipple pattern of brush.

See also:

brush-stretch-mode Generic function

Returns the stretch mode of the brush.

Signature:

brush-stretch-mode brush => stretch-mode

Parameters:

  • brush – An instance of type <brush>.

Values:

  • stretch-mode – An instance of stretch-mode or <boolean>.

Discussion:

Returns the stretch mode of the brush.

brush-tile Generic function

Returns the tile pattern of a brush.

Signature:

brush-tile brush => image

Parameters:

  • brush – An instance of type <brush>.

Values:

  • image – An instance of type <image>.

Discussion:

Returns the tile pattern of brush.

See also:

brush-ts-x Generic function

Returns the value of the x coordinate that is used to align the brush’s tile or stipple pattern.

Signature:

brush-ts-x brush => value

Parameters:

  • brush – An instance of type <brush>.

Values:

  • value – An instance of type false-or(<integer>).

Discussion:

Returns the value of the x coordinate that is used to align the tile or stipple pattern of brush. If brush has no tile or stipple pattern, brush-ts-x returns #f.

See also:

brush-ts-y Generic function

Returns the value of the y coordinate that is used to align the brush’s tile or stipple pattern.

Signature:

brush-ts-y brush => value

Parameters:

  • brush – An instance of type <brush>.

Values:

  • value – An instance of type false-or(<integer>).

Discussion:

Returns the value of the y coordinate that is used to align the tile or stipple pattern of brush. If brush has no tile or stipple pattern, brush-ts-y returns #f.

See also:

<color> Abstract Instantiable Class

The protocol class for colors.

Superclasses:

<ink>

Init-Keywords:

  • red – An instance of type <real>.

  • green – An instance of type <real>.

  • blue – An instance of type <real>.

  • intensity – An instance of type limited(<real>, min: 0, max: sqrt(3)).

  • hue – An instance of type limited(<real>, min: 0, max: 1).

  • saturation – An instance of type limited(<real>, min: 0, max: 1).

  • opacity – An instance of type limited(<real>, min: 0, max: 1).

Discussion:

The <color> class is the protocol class for a color, and is a subclass of <ink>. A member of the class <color> is an ink that represents the intuitive definition of color: white, black, red, pale yellow, and so forth. The visual appearance of a single point is completely described by its color. Drawing a color sets the color of every point in the drawing plane to that color, and sets the opacity to 1.

The red:, green:, and blue: init-keywords represent the red, green, and blue components of the color. For an 8-bit color scheme, these can take any real number in the range 0 to 255.

The intensity describes the brightness of the color. An intensity of 0 is black.

The hue of a color is the characteristic that is represented by a name such as red, green, blue and so forth. This is the main attribute of a color that distinguishes it from other colors.

The saturation describes the amount of white in the color. This is what distinguishes pink from red.

Opacity controls how new color output covers previous color output (that is, the final appearance when one color is painted on top of another). Opacity can vary from totally opaque (a new color completely obliterates the old color) to totally transparent (a new color has no effect whatsoever; the old color remains unchanged). Intermediate opacity values result in color blending so that the earlier color shows through what is drawn on top of it.

All of the standard instantiable color classes provided by DUIM are immutable.

A color can be specified by four real numbers between 0 and 1 (inclusive), giving the amounts of red, green, blue, and opacity (alpha). Three 0’s for the RGB components mean black; three 1’s mean white. The intensity-hue-saturation color model is also supported, but the red-green-blue color model is the primary model we will use in the specification.

An opacity may be specified by a real number between 0 and 1 (inclusive). 0 is completely transparent, 1 is completely opaque, fractions are translucent. The opacity of a color is the degree to which it hides the previous contents of the drawing plane when it is drawn.

Operations:

The following operations are exported from the DUIM-DCs module.

See also:

color? Generic function

Returns #t if object is a color.

Signature:

color? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a color, otherwise returns #f.

See also:

color-ihs Generic function

Returns four values, the intensity, hue, saturation, and opacity components of a color.

Signature:

color-ihs color => intensity hue saturation opacity

Parameters:

  • color – An instance of type <color>.

Values:

  • intensity – An instance of type limited(<real>, min: 0, max: sqrt(3)).

  • hue – An instance of type limited(<real>, min: 0, max: 1).

  • saturation – An instance of type limited(<real>, min: 0, max: 1).

  • opacity – An instance of type limited(<real>, min: 0, max: 1).

Discussion:

Returns four values, the intensity, hue, saturation, and opacity components of the color color. The first value is a real number between 0 and sqrt{3 } (inclusive). The second and third values are real numbers between 0 and 1 (inclusive).

See also:

color-luminosity Generic function

Returns the brightness of a color.

Signature:

color-luminosity* color => luminosity

Parameters:

  • color – An instance of type <color>.

Values:

  • luminosity – An instance of type limited(<real>, min: 0, max: 1).

Discussion:

Returns the brightness of color color as real number between 0 and 1. The value is the solution of a function that describes the perception of the color by the human retina.

See also:

<color-not-found> Concrete Sealed Class

The class of the error that is signalled when a color that is not available is requested.

Superclasses:

<error>

Init-Keywords:

  • color – An instance of type <color>.

Discussion:

The class of the error that is signalled when a color that is not available is requested. The color: init-keyword is used to specify the color that was requested but was not available.

Operations:

  • None.

See also:

color-palette? Generic function

Returns #t if the stream or medium supports color.

Signature:

color-palette? palette => boolean

Parameters:
Values:
Discussion:

Returns #t if the stream or medium supports color.

See also:

color-rgb Generic function

Returns four values, the red, green, blue, and opacity components of a color.

Signature:

color-rgb color => ref green blue opacity

Parameters:

  • color – An instance of type <color>.

Values:

  • red – An instance of type limited(<real>, min: 0, max: 1)

  • gree – n An instance of type limited(<real>, min: 0, max: 1)

  • blue – An instance of type limited(<real>, min: 0, max: 1)

  • opacity – An instance of type limited(<real>, min: 0, max: 1).

Discussion:

Returns four values, the red, green, blue, and opacity components of the color color. The values are real numbers between 0 and 1 (inclusive).

See also:

contrasting-colors-limit Generic function

Returns the number of contrasting colors that can be rendered on the current platform.

Signature:

contrasting-colors-limit port => integer

Parameters:

  • port – An instance of type <silica>

Values:
Discussion:

Returns the number of contrasting colors (or stipple patterns if port is monochrome or grayscale) that can be rendered on any medium on the port port. Implementations are encouraged to make this as large as possible, but it must be at least 8. All classes that obey the medium protocol must implement a method for this generic function.

See also:

contrasting-dash-patterns-limit Generic function

Returns the number of contrasting dash patterns that the specified port can generate.

Signature:

contrasting-dash-patterns-limit port => no-of-patterns

Parameters:

  • port – An instance of type <silica>.

Values:

  • no-of-patterns – An instance of type <integer>.

Discussion:

Returns the number of contrasting dash patterns that the specified port can generate.

See also:

$cross-hatch Constant

A stipple pattern for use in creating a patterned brush with alternating solid and dashed lines.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with alternating solid and dashed lines.

See also:

$cyan Constant

The usual definition for the color cyan.

Type:

<color>

Discussion:

The usual definition for the color cyan.

See also:

$dash-dot-dot-pen Constant

A pen that draws a line with two dots between each dash.

Type:

<pen>

Discussion:

A pen that draws a line with two dots between each dash. The line width is 1 and dashes: is #[4, 1, 1, 1, 1, 1].

See also:

$dash-dot-pen Constant

A pen that draws a dashed and dotted line.

Type:

<pen>

Discussion:

A pen that draws a dashed and dotted line. The line width is 1 and dashes: is #[4, 1, 1, 1].

See also:

$dashed-pen Constant

A pen that draws a dashed line.

Type:

<pen>

Discussion:

A pen that draws a dashed line. The line width is 1 and dashes: is #t.

See also:

default-background Generic function

Returns the ink that is the default background of its argument.

Signature:

default-foreground object => background

Parameters:

  • object – An instance of type <object>.

Values:

  • background – An instance of type <ink>.

Discussion:

Returns the ink that is the default background of its argument.

See also:

default-background-setter Generic function

Sets the default background.

Signature:

default-foreground-setter background object => background

Parameters:

  • background – An instance of type <ink>.

  • object – An instance of type <object>.

Values:

  • background – An instance of type <ink>.

Discussion:

Sets the default background for object.

See also:

default-foreground Generic function

Returns the ink that is the default foreground of its argument.

Signature:

default-foreground object => foreground

Parameters:

  • object – An instance of type <object>.

Values:

  • foreground – An instance of type <ink>.

Discussion:

Returns the ink that is the default foreground of its argument.

See also:

default-foreground-setter Generic function

Sets the default foreground.

Signature:

default-foreground-setter foreground object => foreground

Parameters:

  • foreground – An instance of type <ink>.

  • object – An instance of type <object>.

Values:

  • foreground – An instance of type <ink>.

Discussion:

Sets the default foreground for object.

See also:

default-text-style Generic function

Returns the default text style for its argument.

Signature:

default-text-style object => text-style

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns the default text style for its argument.This function is used to merge against if the text style is not fully specified, or if no text style is specified.

See also:

default-text-style-setter Generic function

Sets the default text style.

Signature:

default-text-style-setter text-style object => text-style

Parameters:
Values:
Discussion:

Sets the default text style.

See also:

<device-font> Concrete Sealed Class

The protocol class for device-specific fonts.

Superclasses:

<text-style>

Init-Keywords:

  • port –

  • font-name –

Discussion:

The protocol class for device-specific fonts.

Operations:

  • None.

See also:

$diagonal-hatch-down Constant

A stipple pattern for use in creating a patterned brush with alternating dashes and spaces.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with alternating dashes and spaces, the first line starting with a dash, followed by a space, and the second line starting with a space followed by a dash.

See also:

$diagonal-hatch-up Constant

A stipple pattern for use in creating a patterned brush with alternating dashes and spaces.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with alternating dashes and spaces, the first line starting with a space, followed by a dash, and the second line starting with a dash followed by a space.

See also:

$dotted-pen Constant

A pen that draws a dotted line.

Type:

<pen>

Discussion:

A pen that draws a dotted line. The line width is 1 and dashes: is #[1, 1].

See also:

find-color Generic function

Looks up and returns a color by name.

Signature:

find-color name palette #key error? => color

Parameters:

  • name – An instance of type <string>.

  • palette – An instance of type <palette>.

  • error? – An instance of type <boolean>. Default value: #f.

Values:

  • color – An instance of type <color>.

Discussion:

Looks up and returns a color by name. This is a list of the commonly provided color names that can be looked up with find-color:

  • alice-blue

  • antique-white

  • aquamarine

  • azure

  • beige

  • bisque

  • black

  • blanched-almond

  • blue

  • blue-violet

  • brown

  • burlywood

  • cadet-blue

  • chartreuse

  • chocolate

  • coral

  • cornflower-blue

  • cornsilk

  • cyan

  • dark-goldenrod

  • dark-green

  • dark-khaki

  • dark-olive-green

  • dark-orange

  • dark-orchid

  • dark-salmon

  • dark-sea-green

  • dark-slate-blue

  • dark-slate-gray

  • dark-turquoise

  • dark-violet

  • deep-pink

  • deep-sky-blue

  • dim-gray

  • dodger-blue

  • firebrick

  • floral-white

  • forest-green

  • gainsboro

  • ghost-white

  • gold

  • goldenrod

  • gray

  • green

  • green-yellow

  • honeydew

  • hot-pink

  • indian-red

  • ivory

  • khaki

  • lavender

  • lavender-blush

  • lawn-green

  • lemon-chiffon

  • light-blue

  • light-coral

  • light-cyan

  • light-goldenrod

  • light-goldenrod-yellow

  • light-gray

  • light-pink

  • light-salmon

  • light-sea-green

  • light-sky-blue

  • light-slate-blue

  • light-slate-gray

  • light-steel-blue

  • light-yellow

  • lime-green

  • linen

  • magenta

  • maroon

  • medium-aquamarine

  • medium-blue

  • medium-orchid

  • medium-purple

  • medium-sea-green

  • medium-slate-blue

  • medium-spring-green

  • medium-turquoise

  • medium-violet-red

  • midnight-blue

  • mint-cream

  • misty-rose

  • moccasin

  • navajo-white

  • navy-blue

  • old-lace

  • olive-drab

  • orange

  • orange-red

  • orchid

  • pale-goldenrod

  • pale-green

  • pale-turquoise

  • pale-violet-red

  • papaya-whip

  • peach-puff

  • peru

  • pink

  • plum

  • powder-blue

  • purple

  • red

  • rosy-brown

  • royal-blue

  • saddle-brown

  • salmon

  • sandy-brown

  • sea-green

  • seashell

  • sienna

  • sky-blue

  • slate-blue

  • slate-gray

  • snow

  • spring-green

  • steel-blue

  • tan

  • thistle

  • tomato

  • turquoise

  • violet

  • violet-red

  • wheat

  • white

  • white-smoke

  • yellow

  • yellow-green

Application programs can define other colors; these are provided because they are commonly used in the X Windows community, not because there is anything special about these particular colors.

See also:

$foreground Constant

An indirect ink that uses the medium’s foreground design.

Type:

<ink>

Discussion:

An indirect ink that uses the medium’s foreground design.

See also:

fully-merged-text-style? Generic function

Returns #t if the specified text style is completely specified.

Signature:

fully-merged-text-style? text-style => boolean

Parameters:
Values:
Discussion:

Returns #t if the specified text style is completely specified.

See also:

$green Constant

The usual definition of the color green.

Type:

<color>

Discussion:

The usual definition of the color green.

See also:

$hearts-stipple Constant

A stipple pattern for use in creating a patterned brush that draws a heart shape.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush that draws a heart shape.

See also:

$horizontal-hatch Constant

A stipple pattern for use in creating a patterned brush with alternating horizontal rows of lines and spaces.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with alternating horizontal rows of lines and spaces.

See also:

<image> Abstract Class

The class for objects that are images.

Superclasses:

<ink>

Discussion:

The class for objects that are images.

Operations:

The following operation is exported from the DUIM-DCs module.

The following operation is exported from the DUIM-Graphics module.

  • <graphics>

See also:

image? Generic function

Returns #t if its argument is an image.

Signature:

image? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if its argument is an image.

See also:

image-depth Generic function

Returns the depth of an image.

Signature:

image-depth image => depth

Parameters:

  • image – An instance of type <image>.

Values:

  • depth – An instance of type <real>.

Discussion:

Returns the depth of the image image.

See also:

image-height Generic function

Returns the height of an image.

Signature:

image-height image => height

Parameters:

  • image – An instance of type <image>.

Values:

  • height – An instance of type <real>.

Discussion:

Returns the height of the image image.

See also:

image-width Generic function

Returns the width of an image.

Signature:

image-width image => width

Parameters:

  • image – An instance of type <image>.

Values:

  • width – An instance of type <real>.

Discussion:

Returns the width of the image image.

See also:

<ink> Abstract Class

The class of objects that represent a way of arranging colors and opacities in the drawing plane.

Superclasses:

<object>

Discussion:

The class of objects that represent a way of arranging colors and opacities in the drawing plane. Intuitively, it is anything that can be drawn with. An ink is anything that can be used in medium-foreground, medium-background, medium-ink, or the foreground or background of a brush.

Operations:

The following operation is exported from the DUIM-DCs module.

See also:

ink? Generic function

Returns #t if its argument is an ink.

Signature:

ink? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is an ink, otherwise returns #f.

See also:

$magenta Constant

The usual definition of the color magenta.

Type:

<color>

Discussion:

The usual definition of the color magenta.

See also:

make Generic function

Returns an object that is of the same type as the class given as its argument.

Signature:

make (class == <pen>) #key width units dashes joint-shape cap-shape => pen

Signature:

make (class == <brush>) #key foreground background mode fill-style fill-rule tile stipple ts-x ts-y => brush

Parameters:

  • (class==<pen>) – The class <pen>.

  • width – An instance of type <pen-width>. Default value: 1.

  • units – An instance of type <pen-units>. Default value: #"normal".

  • dashes – An instance of type <pen-dashes>. Default value: #f.

  • joint-shape – An instance of type <pen-joint-shape>. Default value: #"miter".

  • cap-shape – An instance of type <pen-cap-shape>. Default value: #"butt".

  • (class==<brush>) – The class <brush>.

  • foreground – An instance of type <ink>. Default value: $foreground.

  • background – An instance of type <ink>. Default value: $background.

  • mode – An instance of type <integer>. Default value: $boole-1.

  • fill-style – A (fill-style) or #f. Default value: #f.

  • fill-rule – A (fill-rule) or #f. Default value: #f.

  • tile – An (image) or #f. Default value: #f.

  • stipple – A (stipple) or #f. Default value: #f.

  • ts-x – An instance of false-or(<integer>). Default value: #f.

  • ts-y – An instance of false-or(<integer>). Default value: #f.

Values:

  • pen – An instance of type <pen>.

  • brush – An instance of type <brush>.

Discussion:

Returns an object that is of the same type as the class given as its argument. Default values for the keywords that specify object are provided, or the keywords can be given explicitly to override the defaults.

See also:

make-color-for-contrasting-color Generic function

Returns a color that is recognizably different from the main color.

Signature:

make-color-for-contrasting-color ink => color

Parameters:

  • ink – An instance of type <ink>.

Values:

  • color – An instance of type <color>.

Discussion:

Returns a color that is recognizably different from the main color.

See also:

make-contrasting-colors Function

Returns a vector of colors with recognizably different appearance.

Signature:

make-contrasting-colors n #key k => colors

Parameters:

  • n – An instance of type <integer>.

  • k – An instance of type <integer>.

  • colors – An instance of type limited(<sequence>, of: <color>).

Discussion:

Returns a vector of n colors with recognizably different appearance. Elements of the vector are guaranteed to be acceptable values for the brush: argument to the drawing functions, and do not include $foreground, $background, or nil. Their class is otherwise unspecified. The vector is a fresh object that may be modified.

If k is supplied, it must be an integer between 0 and n - 1 (inclusive), in which case make-contrasting-colors returns the k th color in the vector rather than the whole vector.

If the implementation does not have n different contrasting colors, make-contrasting-colors signals an error. This does not happen unless n is greater than eight.

The rendering of the color is a true color or a stippled pattern, depending on whether the output medium supports color.

See also:

make-contrasting-dash-patterns Function

Returns a vector of dash patterns with recognizably different appearances.

Signature:

make-contrasting-dash-patterns n #key k => dashes

Parameters:
Values:

  • dashes – An instance of type <vector>.

Discussion:

Returns a vector of n dash patterns with recognizably different appearances. If the keyword k is supplied, make-contrasting-dash-patterns returns the k th pattern. If there are not n different dash patterns, an error is signalled.

The argument n represents the number of dash patterns.

The argument k represents the index in the vector of dash patterns indicating the pattern to use.

See also:

make-device-font Function

Returns a device-specific font.

Signature:

make-device-font port font => device-font

Parameters:

  • port – An instance of type <silica>.

  • font – An instance of type <object>.

Values:

  • device-font – A font object or the name of a font.

Discussion:

Returns a device-specific font. Text styles are mapped to fonts for a port, a character set, and a text style. All ports must implement methods for the generic functions, for all classes of text style.

The objects used to represent a font mapping are unspecified and are likely to vary from port to port. For instance, a mapping might be some sort of font object on one type of port, or might simply be the name of a font on another.

Part of initializing a port is to define the mappings between text styles and font names for the port’s host window system.

make-gray-color Function

Returns a member of class <color>.

Signature:

make-gray-color luminosity #key opacity => color

Parameters:

  • luminosity – An instance of type limited(<real>, min: 0, max: 1).

  • opacity – An instance of type limited(<real>, min: 0, max: 1). Default value: 1.0.

Values:

  • color – An instance of type <color>.

Discussion:

Returns a member of class <color>. The luminance is a real number between 0 and 1 (inclusive). On a black-on-white display device, 0 means black, 1 means white, and the values in between are shades of gray. On a white-on-black display device, 0 means white, 1 means black, and the values in between are shades of gray.

See also:

make-ihs-color Function

Returns a member of the class <color>.

Signature:

make-ihs-color intensity hue saturation #key opacity => color

Parameters:

  • intensity – An instance of type limited(<real>, min: 0, max: sqrt(3)).

  • hue – An instance of type limited(<real>, min: 0, max: 1).

  • saturation – An instance of type limited(<real>, min: 0, max: 1).

  • opacity – An instance of type limited(<real>, min: 0, max: 1). Default value: 1.0.

Values:

  • color – An instance of type <color>.

Discussion:

Returns a member of class <color>. The intensity argument is a real number between 0 and sqrt(3) (inclusive). The hue and saturation arguments are real numbers between 0 and 1 (inclusive).

See also:

make-palette Generic function

Returns a member of the class <palette>.

Signature:

make-palette port #key => palette

Parameters:

  • port – An instance of type <silica>.

Values:
Discussion:

Returns a member of the class <palette>.

make-pattern Function

Returns a pattern generated from a two-dimensional array.

Signature:

make-pattern array colors => pattern

Parameters:

  • array – An instance of type <array>.

  • colors – An instance of type limited(<sequence>, of: <color>).

Values:
Discussion:

Returns a pattern design that has (array-dimension array 0) cells in the vertical direction and (array-dimension array 1} cells in the horizontal direction. array must be a two-dimensional array of non-negative integers less than the length of designs. designs must be a sequence of designs. The design in cell*i,j* of the resulting pattern is the n th element of designs, if n is the value of (aref array i j ). For example, array can be a bit-array and designs can be a list of two designs, the design drawn for 0 and the one drawn for 1. Each cell of a pattern can be regarded as a hole that allows the design in it to show through. Each cell might have a different design in it. The portion of the design that shows through a hole is the portion on the part of the drawing plane where the hole is located. In other words, incorporating a design into a pattern does not change its alignment to the drawing plane, and does not apply a coordinate transformation to the design. Drawing a pattern collects the pieces of designs that show through all the holes and draws the pieces where the holes lie on the drawing plane. The pattern is completely transparent outside the area defined by the array.

Each cell of a pattern occupies a 1 by 1 square. You can use transform-region to scale the pattern to a different cell size and shape, or to rotate the pattern so that the rectangular cells become diamond-shaped. Applying a coordinate transformation to a pattern does not affect the designs that make up the pattern. It only changes the position, size, and shape of the cells’ holes, allowing different portions of the designs in the cells to show through. Consequently, applying make-rectangular-tile to a pattern of nonuniform designs can produce a different appearance in each tile. The pattern cells’ holes are tiled, but the designs in the cells are not tiled and a different portion of each of those designs shows through in each tile.

make-rgb-color Function

Returns a member of class <color>.

Signature:

make-rgb-color red green blue #key opacity => color

Parameters:

  • red – An instance of type limited(<real>, min: 0, max: 1).

  • green – An instance of type limited(<real>, min: 0, max: 1).

  • blue – An instance of type limited(<real>, min: 0, max: 1).

  • opacity – An instance of type limited(<real>, min: 0, max: 1). Default value: 1.0.

Values:

  • color – An instance of type <color>.

Discussion:

Returns a member of class <color>. The red, green, and*blue* arguments are real numbers between 0 and 1 (inclusive) that specify the values of the corresponding color components.

When all three color components are 1, the resulting color is white. When all three color components are 0, the resulting color is black.

See also:

make-stencil Function

Returns a pattern design generated from a two-dimensional array.

Signature:

make-stencil array => stencil

Parameters:

  • array – An instance of type <array>.

Values:
Discussion:

Returns a pattern design that has (array-dimension array 0) cells in the vertical direction and (array-dimension array 1) cells in the horizontal direction. array must be a two-dimensional array of real numbers between 0 and 1 (inclusive) that represent opacities. The design in cell i,j of the resulting pattern is the value of (make-opacity (aref array i j)).

make-text-style Function

Returns an instance of <text-style>.

Signature:

make-text-style family weight slant size #key underline? strikeout? => text-style

Parameters:

  • family – An instance of type one-of(#"fix", #"serif", #"sans-serif", #f).

  • weight – An instance of type one-of(#"normal", #"condensed", #"thin", #"extra-light", #"light", #"medium", #"demibold", #"bold", #"extra-bold", #"black", #f).

  • slant – An instance of type one-of(#"roman", #"italic", #"oblique", #f).

  • size – An instance of <integer>, or an instance of type one-of(#"normal", #"tiny", #"very-small", #"small", #"large", #"very-large:", #"huge", #"smaller", #"larger", #f).

  • underline? – An instance of type <boolean>.

  • strikeout? – An instance of type <boolean>.

Values:
Discussion:

Returns an instance of <text-style>.

Text style objects have components for family, face, and size. Not all of these attributes need be supplied for a given text style object. Text styles can be merged in much the same way as pathnames are merged; unspecified components in the style object (that is, components that have #f in them) may be filled in by the components of a default style object. A text style object is called fully specified if none of its components is #f, and the size component is not a relative size (that is, neither #"smaller" nor #"larger").

If size is an integer, it represents the size of the font in printer’s points.

Implementations are permitted to extend legal values for family, face, and size.

See also:

merge-text-styles Generic function

Merges two text styles and returns a new text style that is the same as the first, except that unspecified components in are filled in from the second.

Signature:

merge-text-styles text-style default-style => text-style

Parameters:
Values:
Discussion:

Merges the text styles text-style with default-style, that is, returns a new text style that is the same as text-style, except that unspecified components in style1 are filled in from default-style. For convenience, the two arguments may be also be style specs. Note that default-style must be a fully specified text style.

When merging the sizes of two text styles, if the size from the first style is a relative size, the resulting size is either the next smaller or next larger size than is specified by default-style. The ordering of sizes, from smallest to largest, is #"tiny", #"very-small", #"small", #"normal", #"large", #"very-large", and #"huge".

See also:

<palette> Abstract Instantiable Class

The protocol class for color palettes.

Superclasses:

<object>

Discussion:

The protocol class for color palettes.

Operations:

See also:

palette? Generic function

Returns #t if an object is a palette.

Signature:

palette? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if the object object is a palette. A palette is a color map that maps 16 bit colors into a, for example, 8 bit display.

See also:

<palette-full> Concrete Sealed Class

The class for errors that are signalled when a color palette is full.

Superclasses:

<error>

Init-Keywords:

  • palette –

Discussion:

The class for errors that are signalled when a color palette is full.

See also:

$parquet-stipple Constant

A stipple pattern for use in creating a patterned brush that looks like a parquet floor.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush that looks like a parquet floor.

See also:

<pattern> Concrete Sealed Class

The class for patterns.

Superclasses:

<stencil>

Init-Keywords:

  • colors – An instance of type limited(<sequence>, of: <color>).

Discussion:

The class for patterns. A pattern is a bounded rectangular arrangement of color, like a checkerboard. Drawing a pattern draws a different design in each rectangular cell of the pattern.

Operations:

The following operation is exported from the DUIM-DCs module.

See also:

pattern? Generic function

Returns #t if its argument is a pattern.

Signature:

pattern? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a pattern.

See also:

<pen> Abstract Instantiable Class

The protocol class for pens.

Superclasses:

<object>

Init-Keywords:

  • width – An instance of type <integer>. Default value: 1.

  • units – An instance of type one-of(#"normal", #"point", #"device") . Default value: #"normal".

  • dashes – An instance of type-union(<boolean>, <sequence>). Default value: #f.

  • joint-shape – An instance of type one-of(#"miter", #"bevel", #"round", #"none"). Default value: #"miter".

  • cap-shape – An instance of type one-of(#"butt", #"square", #"round", #"no-end-point"). Default value: #"butt".

Discussion:

The protocol class for pens. A pen imparts ink to a medium.

Operations:

The following operations are exported from the DUIM-DCs module.

See also:

pen? Generic function

Returns #t if its argument is a pen.

Signature:

pen? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if object is a pen, otherwise returns #f.

See also:

pen-cap-shape Generic function

Returns the shape of the end of a line or an arc drawn by the pen.

Signature:

pen-cap-shape pen => value

Parameters:

  • pen – An instance of type <pen>.

Values:

  • value – An instance of type one-of(#"butt", #"square", #"round", #"no-end-point").

Discussion:

Returns the shape of the end of a line or an arc drawn by pen.

See also:

pen-dashes Generic function

Returns #t if the lines drawn by a pen are dashed.

Signature:

pen-dashes pen => value

Parameters:

  • pen – An instance of type <pen>.

Values:

  • value – An instance of type type-union(<boolean>, <sequence>).

Discussion:

Returns #t if the lines drawn by pen are dashed. The sequence is a vector of integers indicating the pattern of dashes. There must be an even number of integers. The odd elements in the list indicate the length of the inked dashes and the even elements indicate the length of the gaps between dashes.

See also:

pen-joint-shape Generic function

Returns the shape of the joints between line segments of a closed, unfilled figure.

Signature:

pen-joint-shape pen => value

Parameters:

  • pen – An instance of type <pen>.

  • value – An instance of type one-of(#"miter", #"bevel", #"round", #"none").

Discussion:

Returns the shape of the joints between line segments of a closed, unfilled figure drawn by pen.

See also:

pen-units Generic function

Returns the units in which the pen width is specified.

Signature:

pen-units pen => value

Parameters:

  • pen – An instance of type <pen>.

Values:

  • value – An instance of type one-of(#"normal", #"point", #"device").

Discussion:

Returns the units in which the pen width is specified. They may be normal, points, or device-dependent. A width of #"normal" is a comfortably visible thin line.

See also:

pen-width Generic function

Returns the pen-width, that is how wide a stroke the pen draws, of its argument.

Signature:

pen-width pen => width

Parameters:

  • pen – An instance of type <pen>.

Values:

  • width – An instance of type <pen-width>. The units that specify the width of the pen may be #"normal", #"points", or #"device".

Discussion:

Returns the pen width, that is how wide a stroke the pen draws, of pen . A width of #"normal" is a comfortably visible thin line.

See also:

read-image Generic function

Reads an image.

Signature:

read-image resource-id #key image-type: image-type #all-keys => image

Parameters:

  • locator – An instance of type type-union(<string>, <locator>).

  • image-type – On Windows, an instance of type one-of(#"bitmap", #"icon").

Values:

  • image – An instance of type <image>.

Discussion:

Reads an image from the location resource-id. This function calls read-image-as.

See also:

read-image-as Generic function

Reads an image.

Signature:

read-image-as class locator image-type #key #all-keys => image

Parameters:

  • class – An instance of type <object>.

  • locator – An instance of type <string>.

  • image-type – On Windows, #"bitmap" or #"icon".

Values:

  • image – An instance of type <image>.

Discussion:

Reads the image in the location pointed to be locator, as an instance of a particular class*.* This function is called by read-image.

The class represents the class that the image is read as an instance of.

See also:

$red Constant

The usual definition of the color red.

Type:

<color>

Discussion:

The usual definition of the color red.

See also:

remove-colors Generic function

Removes one or more colors from a palette and returns the updated palette.

Signature:

remove-colors palette #rest colors => palette

Parameters:

  • palette – An instance of type <palette>.

  • colors – Instances of type <color>.

Values:

  • palette –

Discussion:

Removes colors from palette and returns the updated palette.

$solid-pen Constant

A pen that draws a solid line.

Type:

<pen>

Discussion:

A pen that draws a solid line. The width of the line is 1, and dashes: is #f.

See also:

<stencil> Concrete Sealed Class

The class for stencils.

Superclasses:

<image>

Init-Keywords:

  • array – An instance of type <array>. Required.

  • transform – An instance of type <transform>. Default value: #f.

Discussion:

The class for stencils. A stencil is a special kind of pattern that contains only opacities.

Operations:

The following operations are exported from the DUIM-DCs module.

The following operation is exported from the DUIM-Geometry module.

See also:

stencil? Generic function

Returns #t if its argument is a stencil.

Signature:

stencil? object => boolean

Parameters:

  • object – An instance of type <object>.

Values:
Discussion:

Returns #t if its argument is a stencil.

See also:

<text-style> Abstract Instantiable Class

The protocol class for text styles.

Superclasses:

<object>

Init-Keywords:

  • family – An instance of type one-of(#"fix", #"serif", #"sans-serif", #f). Default value: #f.

  • weight – An instance of type one-of(#"normal", #"condensed", #"thin", #"extra-light", #"light", #"medium", #"demibold", #"bold", #"extra-bold", #"black", #f).

  • slant – An instance of type one-of(#"roman", #"italic", #"oblique", #f).

  • size – An instance of <integer>, or an instance of type one-of(#"normal", #"tiny", #"very-small", #"small", #"large", #"very-large:", #"huge", #"smaller", #"larger", #f). Default value: #f.

  • underline? – An instance of type <boolean>. Default value: #f.

  • strikeout? – An instance of type <boolean>. Default value: #f.

Discussion:

The protocol class for text styles. When specifying a particular appearance for rendered characters, there is a tension between portability and access to specific font for a display device. DUIM provides a portable mechanism for describing the desired text style in abstract terms. Each port defines a mapping between these abstract style specifications and particular device-specific fonts. In this way, an application programmer can specify the desired text style in abstract terms secure in the knowledge that an appropriate device font will be selected at run time. However, some applications may require direct access to particular device fonts. The text style mechanism supports specifying device fonts by name, allowing the programmer to sacrifice portability for control.

If size: is specified as an integer, then it represents the font size in printer’s points.

Operations:

The following operations are exported from the DUIM-DCs module.

The following operations are exported from the DUIM-Sheets module.

See also:

text-style? Generic function

Returns #t if its argument is a text-style.

Signature:

text-style? object => text-style?

Parameters:

  • object – An instance of type <object>.

Values:

  • text-style? – An instance of type <boolean>.

Discussion:

Returns #t if its argument is a text-style.

See also:

text-style-components Generic function

Returns the components of a text style as the values family, face, slant, size, underline and strikeout.

Signature:

text-style-components text-style => family weight slant size underline? strikeout?

Parameters:

  • text-style – An instance of type <text-style>.

  • slant – An instance of type one-of(#"roman", #"italic", #"oblique", #f).

Values:

  • family – An instance of type one-of(#"fix", #"serif", #"sans-serif", #f).

  • weight – An instance of type one-of(#"normal", #"condensed", #"thin", #"extra-light", #"light", #"medium", #"demibold", #"bold", #"extra-bold", #"black", #f).

  • size – An instance of <integer>, or an instance of type one-of(#"normal", #"tiny", #"very-small", #"small", #"large", #"very-large:", #"huge", #"smaller", #"larger", #f). Default value: #f.

  • underline? – An instance of type <boolean>.

  • strikeout? – An instance of type <boolean>.

Discussion:

Returns the components of the text style text-style as the values family, face, slant, size, underline and strikeout.

See also:

text-style-family Generic function

Returns the family component of the specified text style.

Signature:

text-style-family text-style => family

Parameters:
Values:

  • family – An instance of type one-of(#"fix", #"serif", #"sans-serif", #f).

Discussion:

Returns the family component of the specified text style.

See also:

text-style-size Generic function

Returns the style component of the specified text style.

Signature:

text-style-size text-style => size

Parameters:
Values:

  • size – An instance of <integer>, or an instance of type one-of(#"normal", #"tiny", #"very-small", #"small", #"large", #"very-large:", #"huge", #"smaller", #"larger", #f). Default value: #f.

Discussion:

Returns the style component of the specified text style.

See also:

text-style-slant Generic function

Returns the slant component of the specified text style.

Signature:

text-style-slant text-style => slant

Parameters:
Values:

  • slant – An instance of type one-of(#"roman", #"italic", #"oblique", #f).

Discussion:

Returns the slant component of the specified text style.

See also:

text-style-strikeout? Generic function

Returns #t if the text style includes a line through it, striking it out.

Signature:

text-style-strikeout? text-style => strikeout?

Parameters:
Values:

  • strikeout? – An instance of type <boolean>.

Discussion:

Returns #t if the text style includes a line through it, striking it out.

See also:

text-style-underline? Generic function

Returns #t if the text style is underlined.

Signature:

text-style-underline? text-style => underline?

Parameters:
Values:

  • underline? – An instance of type <boolean>.

Discussion:

Returns #t if the text style is underlined.

See also:

text-style-weight Generic function

Returns the weight component of the specified text style.

Signature:

text-style-weight text-style => weight

Parameters:
Values:

  • weight – An instance of type one-of(#"normal", #"condensed", #"thin", #"extra-light", #"light", #"medium", #"demibold", #"bold", #"extra-bold", #"black", #f).

Discussion:

Returns the weight component of the text style.

See also:

$tiles-stipple Constant

A stipple pattern for use in creating a patterned brush with lines and spaces suggesting tiles

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with lines and spaces suggesting tiles

See also:

$vertical-hatch Constant

A stipple pattern for use in creating a patterned brush with alternating vertical columns of lines and spaces.

Type:

<array>

Discussion:

A stipple pattern for use in creating a patterned brush with alternating vertical columns of lines and spaces.

See also:

$white Constant

The usual definition of white.

Type:

<color>

Discussion:

The usual definition of white. In the rgb color model, its value is 111.

See also:

write-image Generic function

Writes out a copy of an image to disk (or other designated medium).

Signature:

write-image image locator => ()

Parameters:

  • image – An instance of type <image>.

  • locator – An instance of type <string>.

Discussion:

Writes out a copy of image to the designated medium locator.

$xor-brush Constant

A standard brush with the drawing property of $boole-xor.

Type:

<brush>

Discussion:

A standard brush with the drawing property of $boole-xor.

$yellow Constant

The usual definition of the color yellow.

Type:

<color>

Discussion:

The usual definition of the color yellow.

See also: