Full Documentation: Graphics Procedures

Icon version 9.5.20f

attribs.icn: Procedure to set attributes via dialog

procedure attribs:         set graphics attributes via dialog

link attribs
February 17, 1997; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure produces a dialog in which the user can change
the most commonly used graphics attributes.

Problems:  If a text-entry field is not long enough to hold the current
value for an attribute, the attribute has to be edited.  Also, a
slider is not the best way of changing the gamma attribute -- it's
not possible to set a precise value.  A slider was used mostly for
demonstration purposes.

[ Summary entry | Source code ]


autopost.icn: Procedures to activate PostScript recorder

link autopost
October 11, 1994; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures, when linked with an unsuspecting Icon program,
cause psrecord (q.v) to begin recording PostScript commands when
an X window is opened.  This is done by overloading the built-in
"open" function.

The results of this may or may not be usable depending on how the
original program is coded.  Psrecord cannot emulate all the X calls
and works best with programs designed for it.

"stop" and "exit" are also overloaded to try and terminate the
PostScript file properly.  Other program exit paths, notably a
return from the main procedure, are not caught.

[ Summary entry | Source code ]


barchart.icn: Procedures for dynamically growing barchart

procedure barchart:        draw barchart
procedure setbar:          set bar value on barchart
procedure rebar:           redraw barchart

link barchart
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures draw barcharts that can grow dynamically.

barchart(win, x, y, dx, dy, sf, n, l, w, b) creates a barchart.

setbar(bc, n, v)        sets the value of a bar.

rebar(bc, sf)           redraws a barchart with a new scaling factor.
____________________________________________________________

barchart(win, x, y, dx, dy, sf, n, l, w, b) -- establish a barchart

    win      window
    x,y      position of base of first bar
    dx,dy    distance to base of second bar (either dx or dy should be
              zero)
    sf       scaling (pixels per unit of value, + or -, need not be
              integer)
    n        number of bars
    l,w      length (maximum) and width of one bar
    b        logarithmic base, if bars are to be scaled logarithmically

    barchart() establishes structures for building a barchart.  Any of the
    eight possible orthogonal orientations can be selected depending on the
    signs of dx, dy, and sf.

    The absolute value of sf establishes a linear scaling from barchart
    values to number of pixels.  Scaling is handled such that a value of 1
    makes the first mark on a bar and then each increment of sf lengthens
    the bar by one pixel.  If a bar would exceed the limit then the entire
    chart is rescaled so that only half the range is then used.

setbar(bc, n, v) - set bar n of barchart bc to represent value v

    It is assumed that v>0 and that bars never shrink; but they may grow.

rebar(bc, sf) - redraw barchart with new scaling factor sf.

    sf is assumed to be of the same sign as the previous scaling factor.

Example:

    Suppose "scores" is a list of scores ranging from 0 to 100.
    This code fragment dynamically draws a histogram using 21 bins.

    The call to barchart() specifies:
        The lower left-hand corner of the barchart is (10, 190).
        The next bar is 10 pixels to its right, which would be (20, 190).
        The bars grow upward, to smaller y values, so the scaling factor
        is negative; each score will grow its bar by 5 pixels.
        Each bar grows to a maximum length of 180 pixels; the width is 8.
        No base is given, so scaling is linear.

    bc := barchart(win, 10, 190, 10, 0, -5, 21, 180, 8)
    b := list(21, 0)                # histogram bins
    every n := !scores do {
        i := n / 5                  # bin (and bar) number
        b[i] +:= 1                  # increment bin count
        setbar(bc, i, b[i])         # update display
        }

[ Summary entry | Source code ]


bevel.icn: Procedures for drawing beveled objects

procedure BevelReset:      set colors for beveled drawing
procedure BevelCircle:     draw beveled circle
procedure BevelDiamond:    draw beveled diamond
procedure BevelSquare:     draw beveled square
procedure RidgeRectangle:  draw ridged rectangle
procedure GrooveRectangle: draw grooved rectangle
procedure BevelRectangle:  draw beveled rectangle
procedure DrawRidge:       draw ridged line
procedure DrawGroove:      draw grooved line
procedure FillSquare:      draw filled square
procedure FillDiamond:     draw filled diamond
procedure FillTriangle:    draw filled triangle

link bevel
April 1, 1997; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures draw objects having a raised or sunken appearance.

BevelReset(win)                         sets/resets shading colors.

BevelCircle(win, x, y, r, bw)           draws a beveled circle.

BevelDiamond(win, x, y, r, bw)          draws a beveled diamond.

BevelTriangle(win, x, y, r, o, bw)      draws a beveled triangle.

BevelSquare(win, x, y, r, bw)           draws a beveled square.

FillSquare(win, x, y, r)                fills a square.

FillDiamond(win, x, y, r)               fills a diamond.

FillTriangle(win, x, y, r, o)           fills a triangle.

RidgeRectangle(win, x, y, w, h, bw)     draws a ridged rectangle.

GrooveRectangle(win, x, y, w, h, bw)    draws a grooved rectangle.

BevelRectangle(win, x, y, w, h, bw)     draws a beveled rectangle.

DrawRidge(win, x1, y1, x2, y2, w)       draws a ridged line.

DrawGroove(win, x1, y1, x2, y2, w)      draws a grooved line.
____________________________________________________________

These procedures allow the drawing of buttons and other objects
with a three-dimensional appearance.  They are intended to be
used like other graphics primitives (DrawRectangle() etc.).
However, this abstraction fails if the background color changes
or if clipping is set, due to the use of cached graphics contexts.

BevelReset(win) -- set/reset colors for beveling
     This procedure is called automatically by the others.
     It can be called explicitly if the background color is changed.

BevelCircle(win, x, y, r, bw) -- draw beveled circle
BevelDiamond(win, x, y, r, bw) -- draw beveled diamond
BevelTriangle(win, x, y, r, o, bw) -- draw beveled triangle
BevelSquare(win, x, y, r, bw) -- draw beveled square
     These procedures draw a figure centered at (x,y) and having
     a "radius" of r.  bw is the bevel width, in pixels.
     o is the triangle orientation: "n", "s", "e", or "w".

FillSquare(win, x, y, r) -- fill square centered at (x,y)
FillDiamond(win, x, y, r) -- fill diamond centered at (x,y)
FillTriangle(win, x, y, r, o) -- fill triangle centered at (x,y)
     These procedures complement the beveled outline procedures
     by filling a figure centered at (x,y).  Fillcircle is already
     an Icon function and so is not included here.

RidgeRectangle(win, x, y, w, h, bw) -- draw ridged rectangle
GrooveRectangle(win, x, y, w, h, bw) -- draw grooved rectangle
BevelRectangle(win, x, y, w, h, bw) -- draw beveled rectangle
     These procedures draw a rectangle with the given external
     dimensions and border width.  Beveled rectangles are raised
     if bw > 0 or sunken if bw < 0.

DrawRidge(win, x1, y1, x2, y2, w) -- draw a ridged line
DrawGroove(win, x1, y1, x2, y2, w) -- draw a grooved line
     These procedures draw a groove or ridge of width 2 at any angle.
     If w = 0, a groove or ridge is erased to the background color.

For BevelSquare() and FillSquare(), the width drawn is 2 * r + 1,
not just 2 * r.  This is necessary to keep the visual center at the
specified (x, y) and is consistent with the other centered procedures
and the built-in function FillCircle.

[ Summary entry | Source code ]


bitplane.icn: Procedures for bitplane manipulation

procedure AlcPlane:        allocate colors for bitplane
procedure FrontPlane:      move bitplane to front
procedure BackPlane:       move bitplane to back
procedure PlaneOp:         set context for bitplane operation

link bitplane
May 2, 2001; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures allow a window to be treated as a series of
overlapping, independent layers, subject to some fairly severe
restrictions.

AlcPlane(W n)           allocates planes.

FrontPlane(W bp, color) moves a layer to the front.

BackPlane(W bp, color)  moves a layer to the back.

PlaneOp(W bp, op)       initializes layer operations.

Deplane(W color)        restores a window to normal.
____________________________________________________________

   These procedures allow drawing and erasing in individual bitplanes of
a window.  One way to use bitplanes is to think of them as transparent
panes in front of a solid background.  Each pane can be drawn with a
single color, obscuring the panes beyond (and the background).  A pane
can also be erased, wholly or selectively, exposing what is beyond; and
a pane need not be visible to be drawn or erased.  Panes can be restacked
in a different order, and the color of a pane (or the background) can be
changed.

   For example, the pane in back could be drawn with a city map.  The
pane in front of that could be used to lay out bus routes, and the paths
could be erased and rerouted without having to redraw the map.  Using a
third plane in front of those, buses could be moved along the routes
without having to redraw either the routes or the map behind them.

   Bitplanes that are allocated together and interact with each other
form a bitplane group.  A bitplane group need not fill the window;
indeed, it can be used in discontiguous portions of a window or even
in multiple windows on the same display.  On the other hand, multiple
bitplane groups can be used different parts of the same window.

   Bitplanes are implemented using Icon's mutable colors, and they
are gluttonous of color map entries.  A set of n bitplanes requires
at least 2^n color map entries, so the practical limit of n is 5 or 6.
On the other hand, sets of 2 or 3 bitplanes are relatively cheap and
using several of them is not unreasonable.

   Each bitplane group is identified by a base index b, which is the
index of the mutable color representing the background.  The individual
bitplanes are referenced as b+1, b+2, b+4 etc. using powers of two.
Other indices between b and b+2^n (exclusive) control the colors used
used when multiple bitplanes are drawn.  The FrontPlane and BackPlane
procedures provides simple control of these, and more sophisticated
effects (such as making a bitplane partially transparent) are possible
by setting them individually.



AlcPlane([win,] n) -- alc colors for n bitplanes

   AlcPlane allocates a set of 2^n mutable colors chosen to be suitable
for the bitplane manipulations described below.  The colors are
consecutively indexed, and the base value b (the most negative index
value) is returned.  The base color is initialized to the current
background color, and the others are initialized to the foreground color.

   A sequence of AlcPlane calls with different values of n is more
likely to succeed if the larger sets are allocated first.



FrontPlane([win,] bp, color) -- move indexed plane to "front"

   FrontPlane sets the pixels in a bitplane to the given color and
moves the bitplane in front of the others in the set.  The color is
optional.

   bp is the index (base+1, base+2, base+4, or whatever) denoting a
particular bitplane.  The move-to-the-front effect is accomplished by
calling Color() for all colors in the bitplane group whose index
after subtracting the base includes the particular bit.



BackPlane([win,] bp, color) -- move indexed plane to "back"

   BackPlane sets the pixels in a bitplane to the given color and
moves the bitplane in back of the others in the set.  The color is
optional.

   bp is the index (base+1, base+2, base+4, or whatever) denoting a
particular bitplane.  The move-to-the-back effect is accomplished by
calling Color() for all colors in the bitplane group whose index
after subtracting the base includes the particular bit.

   A plane can be effectively rendered invisible by calling
BackPlane(win, bp, base);  this moves it to the back and sets
its color to the color of the background plane.



PlaneOp([win,] bp, op) -- set graphics context for plane operation

   PlaneOp initializes the graphics context for drawing or erasing in
a particular bitplane.  bp is a bitplane index, as for FrontPlane;
multiple bits can be set to draw or erase several bitplanes
simultaneously.  op is usually one of two strings:

     "set"   to draw the bits in a bitplane
     "clear" to erase the bits in a bitplane

Subsequent drawing operations will affect only the bits in the selected
bitplane.  Foreground operations are used for both drawing and erasure:
use FillRectangle, not EraseArea.

   After calling PlaneOp with "set" or "clear", be SURE to draw only
in portions of the screen previously initialized with pixel values
from the same bitplane group.  Drawing anywhere else is liable to
produce strange, unwanted results.  Deplane (below) resets the window
for normal operation.

   The op parameter can also be "copy", in which case the previous
contents of the window are immaterial and the drawn pixels are
initialized with the bitplanes specified.


Deplane([win,] color) -- restore normal drawop and set foreground

   Deplane is called to restore normal drawing operations after setting
or clearing bits in a particular bitplane.  The foreground color can be
changed optionally.



Example:

     b := AlcPlane(win, 3)                   # get 3 planes
     Color(win, b, "white")                  # background will be white
     FrontPlane(win, 1, "gray")              # city map will be gray
     FrontPlane(win, 2, "navy")              # routes will be dark blue
     FrontPlane(win, 4, "red")               # buses will be red
     Fg(win, b)
     DrawRectangle(win, x, y, w, h)          # initialize background
     PlaneOp(win, b+1, "set")
     drawmap()                               # draw map
     repeat {
        PlaneOp(win, b+2, "clear")
        DrawRectangle(x, y, w, h)            # clear old routes
        PlaneOp(win, b+2, "set")
        drawroutes()                         # draw new routes
        while routes_ok() do
           runbuses()                        # run buses using plane b+4
        }



Caveats

   AlcPlane must repeatedly ask for new mutable colors until it gets a
set that is suitable.  Unwanted colors cannot be returned or freed, so
some color table entries are usually wasted.

   No more than 7 bitplanes can be requested, and even that is chancy.

   These routines will be confused by multiple displays.  Multiple
windows on a single display, or multiple bitplane sets in a window,
are no problem.

   These routines depend on the internals of Icon, specifically the
mapping of window-system pixel values to mutable color indices.

   The use of unusual "and" and "or" drawops makes the code hard to
understand.

[ Summary entry | Source code ]


button.icn: Procedures for pushbutton sensors

link button
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
See also: evmux.icn
This file is in the public domain.

These procedures implement pushbuttons using the "evmux" event
multiplexor instead of the usual vidget library.

button(win, label, proc, arg, x, y, w, h)
                                establishes a pushbutton.

buttonrow(win,x,y,w,h,dx,dy, label,proc,arg, label,proc,arg, ...)
                                establishes a row of buttons.

buttonlabel(handle, label)      changes a button label.
____________________________________________________________

It is assumed that buttons do not overlap, and that fg, bg, and font
do not change beyond the initial call.  These restrictions can be
accommodated if necessary by using a window clone.

button(win, label, proc, arg, x, y, w, h)

    establishes a button of size (w,h) at (x,y) and returns a handle.
    "label" is displayed as the text of the button.
    When the button is pushed, proc(win, arg) is called.

    If proc is null, the label is drawn with no surrounding box, and
    the button is not sensitive to mouse events.  This can be used to
    insert a label in a row of buttons.

buttonlabel(handle, label)

    changes the label on a button.

buttonrow(win,x,y,w,h,dx,dy, label,proc,arg, label,proc,arg, ...)

    establishes a row (or column) of buttons and returns a list of handles.
    Every button has size (w,h) and is offset from its predecessor by
    (dx,dy).

    (x,y) give the "anchor point" for the button row, which is a corner
    of the first button.  x specifies the left edge of that button unless
    dx is negative, in which case it specifies the right edge.  Similarly,
    y is the top edge, or the bottom if dy is negative.

    One button is created for each argument triple of label,proc,arg.
    An extra null argument is accepted to allow regularity in coding as
    shown in the example below.

    If all three items of the triple are null, a half-button-sized
    gap is inserted instead of a button.

Example:

    Draw a pushbutton at (x,y) of size (w,h);
    then change its label from "Slow" to "Reluctant"
    When the button is pushed, call setspeed (win, -3).

            b := button (win, "Slow", setspeed, -3, x, y, w, h)
            buttonlabel (b, "Reluctant")

    Make a set of buttons extending to the left from (490,10)

            blist := buttonrow(win, 490, 10, 50, 20, -60, 0,
                "fast", setspeed, +3,
                "med", setspeed, 0,
                "slow", setspeed, -3,
                )

[ Summary entry | Source code ]


cardbits.icn: Procedure for constructing playing card images

link cardbits
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
See also: drawcard.icn

cardbits() returns an image for use in drawing playing cards.
____________________________________________________________

   cardbits() returns a bilevel image used by the drawcard() library
procedure (q.v.).  The image contains many small subimages for use in
constructing playing cards.  The images were collected from the
individual X bitmaps of the highly recommended "Spider" solitaire game
that is included as a sample program with the XView toolkit for
X-windows.

Overall structure: 160w x 432h bilevel bitmap.
     Red area: union of two rectangles (0,0,160,188) (0,404,117,28)
     Black area: union of two rectangles (0,188,160,216) (117,404,43,28)

Pips: 16x20 heart, diamond, club, spade at (144, {0,94,188,282})
                      rotated versions    at (144, {20,114,208,302})
Small pips:  9x14 H, D, C, S      at (148, {40,134,228,322})
                      rotated versions    at (148, {54,148,242,336})
Large spade, for the Ace: 43x56 at (117,376)
Ranks: 9x14 A,2,3,4,5,6,7,8,9,J,Q,K  at ({0,12,24,...,144}, 376)
                     rotated versions at ({0,12,24,...,144}, 390)
                     both rows duplicated at ({0,...144}, {404,418})
Faces: 48x94 images including 1-pixel-wide frame.
     Three columns (J,Q,K) of four rows (H,D,C,S)
     at ({0,48,96},{0,94,188,282}).

[ Summary entry | Source code ]


cells.icn: Procedures for creating and coloring panels of cells

procedure makepanel:       make panel of cells
procedure colorcell:       color cell in panel
procedure colorcells:      color all cells in panel
procedure tiercells:       color all cells in panel

link cells
December 16, 2002; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures create an manipulate panels of cells.

     makepanel(n, m, size, fg, bg, pg)
             makes a panel in a hidden window with nxm cells of the
             given size, default 10.  fg, bg, and pg are the
             colors for the window and panel backgrounds. fg
             and bg default to black and white, respectively.
             If pg is not given a patterned background is used.

     matrixpanel(matrix, size, fg, bg, pg)
             same as makepanel(), except matrix determines the
             dimensions.

     clearpanel(panel)
             restores the panel to its original state as made by
             makepanel.

     colorcell(panel, n, m, color)
             colors the cell (n,m) in panel with color.

     colorcells(panel, tier)
             is like colorcell(), except it operates on a tie-up
             record.

     cell(panel, x, y)
             returns Cell() record for the cell in which x,y
             lies.  If fails if the point is out of bounds.

     tiercells(panel, matrix)
             is like colorcell(), except all cells are colored
             using a matrix of colors.

[ Summary entry | Source code ]


clip.icn: Procedures for clipboard operations

link clip
May 26, 1994; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

XCopy(window, x, y, w, h) copies an area of window to the clipboard.

XCut(window, x, y, w, h) copies an area of window to the clipboard and
erases it from window.

XPaste(window, x, y) copies the clipboard to position x,y in window.

NewClip(w, h) is a utility procedure that discards the old clipboard and
creates a new one of the specified dimensions.

[ Summary entry | Source code ]


clipping.icn: Procedures for clipping lines

procedure DrawClipped:     draw line with clipping
procedure ClipLine:        clip line for DrawSegment
procedure Coalesce:        connect adjoining segments

link clipping
June 16, 2000; William S. Evans and Gregg M. Townsend
This file is in the public domain.

ClipLine(W, L, x, y, w, h) clips the multisegment line specified
by coordinates in L to the region (x, y, w, h), which defaults
to the clipping region of the window W.  ClipLine() returns a
list of coordinates suitable for calling DrawSegment().  If no
segments remain after clipping, ClipLine() fails.

Coalesce(L) connects adjoining segments from a DrawSegment()
argument list such as is produced by ClipLine().  Coalesce()
returns a list of DrawLine() lists.

DrawClipped(W, x1, y1, x2, y2, ...) draws a line using ClipLine()
with the clipping region of the window W.  DrawClipped() is
superior to DrawLine() only when lines with extremely large
coordinate values (beyond +/-32767) are involved.

[ Summary entry | Source code ]


clrnames.icn: Procedure to generate color names

link clrnames
March 4, 1995; Ralph E. Griswold
This file is in the public domain.

This procedure generates all the color names in the Icon portable color
naming system.  Not all names produce unique colors.

[ Summary entry | Source code ]


clrutils.icn: Procedures to convert color formats

procedure colortorgb:      rgb record for color

link clrutils
September 17, 1998; Ralph E. Griswold
This file is in the public domain.

These procedures convert between comma-separated Icon color
specifications and a record with r, g, and b fields.

[ Summary entry | Source code ]


color.icn: Procedures dealing with colors

procedure ScaleGamma:      scale with gamma correction
procedure Blend:           generate sequence of colors
procedure Contrast:        choose contrasting color
procedure Shade:           dither shade using pattern
procedure RandomColor:     choose random color
procedure PaletteGrays:    grayscale entries from palette
procedure RGBKey:          return palette key for color
procedure HSVKey:          nearest key from HSV specification
procedure HSV:             HSV interpretation of color
procedure HSVValue:        color value of HSV specification
procedure HLS:             HLS interpretation of color
procedure HLSValue:        color value of HLS specification

link color
April 1, 1997; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures deal with colors in various ways.

ScaleGamma(v, g)        scales a number with gamma correction.

Blend(k1, k2, ...)      generates a sequence of colors.

Contrast(win, k)        returns "white" or "black" contrasting with k.

Shade(win, k)           sets Fg(), with dithering on a bilevel screen.

RandomColor(W, p)       returns a randomly chosen color from a palette.

PaletteGrays(W, p)      returns the gray entries of a palette.

RGBKey(W, p, r, g, b)   returns the palette key closest to (r,g,b).

HSVKey(W, p, h, s, v)   returns the palette key closest to (h/s/v).

HSV(k)                  returns the h/s/v interpretation of a color.

HSVValue(hsv)           returns the ColorValue() of an h/s/v string.

HLS(k)                  returns the h:l:s interpretation of a color.

HLSValue(hls)           returns the ColorValue() of an h:l:s string.
____________________________________________________________

ScaleGamma(v, g) nonlinearly scales the number v (between 0.0 and 1.0)
to an integer between 0 and 65535 using a gamma correction factor g.
the default value of g is 2.5.

Blend(color1, color2, color3,...) generates ColorValue(color1), then
some intermediate shades, then ColorValue(color2), then some more
intermediate shades, and so on, finally generating the color value of
the last argument.  An integer argument can be interpolated at any
point to set the number of steps (the default is four) from one color
to the next.

Contrast(win, colr) returns either "white" or "black", depending
on which provides the greater contrast with the specified color.

Shade(win, colr) sets the foreground for an area filling operation.
On a color screen, Shade() sets the foreground color and returns the
window.  On a bilevel monochrome screen, Shade() sets the foreground
to a magic-square dithering pattern approximating the luminance of the
color specified.  If the environment variable XSHADE is set to "gray"
(or "grey") then Shade simulates a multilevel grayscale monitor.
If it is set to any other value, Shade simulates a bilevel monitor.

RandomColor(win, palette) returns a randomly chosen color from the
given image palette, excluding the "extra" grays of the palette, if
any.  (Colors are selected from a small finite palette, rather than
from the entire color space, to avoid running out of colors if a
large number of random choices are desired.)  The default palette
for this procedure is "c6".

PaletteGrays([win,] palette) is like PaletteChars but it returns only
the characters corresponding to shades of gray.  The characters are
ordered from black to white, and in all palettes the shades of gray
are equally spaced.

RGBKey([win,] palette, r, g, b) returns a palette key given the
three color components as real number from 0.0 to 1.0.
HSVKey([win,] palette, h, s, v) returns a palette key given a
hue, saturation, and value as real numbers from 0.0 to 1.0.

HSV() and HSVValue() convert between Icon color strings and strings
containing slash-separated HSV values with maxima of "360/100/100".
HSV(k) returns the h/s/v interpretation of an Icon color specification;
HSVValue(hsv) translates an h/s/v value into an Icon r,g,b value.

HLS() and HLSValue() convert between Icon color strings and strings
containing colon-separated HLS values with maxima of "360:100:100".
HLS(k) returns the h:l:s interpretation of an Icon color specification;
HLSValue(hls) translates an h:l:s value into an Icon r,g,b value.

[ Summary entry | Source code ]


colorway.icn: Procedures to manipulate color ways

link colorway
August 3, 2000; Ralph E. Griswold
Requires: Version 9 graphics, UNIX for "pick feature"
See also: cw.icn
This file is in the public domain.

Note:  This file contains procedures that can be linked by programs
to add a visual interface, including programs that have one of their
own.

These procedures support the interactive creation and modification of
color ways.  ("Color way" is a the term used in the fashion industry for
a list of colors used in coordination for fabric design or other
decorative purposes.  Think color scheme if you like.)
____________________________________________________________

A color way is represented by a list of color specifications.  A
color specification consists of a name and an associated color.
Color ways are presented in alphabetical order of their color names,
with the name at the left and a swatch for the corresponding color
at the right of the name.

The "edit" button is used to switch between two modes:  control and
edit.

In the control mode, the interface menus and the "edit" button
are available. The "File" menu provides for creating a new color
way, loading an existing color way from a file, and saving the
current color way.  (Only one color way can be manipulated at a time.)
A new color way starts empty.  There also is an item to pick a colorway
file (which must have suffix "cw").

The "Ways" menu allows adding and deleting color specifications from
the current color way.  When adding, a name dialog is presented first,
followed by a color dialog.  Color specifications are added until
the user cancels one of the dialogs.  When deleting, all of the
current color specifications are listed by name, and more than one
can be selected for deletion.

In the edit mode, changes can be made to the current color way.  This is
done in the window displaying the current color way.   Clicking on a name
in the color way window produces a dialog to change that name.  (The new
name cannot be one already in use in the color way.)  Clicking on a
color swatch to the right of a name beings up a color dialog for selecting
a new color for that name.  (The same color can appear in more than one
color specification.)

In the editing mode, pressing the meta key while clicking on a
line of the color way causes the color to be deleted.

The editing mode is exited by typing a "q" in the color way display
window.

Shortcuts exist for all interface features.   @E is a shortcut for
entering the edit mode.

Note:  The current mode is shown by the "edit" button, which is high-
lighted when in the edit mode.  There nonetheless can be confusion about
the current mode.

Unimplemented feature:  Prompting user to save color way that has been
modified since last save.

[ Summary entry | Source code ]


colrlist.icn: Procedures to produce list of colors

procedure colrlist:        list of colors from file
procedure colrplte:        list of colors from palette

link colrlist
November 24, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

colrlist(f) returns a list of the colors given in a file.

colrplte(p) returns a list of colors for the palette p.

[ Summary entry | Source code ]


colrmodl.icn: Procedures to convert between color models

link colrmodl
December 5, 1995; Ralph E. Griswold
This file is in the public domain.

   These procedures convert between various color models. A color
value is represented by a record (see the declarations below).

Color values are normalized to a maximum of 1.0.
____________________________________________________________

Acknowledgement:  Some of the procedures here are based on information
given in Computer Graphics; Principles and Practice, second edition;
James D. Foley, Andries van Dam, Steven K. Feiner, and John F. Hughes;
Addison-Wesley Publishing Company; 1990.
____________________________________________________________

Note:  These procedures have not been extensively tested. Those related
to the YIQ model are particularly in question.

[ Summary entry | Source code ]


colrspec.icn: Procedure to produce VRML color specifications

link colrspec
May 3, 1997; Ralph E. Griswold
This file is in the public domain.

Requires:  Version 9 graphics

[ Summary entry | Source code ]


cwutils.icn: Procedures to support color ways

procedure list2way:        convert list of color specs. to colorway
procedure file2way:        convert file of color specs. to color way
procedure way2list:        convert color way to list of colors
procedure way2file:        convert color way to file of colors
procedure way2image:       create image from color way
procedure saveway:         save color way
procedure loadway:         load color way
procedure image2way:       convert image to color way

link cwutils
September 2, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.


[ Summary entry | Source code ]


decay.icn: Procedures for decaying-displays for windows

procedure dpipe:           create a decay pipeline
procedure decay:           mark entry for later decay

link decay
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures provide a way to draw objects and then have them
automatically redrawn (say, in a lighter color) n steps later.
A user routine is called to do the actual drawing.  If a second
call to draw an object comes before its time has expired, the
object's counter is reset and the drawing routine is not called.

dpipe() initializes a decay pipeline and returns a pipeline object.

decay() marks an object, unmarks another, and advances the clock.
____________________________________________________________

dpipe(proc, length, gc1, gc2) -- create a decay pipeline

    dpipe() initializes a decay pipeline and returns a pipeline object.

    proc    user marking procedure: proc(gc, i) marks entry i using gc
    length  length of the delay pipeline (number of steps)
    gc1     gc to mark an entry when it becomes active
    gc2     gc to mark an entry when it decays (becomes inactive)

decay(dp, i) -- mark entry i with later decay

    decay() marks an object, unmarks another, and advances the clock.

    Using decay pipe dp, entry i (anything but &null) is drawn in an
    active state, and the oldest entry in the pipe is drawn in an
    inactive state.

    Records are kept, though, so that an already-active entry is not
    redrawn, and a decayed entry reaching the end of the pipe is not
    drawn as inactive if it was more recently renewed.

    The decay pipe can be flushed by a sufficient number of
    decay(dp, &null) calls.

[ Summary entry | Source code ]


dialog.icn: Procedures for dialogs

procedure TextDialog:      text dialog
procedure ToggleDialog:    toggle dialog
procedure SelectDialog:    selection dialog
procedure Notice:          notice dialog
procedure SaveDialog:      save dialog
procedure OpenDialog:      open dialog
procedure ColorDialog:     color dialog
procedure Popup:           create popup subwindow

link dialog
December 14, 1999; Ralph E. Griswold and Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

This file contains several procedures for posting dialog boxes:

AskDialog() -- TextDialog() with only caption and "No" instead of "Cancel"
Notice(win, captions) -- notice dialog (a simple text dialog)
TextDialog(win, captions, labels, defaults...) -- text dialog
ToggleDialog(win, captions, labels, defaults...) -- toggle dialog
SelectDialog(win, captions, labels, defaults...) -- selection dialog
SaveDialog(win, caption, filename, len) -- save file dialog
OpenDialog(win, caption, filename, len) -- open file dialog
ColorDialog(win, captions, refcolor, callback, id) -- color dialog

In all cases, the first or only caption is used as a dialog box ID,
used to remember the dialog box location when it is closed.  A later
posting using the same ID places the new box at the same location.
____________________________________________________________

ColorDialog(win, captions, color, callback, id) -- display color dialog

captions     list of dialog box captions; default is ["Select color:"]
color        reference color setting; none displayed if not supplied
callback     procedure to call when the setting is changed
id           arbitrary value passed to callback

ColorDialog displays a dialog window with R/G/B and H/S/V sliders for
color selection.  When the "Okay" or "Cancel" button is pressed,
ColorDialog returns the button name, with the ColorValue of the final
settings stored in the global variable dialog_value.

If a callback procedure is specified, callback(id, k) is called whenever
the settings are changed;  k is the ColorValue of the settings.
____________________________________________________________

Popup(x, y, w, h, proc, args...) creates a subwindow of the specified
size, calls proc(args), and awaits its success or failure.  Then, the
overlaid area is restored and the result of proc is produced.  &window,
as seen by proc, is a new binding of win in which dx, dy, and clipping
have been set.  The usable area begins at (0,0);  its size is
(WAttrib(win, "clipw"), WAttrib(win, "cliph")).  Defaults are:
     x, y    positioned to center the subwindow
     w, h    250, 150
     proc    Event

[ Summary entry | Source code ]


distance.icn: Procedure to compute distance in n-dimensions

link distance
January 3, 1994; Ralph E. Griswold
This file is in the public domain.

distance(d1, d2, d3, ...) returns the distance between points in n-space
distances d1, d2, d3, ... from the origin.

[ Summary entry | Source code ]


drag.icn: Procedures for dragging rectangles

procedure Drag:            opaque rectangle drag
procedure DragOutline:     outlined rectangle drag

link drag
August 21, 1998; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures drag rectangular objects in a window.

Drag(x, y, w, h)                provides an opaque move.

DragOutline(x, y, w, h)         drags only the outline.
____________________________________________________________

Drag(x, y, w, h) lets the user move a rectangular area using the
mouse.  Called when a mouse button is pressed, Drag() handles all
subsequent events until a mouse button is released.  As the mouse
moves, the rectangular area originally at (x,y,w,h) follows it
across the screen; vacated pixels at the original location are
filled with the background color.  The rectangle cannot be dragged
off-screen or outside the clipping region.  When the mouse button
is released, Drag() sets &x and &y to the upper-left corner of the
new location and returns.

DragOutline(x, y, w, h) lets the user move a reverse-mode rectangle
using the mouse.  Called when a mouse button is pressed, DragOutline
draws a reverse-mode rectangle inside the limits of the rectangle
(x,y,w,h) and handles all subsequent events until a mouse button is
released.  As the mouse moves, the rectangle follows it.  When the
mouse button is released, the rectangle disappears, and DragOutline
sets &x and &y to the upper-left corner of the new location.  It is
up to the calling program to update the display as necessary.

[ Summary entry | Source code ]


drawcard.icn: Procedure to draw a playing card

link drawcard
December 31, 2014; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

   drawcard(win, x, y, c) draws the playing card labeled <c> with its
upper left corner at (x,y).  The card size is fixed at 80w x 124h.

   Card labelings are as follows.

       label: ABCDEFGHIJKLM NOPQRSTUVWXYZ abcdefghijklm nopqrstuvwxyz
       rank:  A23456789TJQK A23456789TJQK A23456789TJQK A23456789TJQK
       suit:  hearts....... spades....... clubs........ diamonds.....

These differ unintentionally from the card mappings used in the
"Mappings and Labelings" chapter of the Icon book (pp 243-244, 3/e).

If the label is unrecognized, the back of a card is drawn.
"-" is suggested as a conventional label for a card back.

[ Summary entry | Source code ]


drawcolr.icn: Procedure to display color list

link drawcolr
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This program displays the colors given in a list.

[ Summary entry | Source code ]


drawlab.icn: Procedure to draw figures

link drawlab
August 3, 2000; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure is a general-purpose interface used by various programs
that draw figures of various kinds.

Although it's listed as requiring graphics, that's really not necessary
for interfaces to other devices or just producing coordinates.

[ Summary entry | Source code ]


dsetup.icn: Procedures for creating dialog boxes

link dsetup
May 2, 2001; Gregg M. Townsend and Ralph E. Griswold
This file is in the public domain.

dsetup(win, wlist) initializes a set of widgets according to
a list of specifications created by the interface editor VIB.

win can be an existing window, or null.

wlist is a list of specifications; the first must be the Sizer and
the last may be null.  Each specification is itself a list consisting
of a specification string, a callback routine, and an optional list
of additional specifications.  Specification strings vary by vidget
type, but the general form is "ID:type:style:n:x,y,w,h:label".

dsetup() returns a table of values from the dialog, indexed by ID.

[ Summary entry | Source code ]


enqueue.icn: Procedures for queued events

procedure pack_intrvl:     encode event interval
procedure unpack_intrvl:   decode event interval
procedure pack_modkeys:    encode modifier keys
procedure unpack_modkeys:  decode modifier keys
procedure Enqueue:         enqueue event

link enqueue
May 2, 2001; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures manipulate Icon window events.

Enqueue(W, eventcode, x, y, modkeys, interval) posts an event.

pack_modkeys(s)         encodes the modifier keys for an event.
unpack_modkeys(n)       decodes a modifier key value.

pack_intrvl(n)          encodes an event interval.
unpack_intrvl(n)        decodes an event interval.
____________________________________________________________

   Icon's event queue is a list accessed via Pending(); the list
can be inspected or altered by the Icon program.  An event is stored
as three consecutive entries on the list.  The first is the event code:
a string for a keypress, or an integer for any other event.  The next
two list entries are integers, interpreted as a packed structure:
    0000 0000 0000 0SMC  XXXX XXXX XXXX XXXX   (second entry)
    0EEE MMMM MMMM MMMM  YYYY YYYY YYYY YYYY   (third entry)

The fields have these meanings:
    X...X   &x: 16-bit signed x-coordinate value
    Y...Y   &y: 16-bit signed y-coordinate value
    SMC     &shift, &meta, and &control (modifier keys)
    E...M   &interval, interpreted as  M * 16 ^ E
    0       currently unused; should be zero


   pack_modkeys(s) encodes a set of modifier keys, returning an
integer with the corresponding bits set.  The string s contains
any combination of the letters c, m, and s to specify the bits
desired.

   pack_intrvl(n) encodes an interval of n milliseconds and returns
a left-shifted integer suitable for combining with a y-coordinate.

   unpack_modkeys(n) returns a string containing 0 to 3 of the
letters c, m, and s, depending on which modifier key bits are
set in the argument n.

   unpack_intrvl(n) discards the rightmost 16 bits of the integer
n (the y-coordinate) and decodes the remainder to return an
integer millisecond count.

   Enqueue([window,] eventcode, x, y, modkeys, interval) synthesizes
and enqueues an event for a window, packing the interval and modifier
keys (specified as above) into the correct places.  Default values
are:
    eventcode = &null
    x = 0
    y = 0
    interval = 0
    modkeys = ""

[ Summary entry | Source code ]


event.icn: Procedure to produces events from a window event history

link event
April 30, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

Event(win) overloads the built-in function Event() and produces
events using evplay().

[ Summary entry | Source code ]


evmux.icn: Procedures for window event multiplexor

link evmux
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
See also: button.icn, slider.icn
This file is in the public domain.

These procedures implement a simple event handling package.  This
package has more recently been superseded by the vidget library.

The event multiplexor is configured by registering *sensors*, which
respond to events that occur when the mouse cursor is within a
particular region.  When a sensor fires, it calls a user procedure
that was registered when the sensor was created.

These routines interpret window events and invoke callbacks:

        sensor()        registers the events of interest.

        evhandle()      reads and responds to the next event.

        evmux()         loops forever, handling events.

Two other small procedures help build event-driven programs:

        quitsensor()    registers a standardized response to Q or q.

        argless()       is a "glue" procedure usable as a callback.
____________________________________________________________

sensor(win, ev, proc, arg, x, y, w, h) -- register an event responder.

    registers *proc* as the procedure to be called when the event[s]
    *ev* occur within the given bounds inside window *win* and returns
    a handle.  The default bounds encompass the entire window.

    The event set *ev* can be either:
        -- a cset or string specifying particular keypresses of interest
        -- one of the event keywords (&lpress, &rdrag, &resize, etc.)

    When a matching event occurs, proc(win, arg, x, y, e) is called.  proc,
    win, and arg are as recorded from the sensor call.  x and y give the
    current mouse position and e the event; for a keypress, this is the
    character.

    No event generates more than one procedure call.
    In the case of conflicting entries, the later registrant wins.

    delsensor(win, x) deletes sensor x from the specified window.
    If x is null, all sensors are deleted.


evmux(win) -- loop forever, calling event handlers as appropriate.
evhandle(win) -- wait for the next event, and handle it.

    evmux(win) is an infinite loop that calls user routines in response
    to window events.  It is for programs that don't need to do other
    work while waiting for window input.

    evhandle(win) processes one event and then returns to its caller,
    allowing external loop control.  evhandle returns the outcome of
    the handler proc, or fails if there is no handler for the event.

quitsensor(win, wait) -- standardized "quit" sensor

    quitsensor() registers a sensor that calls exit() when either
    "q" or "Q" is typed in the window.

    If wait is non-null, quitsensor does not return but just waits for
    the signal (useful in non-interactive display programs).


argless(win, proc) -- call proc with no arguments.

    Useful for registering argless procedures as in quitsensor() above.

[ Summary entry | Source code ]


evplay.icn: Procedure to "play back" recorded window events

link evplay
July 15, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

evplay(win) reads a window event history file (such as produced by
evrecord()), and puts an event on the event queue for the given window.
If the global identifier EventFile is nonnull, it is used as the
event history; otherwise standard input is used.

[ Summary entry | Source code ]


evrecord.icn: Procedure to record window events

link evrecord
April 25, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure writes a file of graphics events.  The file can be
converted to "pseudo events" by evplay.icn.

When used with a vidget interface, evrecord can be passed as an
argument to, say, GetEvents(), as in

     GetEvents(root, , evrecord)

[ Summary entry | Source code ]


fetchpat.icn: Procedure to fetch a pattern specification

link fetchpat
October 21, 1993; Ralph E. Griswold
This file is in the public domain.

This procedure fetches a pattern by number from a file of pattern
specifications.  It fails if the file does not exist or does not
contain that many pattern specifications.

The file is searched for in the current directory first, then using
DPATH.

[ Summary entry | Source code ]


fstars.icn: Procedure to produce traces of fractal stars

procedure fstar:           fractal stars

link fstars
May 23, 1996; Ralph E. Griswold
This file is in the public domain.

This procedure produces traces of fractal "stars".  For a discussion of
fractal stars, see

     Fractals; Endlessly Repeated Geometrical Figures, Hans Lauwerier,
     Princeton University Press, 1991, pp. 72-77.

and

     Geometric and Artistic Graphics; Design Generation with
     Microcomputers, Jean-Paul Delahaye, Macmillan, 1987, pp. 55-63.

The arguments are:

     x, y, n, p, r, incr, extent

     x       x coordinate of the initial point, default 0
     y       y coordinate of the initial point, default 0.5
     n       number of vertices, default 5
     p       number of phases, default 5
     r       reduction factor, default 0.35
     incr    angular increment factor, default 0.8
     extent  extent of drawing, 1.0

Chosing values for these arguments that produce interesting results and
centering the star in the window is somewhat of an art.  See fstartbl.icn
for some good values.

[ Summary entry | Source code ]


fstartbl.icn: Procedure to produce calls for fractal stars

link fstartbl
April 8, 1993; Ralph E. Griswold
See also: fstars.icn
This file is in the public domain.

This procedure produces a table of calls from which fractal stars
can be produced.

[ Summary entry | Source code ]


gdisable.icn: Procedure to disable graphics functions

link gdisable
August 14, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure effectively disables the graphics functions.  Care should
be taken in the way the disabled functions are used, since in their
disabled forms, they return their first argument (if any).

[ Summary entry | Source code ]


getcolrs.icn: Procedures for getting color palette

link getcolrs
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures support the interactive selection of colors.

[ Summary entry | Source code ]


gifsize.icn: Procedure to return size of GIF file

procedure gifsize:         size of GIF file

link gifsize
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

This procedure returns the size of a GIF file in the form
width,height.  It fails if the file does not exist or is
not a valid GIF file.

[ Summary entry | Source code ]


glabels.icn: Procedure to produce graph ticks

link glabels
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

glabels(min, max, nticks) produces a list of aesthetically pleasing labels
for graph ticks to cover a given range.  It is based on the algorithm
given by Paul S. Heckert in "Graphic Gems", Andrew S Glassner, ed.,
Academic Press, 1990.

[ Summary entry | Source code ]


glib.icn: Procedures for graphics

link glib
May 2, 2001; Stephen B. Wampler
Requires: Version 9 graphics, co-expressions
This file is in the public domain.

Comments: This package is the collection of routines
   developed to facilitate traditional 2D graphics.
   It is incomplete, but still provides
   a reasonable amount of support.  There is some
   support for 3D graphics here, but that is not so
   well developed.  People are encouraged to improve
   these routines and add new routines.

   All routines use list-based subscripting.  This allows
   programs to describe points as lists OR records.

   In the turtle graphics code, the use gives angles in
   degrees.

[ Summary entry | Source code ]


gpxlib.icn: Procedures for graphics tasks

procedure Distance:        distance between two points
procedure InBounds:        check point within rectangle
procedure ScratchCanvas:   return scratch canvas

link gpxlib
August 21, 1998; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

This file contains a few eclectic graphics procedures.

ScratchCanvas(w, h, id)   creates a temporary, hidden window.

PushWin(L)                adds a default window to an argument list.

Distance(x1, y1, x2, y2)  computes the distance between two points.

InBounds(x, y, w, h)      succeeds if (&x,&y) is within (x,y,w,h).
____________________________________________________________

The following procedure allows an additional first argument
specifying a window to use instead of &window:

ScratchCanvas(w, h, id) returns a hidden-canvas window for temporary
use.  The same scratch window (per display) is returned by successive
calls with the same ID, avoiding the cost of creation.  The size is
guaranteed to be at least (w, h), which default to the size of the
window.  The scratch window must not be closed by the caller, but an
EraseArea can be done to reclaim any allocated colors.
____________________________________________________________

The following procedures do not accept a window argument:

PushWin(L) pushes &window onto the front of list L if the first
element of the list is not a window.  This aids in constructing
variable-argument procedures with an optional window argument.

Distance(x1, y1, x2, y2) returns the distance between two points
as a real number.

InBounds(x, y, w, h) checks whether &x and &y are within the given
region:  it returns &null if x <= &x <= x+w and y <= &y <= y+h,
and fails otherwise.

[ Summary entry | Source code ]


gpxop.icn: Procedures for graphics operations

procedure LeftString:      draw left-justified string
procedure CenterString:    draw centered string
procedure RightString:     draw right-justified string
procedure ClearOutline:    draw and clear rectangle
procedure Translate:       add translation
procedure Sweep:           sweep area with mouse
procedure Zoom:            zoom image
procedure Capture:         capture image as string

link gpxop
May 26, 1999; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

This file contains some graphics procedures.

LeftString(x, y, s)       draws a string left-aligned at (x, y).

CenterString(x, y, s)     draws a string centered at (x, y).

RightString(x, y, s)      draws a string right-aligned at (x, y).

ClearOutline(x, y, w, h)  draws a rectangle, erasing its interior.

Translate(dx, dy, w, h)   moves the window origin and optionally
                          sets the clipping region.

Zoom(x1, y1, w1, h1, x2, y2, w2, h2)
                          copies and distorts a rectangle.

Capture(p, x, y, w, h)    converts a window area to an image string.

Sweep()                   lets the user select a rectangular area.
____________________________________________________________

LeftString(x, y, s), CenterString(x, y, s), and RightString(x, y, s)
draw a string centered vertically about y and left-justified,
centered, or right-justified about x.

ClearOutline(x, y, w, h) draws a rectangle in the foreground color
and fills it with the background color.

Translate(dx, dy, w, h) adjusts a window's dx and dy attributes by
the values given.  Note that the resulting attribute values are the
sums of the existing values with the parameters, so that successive
translations accumulate.  If w and h are supplied, the clipping
region is set to a rectangle of size (w, h) at the new origin.

Zoom(x1, y1, w1, h1, x2, y2, w2, h2) is a distorting variation of
CopyArea that can be used to shrink or enlarge a rectangular area.
Zero, one, or two window arguments can be supplied.  Rectangle 1 is
copied to fill rectangle 2 using simple pixel sampling and replication.
The rectangles can overlap.  The usual defaults apply for both rectangles.

Sweep() lets the user select a rectangular area using the mouse.
Called when a mouse button is pressed, Sweep handles all subsequent
events until a mouse button is released.  As the mouse moves, a
reverse-mode outline rectangle indicates the selected area.  The
pixels underneath the rectangle outline are considered part of this
rectangle, implying a minimum width/height of 1, and the rectangle
is clipped to the window  boundary.  Sweep returns a list of four
integers [x,y,w,h] giving the rectangle bounds in canonical form
(w and h always positive).  Note that w and h give the width as
measured in FillRectangle terms (number of pixels included) rather
than DrawRectangle terms (coordinate difference).

Capture(palette, x, y, w, h) converts a window region into an
image string using the specified palette, and returns the string.

These procedures all accept an optional initial window argument.

[ Summary entry | Source code ]


graphics.icn: Procedures for graphics

link graphics
August 4, 2000; Gregg M. Townsend
This file is in the public domain.

Links to core subset of graphics procedures.

[ Summary entry | Source code ]


grecords.icn: Declarations for graphics

link grecords
July 27, 1996; Ralph E. Griswold
This file is in the public domain.

These declarations are used in procedures that manipulate objects
in two- and three-dimensional space.

[ Summary entry | Source code ]


gtrace.icn: Procedures to process graphic traces

link gtrace
November 19, 1997; Ralph E. Griswold
See also: gtraces.doc
This file is in the public domain.

As used here, the term "trace" refers to a sequence of points that
generally consists of locations on a curve or other geometrical object.
These procedures process such traces in various ways.

[ Summary entry | Source code ]


ifg.icn: Procedure to tell if graphics are running

link ifg
June 14 1994; Ralph E. Griswold
This file is in the public domain.

ifg() fails if (a) the running version of Icon does not support
graphics, or (b) if it is, the graphics system is not running.

[ Summary entry | Source code ]


imagedim.icn: Procedures for getting image dimensions

link imagedim
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

imagedim(s) returns a record that contains the type and dimensions of an
image named s.

The assumptions about image formats are naive.

[ Summary entry | Source code ]


imageseq.icn: Procedure to write sequences of images

link imageseq
December 26, 1994; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures provide help for applications that write sequences
of images.

seq_init(opts) initializes the naming parameters from the table opts.
opts["n"] is the name, opts["f"] is the first number, and opts["c"]
is the number of columns for the serial number.

save_image(win, x, y, w, h) write the specified area of win using the
next name in sequence.  There is no check for duplicate names if the
numbering wraps around.

[ Summary entry | Source code ]


imgcolor.icn: Procedure to produce table of colors in area

link imgcolor
January 5, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure produces a table of all the colors in a specified
area of a window.  The value corresponding to a color key is
the number of pixels with that color

[ Summary entry | Source code ]


imrutils.icn: Procedures to deal with image records

procedure imrcath:         horizontally concatenate image records
procedure imrcatv:         vertically concatenate image records
procedure imrdraw:         draw image record
procedure imrflipd:        flip image record diagonally
procedure imrfliph:        flip image record horizontally
procedure imrflipv:        flip image record vertically
procedure imrnegative:     form negative of image record
procedure imropen:         open window with image record
procedure imrpshift:       map shifted palette
procedure imrrot180:       rotate image record 180 degrees
procedure imrrot90cw:      rotate image record 90 deg. clockwise
procedure imrshifth:       shift image record horizontally
procedure imrshiftv:       shift image record vertically
procedure imrtoims:        convert image record to image string
procedure imstoimr:        convert image string to image record
procedure imror:           form inclusive "or" of two images

link imrutils
January 23, 2002; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

Procedures to manipulate image strings as records.

     imrcath(imr1, imr2)
                     concatenates imr1 and imr2 horizontally

     imrcatv(imr1, imr2)
                     concatenates imr1 and imr2 vertically

     imrcopy(imr)    create copy of imr

     imrdraw(win, x, y, imr)
                     draws an image record

     imrfliph(imr)   flips an image record horizontally

     imrflipv(imr)   flips an image record vertically

     imrnegative(imr)
                     produces "negative" of image; intended for
                     grayscale palettes

     imropen(imr)    opens a hidden window with an image record

     imror(imr)      forms inclusive "or" of two images

     imrpshift(imr, ir)
                     shifts colors by mapping rotated palette

     imrrot180(imr)
                     rotates an image record 180 degrees

     imrrot90cw(imr)
                     rotates an image record 90 degrees clockwise

     imrshifth(imr, i)
                     shifts an image record horizontally by i pixels
                     with wrap-around; positive i to the right,
                     negative to the left.

     imrshiftv(imr, i)
                     shifts an image record vertically by i pixels
                     with wrap-around; positive i to the top,
                     negative to the bottom.

     imstoimr(s)     converts an image string to an image record

     imrtoims(imr)   converts an image record to an image string

Note:  All the procedures that produce image records modify their
argument records; they do not return modified copies.
____________________________________________________________

Possible additions:

     Make stripes from one (or more) rows/columns.

     Convert from one palette to another.

[ Summary entry | Source code ]


imscanon.icn: Procedure to put bi-level image string in canonical form

link imscanon
August 6, 1994; Ralph E. Griswold
Requires: Large integers
This file is in the public domain.

This procedure puts a bi-level image string in canonical form so
that duplicates up to shifting can be eliminated.  It is intended to
be used in imlreduc.icn, which handles the rotational case.

It presently only handles widths that are a multiple of four.

[ Summary entry | Source code ]


imscolor.icn: Procedures for manipulating images

procedure imspalette:      palette for image
procedure imswidth:        width of image
procedure imsheight:       height of image
procedure imsmap:          map data of image string
procedure imswrite:        write image string
procedure drawpalette:     draw palette
procedure pickpalette:     key from drawn palette
procedure XPMImage:        image string for XPM file

link imscolor
December 25, 1999; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures manipulate image strings.

imswidth(im)            returns the width of an image.
imsheight(im)           returns the height of an image.
imspalette(im)          returns the palette used by an image.

imsmap(s1, s2, s3)      applies map() to the image data.

imswrite(f, s, n)       writes an image string to a file.

drawpalette(W, p, x, y, w, h, f, n)     draws the color palette p.

pickpalette(W, p, dx, dy, w, h, n)      maps window coordinates
                        to a palette drawn by drawpalette().

XPMImage(W, f, p)       reads an XPM file, returning an image string.
____________________________________________________________

imswidth(im) returns the width of an image.
imsheight(im) returns the height of an image.
imspalette(im) returns the palette used by an image.

imsmap(s1, s2, s3) returns an image produced by mapping the data (only)
of image s1 and replacing characters found in s2 with corresponding
characters from s3.

imswrite(f, s, n) writes image string s to file f, limiting the line
length to n characters.  Defaults are f = &output, n = 79.  Extra
punctuation in s makes the lines break at nonsensical places, but
the output is still legal.

drawpalette([win,] p, x, y, w, h, f, n) draws the colors of palette
p in the given rectangular region.  n columns are used;  if n is
omitted, a layout is chosen based on the palette name and size. The
layout algorithm works best when the height is two to four times
the width.  Characters in the flag string f have these meanings:
     l       label each color with its key
     o       outline each color in black
     u       unframed use: don't hash unused cells at end

pickpalette([win,] p, dx, dy, w, h, n) returns the character at (dx,dy)
within a region drawn by drawpalette(win, p, x, y, w, h, f, n).

XPMImage([win,] f, palette) reads an XPM (X Pixmap) format image from
the open file f and returns an Icon image specification that uses the
specified palette.  XPMImage() fails if it cannot decode the file.
If f is omitted, &input is used; if palette is omitted, "c1" is used.
Not all variants of XPM format are handled; in particular, images that
use more than one significant input character per pixel, or that use
the old XPM Version 1 format, cause XPMImage() to fail.  No window
is required, but X-specific color names like "papayawhip" will not
be recognized without a window.

[ Summary entry | Source code ]


imsutils.icn: Procedures to manipulate image specifications

link imsutils
May 2, 2001; Ralph E. Griswold
Requires: Version 8.11 graphics
This file is in the public domain.

This file contains procedures that manipulate string representations for
images.

     patident(imx1, imx2)
     XDrawTile(win, xoff, yoff, pattern, magnif, mode)
     XDrawRows(win, xoff, yoff, imx, magnif, mode)
     bits2hex(s)
     decspec(pattern)
     getpatt(line)
     getpattnote(line)
     hex2bits(s)
     hexspec(pattern)
     legalpat(tile)
     legaltile(tile)
     pat2xbm(pattern, name)
     tilebits(imx)
     pdensity(pattern)
     pix2pat(window, x, y, cols, rows)
     readims(input)
     readimsline(input)
     rowbits(pattern)
     imstoimx(ims)
     imxtoims(imx)
     showbits(pattern)
     tiledim(pattern)
     pheight(pattern)
     pwidth(pattern)
     xbm2rows(input)

[ Summary entry | Source code ]


imxform.icn: Procedures to transform image matrices

link imxform
June 10, 2001; Ralph E. Griswold
Requires: Version 8.11, graphics
This file is in the public domain.

This file contains procedures that manipulate matrices that represent
images.

[ Summary entry | Source code ]


interact.icn: Procedures to support interactive applications

procedure edit_file:       editor launch
procedure edit_list:       edit lines dialog
procedure error_notice:    error alert
procedure execute:         command-line launch
procedure list_win:        window for list of strings
procedure expose:          expose window
procedure load_file:       load dialog
procedure open_image:      open image
procedure ExitNotice:      notice dialog that fails
procedure FailNotice:      notice dialog that fails
procedure save_as:         save-as dialog
procedure save_file:       save dialog
procedure save_list:       save list dialog
procedure select_dialog:   select dialog for many items
procedure snapshot:        snapshot dialog
procedure unsupported:     unsupported feature alert

link interact
August 7, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

edit_file(s)    launches an editor, default vi, for the file named
                s.

edit_list(L)    provides edit dialog for the strings in the list L.

error_notice(i, x, s)
                produces a notice dialog noting a run-time
                error.  It can be used to handle procedure
                errors by runerr := error_notice.

execute()       provides a dialog for specifying a command.

expose(win)     attempt to make win the active window for the
                window manager.

load_file(s, n) presents a standard open dialog with the caption s.
                and suggest name n.

                If the user specifies a file that can be opened,
                dialog_value is set to it.  Otherwise, the dialog
                is presented again.  The name of the selected
                button is returned.

open_image(s)   presents a standard open dialog with the caption s.
                If the user specifies a file that can be opened as
                an image in a window, the window is opened.  Otherwise
                the dialog is presented again.

ExitNotice(s[]) Notice() that exits.

FailNotice(s[]) Notice() that fails.

save_as(s, n)   presents a standard save dialog with the caption s
                and suggested name n.  If the user specifies a file
                that can be written, the file is assigned to
                dialog_value.  Otherwise the dialog is presented
                again.  save_as() fails if the user cancels.

save_file(s, n) presents a standard save dialog with the caption s
                and suggested name n.  If the user specifies a file
                that can be written, the file is returned.
                Otherwise, save_as() is called.  The name of
                the selected button is returned.

save_list(s, L) provides dialog for saving list items in a file.

select_dialog(s, L, d)
                provides a dialog for selecting from a list of
                items.  d is the default selection.

snapshot(win, x, y, w, h, n)
                writes an image file for the specified portion of
                the window.  The name for the file is requested from
                the user via a dialog box.  If there already is a
                file by the specified name, the user is given the
                option of overwriting it or selecting another name.
                The procedure fails if the user cancels.  n sets
                the width of the text-entry field.

unsupported()   provides Notice() for unsupported feature.

[ Summary entry | Source code ]


isdplot.icn: Procedures to create grid plots for ISDs

link isdplot
May 26, 2001; Ralph E. Griswold
Requires: Version 9 graphics and large integers
This file is in the public domain.

NOTE:  The drawdown code is patched in from code in pfd2ill.icn and
uses a different method than the others.  One way or another, the
methods should be made consonant.

[ Summary entry | Source code ]


isdxplot.icn: Procedures to create grid plots for ISDs

link isdxplot
March 4, 2003; Ralph E. Griswold
Requires: Version 9 graphics and large integers

NOTE:  The drawdown code is patched in from code in pfd2ill.icn and
uses a different method than the others.  One way or another, the
methods should be made consonant.

This version is for ISDs without explicit thread-color information.

[ Summary entry | Source code ]


joinpair.icn: Procedure to connect pairs of points

link joinpair
February 12, 1993; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

joinpair(points1, points2) draws lines between all pairs of points
in the lists of points.

[ Summary entry | Source code ]


jolygs.icn: Procedure to produce traces of "jolygons"

link jolygs
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

This procedure produces traces of jolygons.  See

     Geometric and Artistic Graphics; Design Generation with
     Microcomputers, Jean-Paul Delahaye, Macmillan, 1987, pp. 20-24.

The arguments specify the starting positions, the extent of the
drawing, the number of segments, the angle between consecutive
segments, the ratio of the lengths of consecutive segments,
a length factor, and a y scaling factor.

[ Summary entry | Source code ]


linddefs.icn: Procedure to produce table of L-systems

link linddefs
November 22, 1997; Ralph E. Griswold
This file is in the public domain.

This procedure produces a table of L-systems.

[ Summary entry | Source code ]


linddraw.icn: Procedure to draw L-System strings

procedure linddraw:        draw L-system

link linddraw
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

This procedure draws strings of characters produced by
L-systems.

[ Summary entry | Source code ]


lindrec.icn: Declarations for L-systems

link lindrec
August 18, 1994; Ralph E. Griswold
This file is in the public domain.

These declarations are provided for representing Lindenmayer systems
as records.

[ Summary entry | Source code ]


lindterp.icn: Procedure to interpret and draw L-System strings

link lindterp
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

This procedure interpreters strings of characters produced by
L-Systems and draws them using turtle graphics.

[ Summary entry | Source code ]


lsystem.icn: Procedures for Lindenmayer systems support

link lsystem
May 2, 2001; Stephen B. Wampler
Requires: Version 9 graphics, co-expressions (for glib.icn)
This file is in the public domain.

Comments: This package is the collection of routines
   developed to facilitate experiments with L-systems,
   including the interpretation of strings as turtle
   graphics commands.

   Only rudimentary L-systems are currently implemented.
    users are encouraged to extend this system.

[ Summary entry | Source code ]


mapnav.icn: Procedures for navigating a map interactively

procedure mapinit:         initialize navigator
procedure mapgen:          invoke callback to redraw the map
procedure mapproj:         compute map projection
procedure mapevent:        navigate map as directed by action e

link mapnav
May 7, 2002; Gregg M. Townsend
This file is in the public domain.

These procedures implement a user interface for browsing a map
that is drawn using a simple rectangular projection.  The
following interface actions are provided, if not overridden
by the calling program:
   The arrow keys pan the display.
   Shifted arrows pan by a smaller amount.
   The + and - keys zoom in and out.
   The 0, 1, or HOME key resets the original display.
   The q key causes an immediate exit.
   Sweeping a region with the mouse zooms the display.
   Resizing the window causes it to be redrawn.

The calling program provides the main loop and a drawing
procedure; this module handles the interface and computes
the output transformation.

mapinit(win, proc, arg, xleft, xright, ytop, ybottom, m) initializes.
mapgen(win, proc, arg) generates the map by invoking the callback.
mapevent(win, e) handles a window event, possibly invoking a callback.
mapproj(win) returns the projection used in the window.

The win argument is optional in all procedures but can be used
to supply the correct graphics context.  The window argument is
always supplied to the callback procedure.
____________________________________________________________

Typical use is like this:

procedure main(...)
   ... initialize ...
   ... load data ...
   ... open window ...
   mapinit(draw, ...)
   mapgen()
   case e := Event() of {
      ... handle custom events ...
      default: mapevent(e)
      }
end

procedure draw(win, p, arg)
   ... create list of coordinates ...
   ... L2 := project(p, L1) ...
   ... draw map ...
end
____________________________________________________________

mapinit(win, proc, arg, xleft, xright, ytop, ybottom, m) configures
the navigator.  proc is a drawing procedure to be called whenever
the window needs to be redrawn.  arg is an arbitrary value to be
passed to proc along with the transformation parameters.

xleft, xright, ytop, and ybottom specify the range of coordinates
for the data that is to be displayed.  For both the x and y pairs,
the values must differ but either can be the greater.

The value of m (default 1.0) specifies the aspect ratio of the
input units.  If the input data is in units of latitude and
longitude, choose a central latitude for projection and pass
the cosine of that latitude as m.
____________________________________________________________

mapgen(win, proc, arg) calls the drawing procedure proc to draw a
map.  win is optional, and proc and arg default to the values
registered by the last mapinit() call.

The drawing procedure is called as
   proc(win, pj, arg)
where pj the projection returned by mapproj(win).

The drawing procedure should project and display its data.
It must ensure that the resulting coordinates lie inside
the range -32768 <= v <=32767 before passing them to Icon
drawing functions.  (See also clipping.icn.)
____________________________________________________________

mapevent(win, e) handles a window event.  If e is recognized as
an interface action, the map parameters are altered and mapgen()
is called, resulting in a call to the drawing procedure.  For
a panning action, the window contents are first shifted;
otherwise, the window is first erased.  mapevent() fails if
e is not recognized.

The calling program can intercept and override any action it does
not want handled by the navigator.  This can be used to customize
the interface -- for example, to use "0" for something other than
"reset zooming".  However, any &resize event, even if handled by
the caller, should be passed to the navigator to allow it to
properly adjust its view of the world.
____________________________________________________________

mapproj(win) returns a rectangular projection (see cartog.icn)
that maximizes the display of the currently selected data range
for viewing in the center of window win.  The "selected data range"
is that passed to mapinit() and subsequently modified by any
zooming or panning actions.

[ Summary entry | Source code ]


mirror.icn: Procedure to mirror tile

link mirror
November 15, 1997; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

mirror(win)  mirrors win using p2mm symmetry and returns the result as a
             hidden window.

[ Summary entry | Source code ]


modlines.icn: Procedure to produce trace of modular lines

link modlines
August 3, 2000; Ralph E. Griswold
This file is in the public domain.

For a description of the method used here, see

     Geometric and Artistic Graphics; Design Generation with
     Microcomputers, Jean-Paul Delahaye, Macmillan, 1987, pp. 90-95.

[ Summary entry | Source code ]


navitrix.icn: Procedures to perform file navigation

link navitrix
July 10, 2002; Ralph E. Griswold
Requires: Version 9 graphics, UNIX
This file is in the public domain.

This package provides an interface for file navigation.  It is
intended for use with another application with a visual interface.
____________________________________________________________

The code is based on Unix but may work in other Unix-like environments.

Directories are shown with a trailing slash.  Clicking on a directory
moves there.  Clicking on a file name selects it.  The text of the
button used to dismiss the navigator is put in the global variable
nav_state, while the name of the selected file is put in the global
variable nav_file.

nav_keyboard() processes keyboard shortcuts.  A return character is
equivalent to clicking on the Okay button.  Other characters cause
the top list entry to be positioned at a name that starts with or is
close to the character.

The other application needs only to know this:

     The navigator is initialized by calling nav_init().  This opens a
     hidden window, assigned to the global variable nav_window, for
     the navigator.  It also assigns the navigator root vidget to the
     global variable nav_root.

     To use the navigator, the other application needs to change the
     canvas status nav_window to normal so it can accept user events
     and hide it again when it has been "dismissed".  The navigator
     puts the selected file in nav_file as mentioned above.

     If the application wants to support the navigator's keyboard
     shortcuts, it needs to set the shortcut procedure to nav_keyboard
     when the navigator window is active.

A typical event loop for using the navigator is:

repeat {                     # event loop
   case Active() of {
      &window   :  {         # application window
         root_cur := root
         shortcuts_cur := shortcuts
         }
      nav_window   :  {      # navigation window
         root_cur := nav_root
         shortcuts_cur := nav_keyboard
         }
      }
   ProcessEvent(root_cur, , shortcuts_cur)
   case nav_state of {
      &null   :  next
      "Okay"  :  load_pattern()
      }
   nav_state := &null
   WAttrib(nav_window, "canvas=hidden")
   }

where process_file() is a procedure that does something with the
file.

Note that the value of nav_state determines what needs to be done.  It is
null when the navigator has not been used since the last event.  If
the navigator is dismissed with "Cancel" instead of "Okay", nothing
needs to be done except hide the navigator window and set the nav_state
to null.

Coupled with this is a procedure (or more than one) that makes the
navigator window visible, as in

     procedure open_cb()
        WAttrib(nav_window, "canvas=normal")
        ...
        return
     end

If there is more than one use of the navigator, the callbacks that
enable it can set process_file to the appropriate companion procedure.

[ Summary entry | Source code ]


optwindw.icn: Procedures to open window with standard options

procedure optwindow:       open window with options

link optwindw
October 10, 1997; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

optwindow() opens a window, interpreting command options to
set various window attributes.
____________________________________________________________

optwindow(opttable, attribute...) -- open window based on option table

optwindow returns a new X-window configured according to a table of
options such as that returned by options().  If a window cannot be
opened, the program is aborted.

If any attribute arguments are supplied they are passed to the open call
ahead of anything generated from the option table.

In general, upper-case letters are used for generic window options, and
any letters not listed below are reserved for future use.  This leaves
the lower-case letters for program-specific options.

The following options are recognized:

     -B color        background color        default: "pale gray"
     -F color        foreground color        default: "black"
     -L label        window label (title)    default: &progname (trimmed)
     -T font         text font               default: unspecified

     -D display      window device           default: unspecified
     -X xpos         x position              default: unspecified
     -Y ypos         y position              default: unspecified
     -W width        window width            default: 500
     -H height       window height           default: 300
     -M margin       frame margin            default: 0

     -S width,height window size             default: 500,300 + margins
     -P xpos,ypos    window position         default: unspecified
     -G [wxh][+x+y]  geometry, in usual X terms (but NOTE: no negative x | y)

     -!              echo the window creation call on stderr (for debugging)

-G is translated into -X -Y -W -H and overrides those values.
-P and -S override values from -G, -X, -Y, -W, and -H.

Table values for {B,F,L,X,Y,W,H,M,P,S} are guaranteed to be set upon return.

The "margin" is the internal border between the actual window frame and the
area used for display; you don't usually want to write right up to the edge.
If a negative value is given for -M, a standard margin of 10 pixels is set.
-M is added twice (for two margins) to -W and -H when calculating the actual
window size so that -W and -H reflect the actual usable area.  If -W and -H
are derived from -G, which specifies actual window sizes, -M is twice
subtracted so that -W and -H always reflect the usable dimensions.

winoptions() can be used to combine the above options with other options
for the options() call.

Example:

     # get option table; allow standard options plus "-f filename"
     opts := options(args, winoptions() || "f:")

     # set defaults if not given explicitly
     /opts["W"] := 400                       # usable width
     /opts["H"] := 400                       # usable height

     # open the window
     win := optwindow(opts, "cursor=off")

     # save actual values given by the window manager
     h := opts["H"]                          # usable height
     w := opts["W"]                          # usable width
     m := opts["M"]                          # specified margin

(The usable area, then, is from (m,m) to (m+w, m+h).

[ Summary entry | Source code ]


orbits.icn: Procedures to produce traces of orbits

link orbits
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

These procedures produce traces of orbits.  See

     Geometric and Artistic Graphics; Design Generation with
     Microcomputers, Jean-Paul Delahaye, Macmillan, 1987, pp. 65-73.

The arguments specify the starting positions, the extent of the
drawing, the number of segments, and various parameters that
control the orbit.

[ Summary entry | Source code ]


overlay.icn: Procedure to overlay an image in a window

link overlay
May 26, 1994; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

overlay(window, image) writes the image in the window, a line at a time.

[ Summary entry | Source code ]


palettes.icn: Procedures for programmer-defined palettes

procedure BuiltinPalette:  check for built-in palette
procedure CreatePalette:   create palette
procedure DrawImage:       draw image
procedure InitializePalett initialize palettes
procedure Measure:         measure of RGB distance
procedure NearColor:       close color in palette
procedure PaletteChars:    characters in palette
procedure PaletteColor:    color for key in palette
procedure PaletteKey:      key for color in palette
procedure RGB:             convert RGB color to record
procedure makepalette:     make palette automatically
procedure palette_colors:  list of palette colors
procedure keyseq:          sequence of palette keys
procedure color_range:     adjust RGB range
procedure colorseq:        sequence of palette colors
procedure value:           RGB magnitude

link palettes
January 23, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures implement programmer-defined palettes.  They overload
and build on top of the built-in palette mechanism.
____________________________________________________________

Data structures:

     Palette_() is a record that holds the information for a
     programmer-defined palette.  Its fields are:

             name:    the name the palette is known by
             keys:  the string of the palette characters
             table:   a table keyed by the palette characters
                      whose corresponding values are the colors

     Color_() is a record that holds the components of an RGB
     color in separate r, g, and b fields.

     PDB_ is a table whose keys are the names of programmer-
     defined palettes and whose corresponding values are the
     palettes.  PDB_ is a global variable and provides the
     way for programmer-defined palette procedures to access
     a particular database.  If it is null, a new database is
     created.

Procedures:

     BuiltinPalette(name)
             succeeds if name is the name of a built-in palette but
             fails otherwise.

     CreatePalette(name, keys, colors)
             creates a new palette with the given colors and
             corresponding keys.  The colors used are the given ones.

     InitializePalettes()
             initializes the built-in palette mechanism; it is called
             by the first palette procedure that is called.

     Measure(color1, color2) returns the a measure of the distance
              between color1 and color2 in RGB space.

     NearColor(name, color)
             returns a color close to color in the palette name.

     PaletteChars(win, palette)
             returns the palette characters of palette.  It extends
             the standard version.

     PaletteColor(win, palette, key)
             returns color in palette for the given key. It extends
             the standard version.

     PaletteKey(win, palette, color)
             returns the key in palette closest to the given color.

     RGB(color)
             parses RGB color and returns a corresponding record.

     makepalette(name, clist)
             makes a palette from the list of colors, choosing
             keys automatically.

     palette_colors(palette)

             returns the list of colors in palette.

Procedures fail in case of errors. This leaves control and error
reporting to programs that use this module.  This module is intended
to be used by programs that manage the necessary data and supply
the table through PDB_.  The problem with this is that there is
no way to differentiate errors.  A solution would be to post error
messages in a global variable.

Limitations and problems:

     The names of built-in palettes may not be used for programmer-
     defined ones.

     PaletteGrays() is not implemented for programmer-defined
     palettes.  The library version should work for built-in
     palettes with this module linked.

     Transparency is not yet implemented for DrawImage().

     ReadImage() does not yet support programmer defined palettes.

     Not tested:  Capture(), which may work.

     There is some library code that checks for the names of
     built-in palettes in an ad-hoc fashion.  It therefore is
     not advisable to use names for programmer-defined palettes
     that begin with "c" or "g" followed by a digit.

[ Summary entry | Source code ]


pattread.icn: Procedure to read pattern

link pattread
December 10, 2001; Ralph E. Griswold
This file is in the public domain.

Reads BLP or row file and produces pattern in row form.

[ Summary entry | Source code ]


patutils.icn: Procedures to manipulate patterns

procedure eqpats:          test row patterns for equality

link patutils
July 8, 2002; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This file contains procedures that manipulate graphic pattern
representations.  These procedures are intended for bi-level patterns
representable by 0s and 1s.

A row pattern is a list of strings, with each string representing
a row in the pattern.

     DrawTile(win, xoff, yoff, pattern, magnif, mode)
     DrawRows(win, xoff, yoff, rows, magnif, mode)
     bits2hex(s)
     decspec(pattern)
     eqpats(prws, rows2)
     getpatt(line)
     getpattnote(line)
     hex2bits(s)
     hexspec(pattern)
     legalpat(tile)
     legaltile(tile)
     pat2xbm(pattern, name)
     tilebits(rows)
     pdensity(pattern)
     pix2pat(window, x, y, cols, rows)
     readpatt(input)
     readpattline(input)
     rowbits(pattern)
     pat2rows(pattern)
     rows2pat(rlist)
     showbits(pattern)
     tiledim(pattern)
     xbm2rows(input)

[ Summary entry | Source code ]


patxform.icn: Procedures to transform patterns in row form

procedure pborder:         place border around pattern
procedure pcaten:          concatenate patterns
procedure pcenter:         center pattern
procedure pcrop:           crop pattern
procedure pdisplay:        display pattern
procedure pdouble:         double pattern
procedure pflip:           flip pattern
procedure phalve:          halve pattern by bits
procedure pinvert:         invert B&W pattern
procedure pminim:          minimize pattern
procedure por:             "or" patterns
procedure protate:         rotate pattern
procedure pscramble:       scramble pattern
procedure pshift:          bit shift pattern
procedure ptrim:           trim pattern

link patxform
June 26, 2002; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

pborder(rows, l, r, t, b, c)
pcaten(rows1, rows2, dir)
pcenter(rows, w, h)
pcrop(rows, l, r, t, b)
pdisplay(rows)
pdouble(rows, dir)
pflip(rows, dir)
phalve(rows, dir, choice)
pinvert(rows)
pminim(rows)
por(rows1, rows2)
protate(rows, dir)
pscramble(rows, dir)
pshift(rows, shift, dir)
ptrim(rows, c)

[ Summary entry | Source code ]


pixelmap.icn: Procedure to create image from pixel list

link pixelmap
January 23, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

pixelmap(name, p, args[]) reads the pixel list in file name and
constructs an image, applying p ! args to each pixel.  If p is
omitted or null, the pixels are used as-is.

[ Summary entry | Source code ]


popular.icn: Procedure to show "popularity" of colors in image string

procedure popularity:      color popularity in image string

link popular
September 17, 1998; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure shows the "popularity" of colors in an image string.

[ Summary entry | Source code ]


psrecord.icn: Procedures for PostScript record of window

procedure PSEnable:        enable PostScript recording
procedure PSSnap:          take PostScript snapshot
procedure PSRaw:           output raw PostScript
procedure PSDisable:       disable PostScript recording
procedure PSDone:          terminate PostScript recording

link psrecord
June 16, 2010; Gregg M. Townsend
Contributors: Stephen B. Wampler and Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures intercept graphics calls in order to produce
a PostScript copy of what is drawn.  The record is decidedly
imperfect.
____________________________________________________________

   These procedures produce a PostScript record of the screen display
of an Icon program.  The technique used is to intercept calls to
graphics functions and write PostScript before calling the built-in
versions.

   Because the X emulation is imperfect, psrecord works best for
programs designed with it in mind.  Not all function calls are
intercepted; some such as CopyArea cannot be handled at all.  The
list of functions is in the internal routine PS_swap().  It is assumed
that there is only a single window and a single graphics context;
programs that switch among multiple graphics contexts will not be
recorded properly.

   PostScript recording is enabled by calling PSEnable(window, filename)
any time after after the window has been opened.  (The procedures in
"autopost.icn" may be used for this.)  Defaults for PSEnable are
&window and "xlog.ps".  At the end, PSDone() should be called to
properly terminate the file; when PSDone() is not called, the file is
still be legal but lacks the "showpage" command needed for printing.

   If the argument to PSDone is non-null, no showpage is written.
This is recommended for Encapsulated PostScript that is to be
placed in documents, since otherwise the bounding box resulting
from showpage may interfere with document layout.  showpage is, of
course, needed for PostScript that is to be printed stand-alone.

   Additional procedures provide more detailed control but must be used
with care.  PSDisable() and PSEnable() turn recording off and back on;
any graphics state changes during this time (such as changing the
foreground color) are lost.  PSSnap() inserts a "copypage" command in
the output; this prints a snapshot of the partially constructed page
without erasing it.  PSRaw() writes a line of PostScript to the output
file.

   PSStart(window, filename) is similar to PSEnable except that it
always starts a fresh output file each time it is called.

   The output file is legal Encapsulated PostScript unless PSSnap is
used; PSSnap renders the output nonconforming because by definition
an EPS file consists of a single page and does not contain a "copypage"
command.  It should be possible to postprocess such output to make a
set of legal EPS files.

   Some of the other limitations are as follows:
       Only a few font names are recognized, and scaling is inexact.
       Newlines in DrawString() calls are not interpreted.
       Output via write() or writes() is not recorded.
       The echoing of characters by read() or reads() is not recorded.
       DrawCurve output is approximated by straight line segments.
       Window resizing is ignored.
       Drawing arguments must be explicit; few defaults are supplied.

[ Summary entry | Source code ]


putpixel.icn: Procedure to write quantized, processed pixel

procedure PixInit:         initialize pixel processing
procedure PutPixel:        write pixel

link putpixel
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures assist pixel-by-pixel image construction.

PutPixel(W, x, y, k)    draws a single pixel after applying
                        dithering, color quantization, and
                        gamma correction.

PixInit(gamma, cquant, gquant, drandom)
                        initializes parameters for PutPixel().
____________________________________________________________

   PutPixel([win,] x, y, colr) sets the pixel at (x,y) to the given color
after applying dithering, color quantization, and gamma correction.
It is designed for constructing images a pixel at a time.  The window's
foreground color is left set to the adjusted color.

   Colr can be any value acceptable to Fg.  Mutable colors are not
dithered, quantized, or gamma-corrected.

   PixInit(gamma, cquant, gquant, drandom) may be called before PutPixel
to establish non-default parameters.  The default gamma value is 1.0
(that is, no correction beyond Icon's usual gamma correction).
cquant and gquant specify the number of color and grayscale quantization
steps; the defaults are 6 and 16 respectively.  If gquant + cquant ^ 3
exceeds 256 there is a potential for running out of colors.  drandom
is the fraction (0 to 1) of the dithering to be done randomly; the
default is zero.

[ Summary entry | Source code ]


randarea.icn: Procedures to generate random points in areas

link randarea
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

These procedures generate randomly selected points with specified
areas.

[ Summary entry | Source code ]


randfigs.icn: Procedures to generate random figures

link randfigs
March 27, 1993; Ralph E. Griswold
This file is in the public domain.

These procedures generate random geometrical figures.

[ Summary entry | Source code ]


rawimage.icn: Procedures to write and read images in raw format

link rawimage
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics and co-expressions
This file is in the public domain.

These procedures write and read raw image files.  The format of a raw
image file is:

     width,height
     <palette entries with 2 hex digits, a blank, and a color specification>
     <blank line>
     <image data consisting of pairs of hext digits in row-primary order>

These procedures are slow and should only be used when the image file
formats that Icon can read and write are not sufficient.

[ Summary entry | Source code ]


repeats.icn: Procedure to repeat image

procedure repeats:         repeat image

link repeats
August 23, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure produces repeats of an image specified number of times.

[ Summary entry | Source code ]


rgbcomp.icn: Procedures to perform computations on RGB values

link rgbcomp
January 14, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

rgbsum(s1, s2) returns a color whose RGB components are the sums of the
components for s1 and s2.

rgbdif(s1, s2) returns a color whose RGB components are the differences of
the components for s1 and s2.

rgbavg(s1, s2) returns a color whose RGB components are the averages of
the components for s1 and s2.

rsgcomp(s) returns the color that is the complement of s.

The results may not be what's expected in some cases.

[ Summary entry | Source code ]


rgbrec.icn: Procedure to produce RGB record from color specification

link rgbrec
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure produces a three-field RGB record from an Icon color
specification.  It fails id its argument is not a valid color specifi-
cation.

[ Summary entry | Source code ]


rpolys.icn: Procedure to produce traces of regular polygons

procedure rpoly:           generate polygon points

link rpolys
March 24, 1999; Ralph E. Griswold
This file is in the public domain.

Generate points for a regular polygon with the specified number of
vertices and radius, centered at cx and cy.  The offset angle is theta;
default 0.

[ Summary entry | Source code ]


rstars.icn: Procedure to generate traces of regular stars

procedure rstar:           regular star

link rstars
March 27, 1993; Ralph E. Griswold
This file is in the public domain.

This procedure generates traces of regular stars.

[ Summary entry | Source code ]


rstartbl.icn: Procedure to produce calls for regular stars

link rstartbl
April 8, 1993; Ralph E. Griswold
See also: rstars.icn
This file is in the public domain.

This procedure produces a table of calls from which regular stars
can be produced.

[ Summary entry | Source code ]


select.icn: Procedure to get selection from window

procedure select:          interactive selection from window

link select
August 30, 1996; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.


[ Summary entry | Source code ]


slider.icn: Procedures for slider sensors

link slider
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
See also: evmux.icn
This file is in the public domain.

These procedures implement slider using the "evmux" event
multiplexor instead of the usual vidget library.

slider(win, proc, arg, x, y, w, h, lb, iv, ub)  creates a slider.

slidervalue(h, v)                       modifies a slider's value.
____________________________________________________________

slider(win, proc, arg, x, y, w, h, lb, iv, ub)

     establishes a slider and returns a handle for use with slidervalue().

     x,y,w,h give the dimensions of the slider.  The slider runs vertically
     or horizontally depending on which of w and h is larger.  20 makes a
     nice width (or height).

     lb and ub give the range of real values represented by the slider;
     lb is the left or bottom end.  iv is the initial value.
     proc(win, arg, value) is called as the slider is dragged to different
     positions.

slidervalue(h, v)

     changes the position of the slider h to reflect value v.
     The underlying action procedure is not called.
____________________________________________________________

Example:  A simple color picker

     record color(red, green, blue)
     global win, spot

             ...
         Fg(win, spot := NewColor(win))
         Color(win, spot, "gray50")
         FillArc(win, 10, 10, 100, 100)
         Fg(win, "black")
         h1 := slider(win, setcolor, 1, 110, 10, 20, 100, 0, 32767, 65535)
         h2 := slider(win, setcolor, 2, 140, 10, 20, 100, 0, 32767, 65535)
         h3 := slider(win, setcolor, 3, 170, 10, 20, 100, 0, 32767, 65535)
             ...

     procedure setcolor(win, n, v)
         static fg
         initial fg := color(32767, 32767, 32767)
         fg[n] := v
         Color(win, spot, fg.red || "," || fg.green || "," || fg.blue)
     end

     Draw a filled circle in a mutable color that is initially gray.
     Draw three parallel, vertical sliders of size 20 x 100.  Their values
     run from 0 to 65535 and they are each initialized at the midpoint.
     (The values are only used internally; the sliders are unlabeled.)

     When one of the sliders is moved, call setcolor(win, n, v).
     n, from the "arg" value when it was built, identifies the slider.
     v is the new value of the slider.   Setcolor uses the resulting
     color triple to set the color of the mutable color "spot".

     Additional calls
         every slidervalue(h1 | h2 | h3, 32767)
         every setcolor(win, 1 to 3, 32767)
     would reset the original gray color.  Note that explicit calls to
     setcolor are needed because slidervalue does not call it.

[ Summary entry | Source code ]


spirals.icn: Procedure to produce traces of fractal stars

link spirals
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

Draw spiral with n segments and t rotations, starting at (x,y).
The extent determines the size of the drawing.

The eccentricity is e (1 gives circle) and the reduction factor is r.
The angular increment is incr and the y scaling factor is yfact.

[ Summary entry | Source code ]


spokes.icn: Procedure to draw spokes

link spokes
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

spokes(x, y, radius1, radius2, n, m) draws spokes.

[ Summary entry | Source code ]


strpchrt.icn: Procedure for dynamic stripchart for windows

procedure stripchart:      create stripchart
procedure sadvance:        advance stripchart
procedure smark:           mark stripchart

link strpchrt
August 14, 1996; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

A stripchart models a continuous roll of paper that is marked along
the right edge while it moves continuously to the left.  This is
also known as a chart recording.

stripchart(window, x, y, width, height) creates a stripchart.

sadvance(sc)                            advances a stripchart.

smark(sc, y1, y2)                       marks a stripchart.
____________________________________________________________

stripchart(window, x, y, width, height)

    establishes a stripchart and returns a record sc for use with
    other procedures.

    The chart can be marked by calling smark() or by drawing directly
    at location (sc.x, y) where y is arbitrary.

sadvance(sc)

    advances the stripchart by one pixel.

smark(sc, y1, y2)

    marks the current position of the stripchart from y1 to y2.  y2 may
    be omitted, in which case a single pixel at (sc.x, y1) is marked.

    If the chart has not been advanced since the last mark at y1,
    nothing happens.

[ Summary entry | Source code ]


subturtl.icn: Procedures for turtle-graphics (subset version)

procedure TInit:           initialize turtle system
procedure TReset:          reset turtle system
procedure TDraw:           draw with turtle
procedure TDrawto:         draw to with turtle
procedure TSkip:           skip with turtle
procedure TGoto:           goto with turtle
procedure TRight:          turn turtle right
procedure TLeft:           turn turtle left
procedure TFace:           turn turtle to face point
procedure TX:              turtle x coordinate
procedure TY:              turtle y coordinate
procedure THeading:        turtle heading
procedure TSave:           save turtle state
procedure TRestore:        restore turtle state

link subturtl
January 30, 1996; Gregg M. Townsend
Requires: Version 9 graphics
See also: turtle.icn
This file is in the public domain.

These procedures implement a simplified subset of the turtle.icn
package.  The main omissions are scaling, TWindow(), THome(), and
high-level primitives like TCircle().  Some procedures accept fewer
arguments, omit defaults, or omit the return value.
____________________________________________________________

The procedures are as follows:

TDraw(n) -- move forward and draw
TSkip(n) -- skip forward without drawing
     The turtle moves forward n units.  n can be negative to move
     backwards.

TDrawto(x, y) -- draw to the point (x,y)
     The turtle turns and draws a line to the point (x,y).
     The heading is also set as a consequence of this movement.

TGoto(x, y) -- set location
     The turtle moves to the point (x,y) without drawing.
     The turtle's heading remains unaltered.

TRight(d) -- turn right
TLeft(d) -- turn left
     The turtle turns d degrees to the right or left of its current
     heading.  Its location does not change, and nothing is drawn.

TFace(x, y) -- set heading
     The turtle turns to face directly to face the point (x,y).
     If the turtle is already at (x,y), the heading does not change.

TX() -- query current x position
TY() -- query current y position
     The x- or y-coordinate of the turtle's current location is
     returned.

THeading() -- query heading
     The turtle's heading (in degrees) is returned.

TSave() -- save turtle state
TRestore() -- restore turtle state
     TSave saves the current turtle window, location, and heading
     on an internal stack.  TRestore pops the stack and sets
     those values, or fails if the stack is empty.

TReset() -- clear screen and reinitialize
     The window is cleared, the turtle moves to the center of the
     screen without drawing, the heading is set to -90 degrees, and
     the TRestore() stack is cleared.  These actions restore the
     initial conditions.

[ Summary entry | Source code ]


symrand.icn: Procedures to generate random points

link symrand
August 14, 1996; Ralph E. Griswold
This file is in the public domain.

rand(x, y, extentx, extenty, n) generates random points in a rectangle.

symrand(x, y, extentx, extenty, size, n) generates points symmetrically.

[ Summary entry | Source code ]


tieedit.icn: Procedures to create and edit binary arrays

link tieedit
January 19, 2002; Ralph E. Griswold and Gregg M. Townsend
Requires: Version 9 graphics, /tmp
This file is in the public domain.

This package provides a variety of facilities for creating and
editing binary arrays.  It is intended for use with weaving tie-ups
and liftplans.

[ Summary entry | Source code ]


tieutils.icn: Procedures related to weaving tie-ups

procedure imr2tie:         convert image record to tie-up
procedure pat2tie:         convert pattern to tie-up string
procedure pat2tier:        convert pattern to tie-up record
procedure showpat:         image of bi-level pattern
procedure testtie:         test validity of tie-up s
procedure tie2imr:         convert tie-up to image record
procedure tie2pat:         convert tie-up record to ims
procedure tie2tier:        create 0/1 tie-up record
procedure tie2coltier:     create color tie-up record
procedure tier2string:     convert tie-up record to string
procedure twill:           twill tie-up
procedure direct:          direct tie-up
procedure satin:           satin tie-up
procedure tabby:           tabby tie-up
procedure general:         general tie-up
procedure exptie:          expression tie-up

link tieutils
September 15, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

imr2tie(imr)    converts g2 image record to tie-ip

pat2tie(pat)    converts bi-level pattern to tie-up string

pat2tier(pat)   converts bi-level pattern to tie-up record

showpat(pat, size, fg, bg)
                produces a hidden window for the pattern as a matrix
                with the specified foreground and background colors

str2matrix(shafts, treadles, s)
                produce matrix from binary string

testtie(s)      succeeds if s is a valid tie-up but fails otherwise

tie2imr(s)      converts tie-up to g2 image record

tie2pat(i, j, tie)
                converts tie-up to bi-level pattern

tie2coltier(s)  creates a black/white color tieup-record for
                  tie-up s

tie2tier(s)     creates a 0/1 tie-up record for tie-up s

tier2rstring(r) creates a tie-up string from a tie-up record

twill(pattern, shift, shafts)
                twill tie-up

overunder(pattern, treadles)
                over/under tie-up structure

direct(shafts, treadles)
                direct tie-up

satin(counter, shafts, treadles)
                satin tie-up

tabby(shafts, treadles)
                tabby tie-up

general(pattern, shift, rep, shafts)
                general tie-up

exptie(expression, shafts, treadles)
                expression tie-up

[ Summary entry | Source code ]


tile.icn: Procedure to tile window

procedure tile:            tile area with image

link tile
September 29, 1997; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure tiles a portion of win1 over the specified portion
of win2, doubling to reduce the number of copies required.

[ Summary entry | Source code ]


tiler.icn: Procedures to tile window with image

procedure tileimg:         tile image
procedure tileims:         tile image string

link tiler
December 18, 1997; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

tileimg(win, image) tiles win with copies of image.

tileims(win, ims) tiles win with copies of the image specified by ims

Note that tileimg() uses the gamma value of win.

[ Summary entry | Source code ]


turtle.icn: Procedures for turtle-graphics interface

procedure TWindow:         set turtle window
procedure TInit:           initialize turtle system
procedure TReset:          reset turtle system
procedure THome:           return turtle to home
procedure TScale:          turtle scaling
procedure THeading:        turtle heading
procedure TRight:          turn turtle right
procedure TLeft:           turn turtle left
procedure TFace:           face turtle
procedure TX:              turtle x coordinate
procedure TY:              turtle y coordinate
procedure TDraw:           draw with turtle
procedure TSkip:           skip with turtle
procedure TGoto:           go to with turtle
procedure TDrawto:         draw to with turtle
procedure TSave:           save turtle state
procedure TRestore:        restore turtle state
procedure TRect:           draw rectangle centered at turtle
procedure TFRect:          draw filled rectangle centered at turtle
procedure TCircle:         draw circle centered at turtle
procedure TFCircle:        draw filled circle centered at turtle
procedure TPoly:           draw polygon centered at turtle
procedure TFPoly:          draw filled polygon centered at turtle

link turtle
August 8, 2000; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

These procedures provide a "turtle graphics" interface to Icon.
With this approach, popularized by the Logo programming language,
all drawing is done by a "turtle" that carries a pen over a drawing
surface under program control.

TWindow(W)      sets the turtle window.

TDraw(n)        moves forward and draws.

TSkip(n)        skips forward without drawing.

TDrawto(x, y)   draws to the point (x,y).

TScale(n)       sets or queries current scaling factor.

TRight(d)       turns right d degrees.

TLeft(d)        turns left d degrees.

THeading(a)     sets or queries the heading.

TFace(x, y)     sets or queries the heading.

TX(x)           sets or queries the current x position.

TY(y)           sets or queries the current y position.

TGoto(x, y, a)  sets the location and optionally changes the heading.

THome()         moves to the window center and turns to face upward.

TReset()        clears the window and reinitializes.

TSave()         saves the turtle state.

TRestore()      restores the turtle state.

TRect(h, w)     draws a rectangle centered at the turtle.

TCircle(d)      draws a circle centered at the turtle.

TPoly(d, n)     draws a polygon centered at the turtle.

TFRect(h, w)    draws a filled rectangle centered at the turtle.

TFCircle(d)     draws a filled circle centered at the turtle.

TFPoly(d, n)    draws a filled polygon centered at the turtle.
____________________________________________________________

In this package there is a single turtle which is itself invisible;
it is known only by the marks it leaves on the window.  It remembers
its location and heading between calls.

No explicit initialization is required.  The turtle begins at the
center of the window with a heading of -90 degrees (that is, pointed
towards the top of the window).

The turtle draws on &window unless a different window is specified by
calling TWindow().  If no window is provided and &window is null,
a 500x500 window is opened and assigned to &window.

Distances are measured in pixels and are always multiplied by a
settable scaling factor, initially 1.  Angles are measured in degrees;
absolute angles measure clockwise from the positive X axis.
____________________________________________________________

The procedures are as follows:

TDraw(n) -- move forward and draw
TSkip(n) -- skip forward without drawing
     The turtle moves forward n units.  n can be negative to move
     backwards.
     Default:  n = 1

TDrawto(x, y) -- draw to the point (x,y)
     The turtle turns and draws a line to the point (x,y).
     The heading is also set as a consequence of this movement.
     Default:  center of window

TScale(n) -- set or query current scaling factor.
     If n is supplied, the scaling factor applied to TDraw and TSkip
     arguments is *multiplied* (not replaced) by n.  The resulting
     (multiplied or unaltered) scaling factor is returned.
     The turtle's heading and location do not change.

TRight(d) -- turn right
TLeft(d) -- turn left
     The turtle turns d degrees to the right or left of its current
     heading.  Its location does not change, and nothing is drawn.
     The resulting heading is returned.
     Default:  d = 90

THeading(a) -- set or query heading
     The turtle's heading (in degrees) is returned.  If a is supplied,
     the heading is first set to that value.  The location does not
     change.

TFace(x, y) -- set or query heading
     The turtle turns to face directly towards the point (x,y).
     If x and y are missing or the turtle is already at (x,y),
     the heading does not change.  The new heading is returned.
     Default: center of window

TX(x) -- set or query current x position
TY(y) -- set or query current y position
     The unscaled x- or y-coordinate of the turtle's current location
     is returned.  If an argument is supplied, the coordinate value
     is first set, moving the turtle without drawing.  The turtle's
     heading does not change.

TGoto(x, y, a) -- set location and optionally change heading
     The turtle moves to the point (x,y) without drawing.
     The turtle's heading remains unaltered unless <a> is supplied,
     in which case the turtle then turns to a heading of <a>.
     Default:  center of window

THome() -- move to home (center of window) and point North
     The turtle moves to the center of the window without drawing
     and the heading is set to -90 degrees.  The scaling factor
     remains unaltered.

TReset() -- clear window and reinitialize
     The window is cleared, the turtle moves to the center of the
     window without drawing, the heading is set to -90 degrees, the
     scaling factor is reset to 1, and the TRestore() stack is
     cleared.  These actions restore the initial conditions.

TSave() -- save turtle state
TRestore() -- restore turtle state
     TSave saves the current turtle window, location, heading, and
     scale on an internal stack.  TRestore pops the stack and sets
     those values, or fails if the stack is empty.

TRect(h, w) -- draw a rectangle centered at the turtle
TCircle(d) -- draw a circle centered at the turtle
TPoly(d, n) -- draw an n-sided regular polygon centered at the turtle
     These three procedures draw a figure centered at the turtle's
     current location.  The location and heading do not change.
     The base of the figure, if any, is directly behind the turtle.

     TRect(h, w) draws a rectangle of height h and width w.
     "width" is the dimension perpendicular to the turtle's path.
     Default:  h = 1
               w = h

     TCircle(d) draws a circle of diameter d.
     Default:  d = 1

     TPoly(d, n) draws an n-sided regular polygon whose circumscribed
     circle would have a diameter of d.
     Default:  d = 1
               n = 3

TFRect(h, w) -- draw a filled rectangle centered at the turtle
TFCircle(d) -- draw a filled circle centered at the turtle
TFPoly(d, n) -- draw an n-sided filled polygon centered at the turtle
     These are like their counterparts above, but a solid figure is
     drawn instead of just an outline.

TWindow(win) -- set turtle window
     The turtle is moved to the given window, retaining its
     coordinates and heading.
     Default:   win = &window

These procedures do not attempt to provide a complete graphics interface;
in particular, no control of color is provided.  Missing functions can
be accomplished by calling the appropriate Icon routines.

Unlike most turtle graphics environments, there are no commands to
lift and drop the pen.  Instead, use TSkip() to move without drawing,
or set WAttrib("drawop=noop") if you really need a global "pen up"
state.

[ Summary entry | Source code ]


twists.icn: Procedures to produce traces of "twists"

link twists
May 2, 2001; Ralph E. Griswold
This file is in the public domain.

These procedures produce traces of twisting orbits.  See

     Geometric and Artistic Graphics; Design Generation with
     Microcomputers, Jean-Paul Delahaye, Macmillan, 1987, pp. 73-80.

The arguments specify the starting positions, the extent of the
drawing, the number of segments, and various parameters that determine
the orbits.

[ Summary entry | Source code ]


vfilter.icn: Procedure to change filter mode in sliders and scrollbars

procedure VSetFilter:      filter mode of slider/scrollbar

link vfilter
March 3, 1998; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

VSetFilter(vidget, value) sets the appropriate field in the structure for
vidget to change the filtering mode (null for no filtering, "1" for
filtering).

[ Summary entry | Source code ]


vidgets.icn: Procedures for vidgets

link vidgets
September 17, 1997; Jon Lipp
This file is in the public domain.

Links to basic vidget files needed to use the library.

[ Summary entry | Source code ]


vsetup.icn: Procedures for vidget application setup

link vsetup
October 9, 1997; Gregg M. Townsend
This file is in the public domain.

vsetup(win, cbk, wlist[]) initializes a set of widgets according to
a list of specifications created by the interface editor VIB.

win can be an existing window, a list of command arguments to be
passed to Window(), null, or omitted.  In the latter three cases
a new window is opened if &window is null.

cbk is a default callback routine to be used when no callback is
specified for a particular vidget.

wlist is a list of specifications; the first must be the Sizer and
the last may be null.  Each specification is itself a list consisting
of a specification string, a callback routine, and an optional list
of additional specifications.  Specification strings vary by vidget
type, but the general form is "ID:type:style:n:x,y,w,h:label".

vsetup returns a table of vidgets indexed by vidget ID.
The root vidget is included with the ID of "root".

[ Summary entry | Source code ]


wattrib.icn: Procedures for attributes

link wattrib
March 6, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These are "helper" procedures to use in place of WAttrib().

This is a work in progress; at present it only handles fetching
of a few attribute values.

[ Summary entry | Source code ]


weavegif.icn: Procedure to produce a woven image from a draft

procedure weavegif:        create GIF from ISD

link weavegif
June 10, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure produces a woven image from a pattern-form draft, which
is passed to it as it's first argument.  Window attributes may be
passed as a list in the second argument

[ Summary entry | Source code ]


wifisd.icn: Procedure to convert WIF to xencoded ISD

link wifisd
April 6, 2002; Ralph E. Griswold
This file is in the public domain.

This procedure analyzes a Weaving Information File and returns xencoded
ISD.

Information in a WIF that is not necessary for an ISD is ignored.

If there is a liftplan, the symbols in the treadling sequence
correspond to shaft patterns given in the liftplan.  The symbols
for these pattern shafts are implicit and occur in orde to the number
of shaft patterns.

There is a problem where there is treadling with multiple treadles
and no liftplan.  *Presumably* that treadling can be used like a
liftplan, but without, necessarily, a direct tie-up.  This problem
problem has not been addressed yet.

If there is a liftplan, then a direct tie-up is implied by the
wording in the WIF documentation.  However, that's in the interpretation
of the draft.  The tie-up produced here is the one given in the WIF.

If there is a liftplan and a treadling with multiple treadles,
the treadling is ignored.

This procedure does not attempt to detect or correct errors in WIFs,
but it does try to work around some common problems.

[ Summary entry | Source code ]


win.icn: Procedures to open bare-bones window

link win
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures are provided as quick-and-dirty ways to get a
nominal window as, for example, when testing.

win() causes error termination if a window can't be opened.
winf(), on the other hand, just fails.

[ Summary entry | Source code ]


window.icn: Procedure for opening window

link window
October 10, 1997; Gregg M. Townsend
Requires: Version 9 graphics
This file is in the public domain.

Window() opens a window with provisions for option processing and
error handling.  The returned window is assigned to &window if
&window is null.  If the window cannot be opened, the program is
aborted.

The characteristics of the window are set from several sources:
Window's arguments, optionally including the program argument list;
user defaults; and built-in defaults.  These built-in defaults are
the same as for optwindow(): bg=pale gray, fg=black, size=500,300.
____________________________________________________________

With one exception, arguments to Window() are attribute specifications
such as those used with open() and WAttrib().  Order is significant,
with later attributes overriding earlier ones.

Additionally, the program argument list -- the single argument passed
to the main procedure -- can be passed as an argument to Window().
Options specified with a capital letter are removed from the list and
interpreted as attribute specifications, again in a manner consistent
with optwindow().

Because the Window() arguments are processed in order, attributes that
appear before the program arglist can be overridden by command-line
options when the program is executed.  If attributes appear after the
program arglist, they cannot be overridden.  For example, with

     procedure main(args)
     Window("size=600,400", "fg=yellow", args, "bg=black")

the program user can change the size and foreground color
but not the background color.

User defaults are applied at the point where the program arglist appears
(and before processing the arglist).  If no arglist is supplied, no
defaults are applied.  Defaults are obtained by calling WDefault().
Icon attribute names are used as option names;  &progname is used
as the program name after trimming directories and extensions.

The following table lists the options recognized in the program arglist,
the corresponding attribute (and WDefault()) names, the default values
if any, and the meanings.  All legal attributes are allowed in the
Window() call, but only these are set from the command line or
environment:

     arg     attribute       default         meaning
     ---     ---------       -------         --------------------------
     -B      bg              pale gray       background color
     -F      fg              black           foreground color
     -T      font             -              text font
     -L      label           &progname       window title
                             (trimmed)

     -D      display          -              window device
     -X      posx             -              horizontal position
     -Y      posy             -              vertical position
     -W      width           500             window width
     -H      height          300             window height

     -S      size            500,300         size
     -P      pos              -              position
     -G      geometry         -              window size and/or position

     -A      <any>            -              use "-A name=value"
                                             to set arbitrary attribute

     -!       -               -              write open() params to &error
                                             (for debugging)

[ Summary entry | Source code ]


winsnap.icn: Procedure to take snapshot of a portion of a window

link winsnap
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

This procedure writes an image file for a specified portion of a
window.  The name for the file is requested from the user via a
dialog box.  If there already is a file by the specified name, the
user is given the option of overwriting it or selecting another
name.  The procedure fails if the user cancels.

[ Summary entry | Source code ]


wipe.icn: Procedure to wipe window area

link wipe
May 2, 2001; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

wipe(window, color, direction, x, y, w, h)  "wipes" a rectangular area of
window to the specified color.  The direction of wiping can be any one of:

     "right"         from left to right
     "left"          from right to left
     "down"          from top to bottom
     "up             from bottom to top
     "left-right"    from left and right toward center
     "up-down"       from top and bottom toward center
     "in"            from outside to inside

The default direction is "right".

The default color is the background color of the window.

x, y is the top left corner of the area and w and h are the width and
height. An omitted value defaults to the one for the entire window.

[ Summary entry | Source code ]


wopen.icn: Procedures for graphics input/output

link wopen
April 15, 2002; Gregg M. Townsend and Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures provide window input and output using "W" names as
substitutes for standard input and output functions.  WOpen() opens
and returns a window; the result is also assigned to &window if
&window is null.

WOpen(attrib, ...)      opens and returns a window.

WRead(W)                reads a line from a window.

WReads(W, i)            reads i characters from a window.

WWrite(W, s, ...)       writes a line to window.

WWrites(W, s, ...)      writes a partial line to window.

WDelay(W, n)            flushes a window, then delays n milliseconds.
                        default:  n = 1

WClose(W)               closes a window;
                        if W === &window, sets &window to &null.

WDone(), WQuit(), QuitCheck(), and QuitEvents() incorporate knowledge
of the Icon standard set of "quit" events, currently the letters
"q" or "Q".  The procedures themselves are trivial.

WQuit() consumes unread window events and succeeds if a quit event
is seen.  It does not wait.  WDone() waits until a quit event is read,
then exits the program.  QuitCheck(ev) calls exit() if its parameter
is a quit event; QuitCheck can be used with the vidget package as a
default event handler.  QuitEvents() generates the standard set of
quit events.

ZDone() is a zooming version of WDone().  If the window is resized
while waiting for a quit event, its contents are zoomed to fill the
new size.  Zooming to a multiple of the original size can also be
accomplished by typing a nonzero digit into the window.

SubWindow(W, x, y, w, h) produces a subwindow by creating and
reconfiguring a clone of the given window.  The original window
is not modified.  In the clone, which is returned, clipping
bounds are set by the given rectangle and the origin is
set at the rectangle's upper left corner.

[ Summary entry | Source code ]


xbfont.icn: Procedures for X font selection

procedure BestFont:        generate best X fonts
procedure RankFonts:       generate scores for X fonts

link xbfont
May 2, 2001; Gregg M. Townsend
Requires: Version 9 graphics under Unix
This file is in the public domain.

BestFont(W, s, ...) generates X-windows font names matching a
given specification, beginning with the closest match.  The
ranking algorithm is similar to that used in Font() but it is
not identical.
____________________________________________________________

   BestFont(window, spec, ...) returns the name of whichever available
X-Windows font most closely matches the given specification.  Note that
matching is done using a slightly different algorithm from that of the
Icon runtime system; this procedure preceded Icon's font selection
implementation and served as a prototype.

   The font specification is one or more strings containing whitespace-
or comma-separated tokens.  Tokens are case-insensitive.  There are
three kinds of tokens.
   A token having the form of an integer specifies the desired "pixel
size" (height).  If no size is included, a target size of 14 is used.
   An unrecognized token is taken as a substring of the desired X font
name.  Family names, weights, and other such factors are specified this
way.
   Certain tokens are recognized and handled specially:
      m  mono  monospaced
      p  prop  proportional
      r  roman
      i  italic
      o  oblique
      s  sans  sans-serif  sansserif
These are turned into search strings of a particular form.  For example,
"roman" and "r" specify the search string "-r-".

   The "best match" to a given specification is calculated by reviewing
all the available fonts, assigning a score to each, then choosing the
one with the highest value.  There are several aspects of scoring.
   Size is the most important factor.  A tuned font of the correct size
gets the maximum score.  Nearby sizes receive partial credit, with
an undersized font preferred over an oversized font.  Scalable fonts
are also recognized, but a tuned font of the correct or nearly-correct
size gets a higher score.
   Each successful substring match increases the score, whether the
test string comes from an unrecognized token or a special keyword.
Earlier tokens receive slightly more weight than later ones.
   All tokens need not match.  The string "lucida gill sans 18"
is perfectly reasonable; it specifies a preference for Lucida Sans
over Gill Sans by the position of the tokens, but will match either.
   Ties are broken by giving slight preferences for normal weight,
no slant, normal width, and ASCII ("iso8859") encoding.  A slight
penalty is assessed for "typewriter" fonts.  Oblique fonts receive
partial credit for matching "italic" requests, and vice versa.
   The scoring function can be altered by assigning values to certain
global variables.  See XBF_defaults() for a commented list of these.

   For a scalable font, the returned value is a string specifying an
instance of the font scaled to the target size.  For large sizes, the
scaling time may be noticeable when the font is used.

   BestFont() is actually a generator that produces the entire list
of available fonts in order of preference.  RankFonts(w, spec, ...)
is similar to BestFont but produces a sequence of two-element records,
where result.str is the font name and result.val is its score.  For
either of these, a list of X font names can be passed instead of a
window.

   There is some startup cost the first time BestFont is called; it
opens a pipe to the "xlsfonts" program and reads the output.  Results
are cached, so this overhead is only incurred once.

   Examples:
      Font(w, BestFont(w, "times bold italic 20"))
      s := BestFont(w, size, family, "italic")

[ Summary entry | Source code ]


xform.icn: Procedures to transform points

link xform
October 1, 1997; Ralph E. Griswold
This file is in the public domain.

This file contains procedures that manipulate points representing
vertices.

[ Summary entry | Source code ]


xformimg.icn: Procedures to transform image

link xformimg
February 4, 1995; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

These procedures perform reflections, rotations, and concatenations
of images.

Warning:  Some of these operations are slow.

[ Summary entry | Source code ]


xgtrace.icn: Procedures to draw traces of points

link xgtrace
November 19, 1997; Ralph E. Griswold
Requires: Version 9 graphics
This file is in the public domain.

As used here, the term "trace" refers to a sequence of points that
generally consists of locations on a curve or other geometrical object.

[ Summary entry | Source code ]


Program Library Page | Icon Home Page