Icon Graphics Facilities; Appendix A: Graphics Procedures

Appendix A

Graphics Procedures

In addition to the notation used in the Icon language book [1] to denote argument types, the following characters have meaning as indicated:

   W      window             graphics source or destination
   a      any type           arbitrary value
   x, y   integer            coordinate location
   w, h   integer            width and height of a rectangle
   theta  real               angle (measured in radians)
   alpha  real               angle (measured in radians)
   k      string or integer  color specification

Either or both of w and h can be negative to indicate a rectangle that extends leftward or upward from its given coordinates. A color specification is either an integer obtained from NewColor() or a string having one of these forms:

   [lightness] [saturation] [hue[ish]] hue
   red,green,blue
   #hexdigits
   system-dependent-color-name

Any window argument named W can be omitted, in which case the subject window, &window, is used. Note that this is not the same as a default argument: to use the subject window, the argument is omitted entirely, not replaced by a null argument.

The notation "......" in an argument list indicates that additional argument sets can be provided, producing the same effect as multiple calls. The optional window argument, W, is not repeated in these additional argument sets.

The list that follows includes some procedures that are not built into Icon itself but are instead part of the library. For these, the corresponding link file is noted. Alternatively, link graphics incorporates all procedures listed.

Only a small portion of the library is documented here; the full library [4] is much more extensive.

Active() : W -- produce active window

Active() returns a window that has one or more events pending, waiting if necessary. Successive calls avoid window starvation by checking the open windows in a different order each time. Active() fails if no window is open.

See also: Pending()

Alert(W) : W -- alert user

Alert() produces a beep or other signal to attract attention.

Bg(W, k1) : k2 -- set or query background color

Bg() returns the background color. If k1 is supplied, the color is first set to that specification; failure occurs if the request cannot be satisfied. Setting the background color does not change the appearance of the window, but subsequent drawing operations that use the background color are affected.

See also: EraseArea(), Fg(), and FreeColor()

CenterString(W, x, y, s) : W -- draw centered string

CenterString() draws a text string that is centered vertically and horizontally about (x,y).

Link: gpxop

See also: DrawString(), LeftString(), and RightString()

Clip(W, x, y, w, h) : W -- set clipping rectangle

Clip() sets the clipping region to the specified rectangle; subsequent output extending outside its bounds is discarded. If Clip() is called with no arguments, clipping is disabled and the entire canvas is writable.

Defaults: w, h   to edge of window

Clone(W, s1, s2,..., sn) : W -- create new context with existing canvas

Clone() produces a new window value that combines the canvas of W with a new graphics context. The new graphics attributes are copied from W and modified by the arguments of Clone(). Invalid arguments produce failure as in WAttrib().

See also: Couple() and WAttrib()

Color(W, i, k1, ) : k2 -- set or query mutable color

Color() returns the setting of mutable color i if k1 is omitted. If k1 is supplied, color i is changed as specified, with an immediate effect on any visible pixels of that color. Additional index and color pairs may be supplied to set multiple entries with one call. Color() fails if a color specification is invalid.

See also: NewColor()

ColorDialog(W, L, k, p, a) : s -- display color selection dialog

ColorDialog() displays a color selection dialog box with Okay and Cancel buttons. The box is headed by zero or more captions specified by the list L, or a single string argument if passed in place of a list. If k is supplied, it specifies a reference color to be displayed below the color being adjusted.

If a callback procedure p is supplied, then p(a, s) is called whenever the color settings are adjusted. The argument a is an arbitrary value from the ColorDialog() call; s is the new color setting in the form returned by ColorValue().

The color initially is set to k , if supplied, or otherwise to the foreground color. The final color setting, in ColorValue() form, is stored in the global variable dialog_value. ColorDialog() returns the name of the button that was selected.

Defaults: L   "Select color:"

Link: dialog

ColorValue(W, k) : s -- translate color to canonical form

ColorValue() interprets the color k and returns a string of three comma-separated integer values denoting the color's red, green, and blue components. ColorValue() fails if k is not a valid color specification.

CopyArea(W1, W2, x1, y1, w, h, x2,

y2)
: W1

-- copy rectangle

CopyArea() copies a rectangular region (x1, y1, w, h) of window W1 to location (x2, y2) on window W2. If W2 is omitted, W1 is used as both source and destination. If W1 is omitted, the subject window is used.

Defaults: x1, y1   upper-left pixel
          w, h     to edge of window
          x2, y2   upper-left pixel

Couple(W1, W2) : W3 -- couple canvas and context

Couple() produces a new window value that binds the canvas of W1 with the graphics context of W2. Both arguments are required.

See also: Clone() and WAttrib()

DrawArc(W, x, y, w, h, theta, alpha, ......
) : W

-- draw arc

DrawArc() draws an arc of the ellipse inscribed in the rectangle specified by (x, y, w, h). The arc begins at angle theta and extends by an angle alpha.

Defaults: x, y   upper-left pixel
          w, h   to edge of window
          theta  0
          alpha  2 pi

See also: DrawCircle() and FillArc()

DrawCircle(W, x, y, r, theta, alpha,
......) : W

-- draw circle

DrawCircle() draws an arc or circle of radius r centered at (x,y). theta is the starting angle and alpha is the extent of the arc.

Defaults: theta  0
          alpha  2 pi

See also: DrawArc() and FillCircle()

DrawCurve(W, x1, y1, x2, y2, ... , xn,
yn) : W

-- draw curve

DrawCurve() draws a smooth curve through the points given as arguments. If the first and last point are the same, the curve is smooth and closed through that point.

See also: DrawLine() and DrawPolygon()

DrawImage(W, x, y, s) : i -- draw rectangular figure

DrawImage() draws an arbitrarily complex figure in a rectangular area at (x,y). s has one of these forms:

   "width,palette,data"  character-per-pixel image
   "width,#hexdigits"    bi-level image
   "width,~hexdigits"    transparent bi-level image

DrawImage() normally returns the null value, but if some colors cannot be allocated, it returns the number of colors that cannot be allocated.

Defaults: x, y   upper-left pixel

See also: Pattern() and ReadImage()

DrawLine(W, x1, y1, x2, y2, ... , xn, yn)
: W

-- draw line

DrawLine() draws line segments connecting a list of points in succession.

See also: DrawCurve(), DrawPolygon(), and DrawSegment()

DrawPoint(W, x, y, ...... ) : W -- draw point

DrawPoint() draws a point at each coordinate location given.

DrawPolygon(W, x1, y1, ... , xn, yn)
: W

-- draw polygon

DrawPolygon() draws the outline of a polygon formed by connecting the given points in order, with x1,y1 following xn,yn.

See also: DrawCurve(), DrawLine(), and FillPolygon()

DrawRectangle(W, x, y, w, h, ......
) : W

-- draw rectangle

DrawRectangle() draws the outline of the rectangle with corners at (x,y) and (x+w,y+h).

Defaults: x, y   upper-left pixel
          w, h   to edge of window

See also: FillRectangle()

DrawSegment(W, x1, y1, x2, y2, ......
) : W

-- draw line segment

DrawSegment() draws a line between two points. Additional pairs of coordinates may be supplied to draw additional, disconnected segments.

See also: DrawLine()

DrawString(W, x, y, s, ...... ) : W -- draw text

DrawString() draws a string of characters starting at (x,y) without altering the text cursor.

Enqueue(W, a, x, y, s, i) : W -- append event to queue

Enqueue() adds event a to the window event list with an event location of (x,y). The string s specifies a set of modifier keys using the letters c, m, and s to represent &control, &meta, and &shift, respectively. i specifies a value for &interval, in milliseconds.

Defaults: a   &null
          x   0
          y   0
          s   ""
          i   0

Link: enqueue

See also: Pending()

EraseArea(W, x, y, w, h, ...... ) : W -- clear rectangular area

EraseArea() fills a rectangular area with the background color.

Defaults: x, y   upper-left pixel
          w, h   to edge of window

See also: FillRectangle()

Event(W) : a -- return next window event

Event() returns the next event from a window, waiting if necessary. The keywords &x, &y, &row, &col, &interval, &control, &shift, and &meta are set as side effects of calling Event().

See also: Active(), Enqueue(), Pending(), WRead(), and WReads()

Fg(W, k1) : k2 -- set or query foreground color

Fg() returns the foreground color. If k1 is supplied, the color is first set to that specification; failure occurs if the request cannot be satisfied. Setting the foreground color does not change the appearance of the window, but subsequent drawing operations are affected.

See also: Bg(), FreeColor(), and Shade()

FillArc(W, x, y, w, h, theta, alpha, ......
) : W

-- draw filled arc

FillArc() draws a filled arc of the ellipse inscribed in the rectangle specified by (x, y, w, h). The arc begins at angle theta and extends by an angle alpha.

Defaults: x, y   upper-left pixel
          w, h   to edge of window
          theta  0
          alpha  2 pi

See also: DrawArc() and FillCircle()

FillCircle(W, x, y, r, theta, alpha, ......
) : W

-- draw filled circle

FillCircle() draws a filled arc or circle of radius r centered at (x,y). theta is the starting angle and alpha is the extent of the arc.

Defaults: theta   0
          alpha   2 pi

See also: DrawCircle() and FillArc()

FillPolygon(W, x1, y1, x2, y2, ... ,
xn, yn) : W

-- draw filled polygon

FillPolygon() draws and fills the polygon formed by connecting the given points in order, with x1,y1 following xn,yn.

See also: DrawPolygon()

FillRectangle(W, x, y, w, h, ......
) : W

-- draw filled rectangle

FillRectangle() draws a filled rectangle.

Defaults: x, y   upper-left pixel
                 w, h to edge of window

See also: DrawRectangle() and EraseArea()

Font(W, s1) : s2 -- set or query text font

Font() returns the text font. If s1 is supplied, the font is first set to that specification; failure occurs if the request cannot be satisfied.

FreeColor(W, k, ...... ) : W -- free color

FreeColor() informs the graphics system that the color k no longer appears in the window. This may allow the system to reclaim some resources. Unpredictable results may occur if the color is still present in the window.

See also: Bg(), Fg(), and NewColor()

GotoRC(W, i1, i2) : W -- move text cursor to row and column

GotoRC() sets the text cursor position to row i1 and column i2, where the character position in the upper-left corner of the window is 1,1 and calculations are based on the current font attributes.

Defaults: x, y   1, 1

See also: GotoXY()

GotoXY(W, x, y) : W -- move text cursor to coordinate position

GotoXY() sets the text cursor position to the specified coordinate position.

Defaults: x, y   0, 0

See also: GotoRC()

LeftString(W, x, y, s) : W -- draw left-justified string

LeftString() draws a text string that is left-justified at position x and centered vertically about y.

Link: gpxop

See also: CenterString(), DrawString(), and RightString()

Lower(W) : W -- lower window to bottom of window stack

Lower() sets a window to be "below" all other windows, causing it to become obscured by windows that overlap it.

See also: Raise()

NewColor(W, k) : i -- allocate mutable color

NewColor() allocates a changeable entry in the color map and returns a small negative integer that serves as a handle to this entry. If k is supplied, the color map entry is initialized to that color. NewColor() fails if no mutable entry is available.

See also: Color() and FreeColor()

Notice(W, s1, s2, ... , sn) : sm -- display strings and await response

Notice() posts a dialog box with an Okay button and returns "Okay" after response by the user. Each string sn is displayed centered on a separate line in the dialog box.

Link: dialog

See also: TextDialog()

OpenDialog(W, s1, s2, i) : s3 -- display dialog for opening file

OpenDialog() displays a dialog box allowing entry of a text string of up to i characters, normally a file name, along with Okay and Cancel buttons. s1 supplies a caption to be displayed in the dialog box. s2 is used as the initial value of the editable text string. The final text string value is stored in the global variable dialog_value. OpenDialog() returns the name of the button that was selected.

Defaults: s1   "Open:"
          s2   ""
          i    50

Link: dialog

See also: SaveDialog() and TextDialog()

PaletteChars(W, s1) : s2 -- return characters of color palette

PaletteChars() returns the string of characters that index the colors of palette s1.

Default: s1   "c1"

See also: PaletteColor(), PaletteGrays(), and PaletteKey()

PaletteColor(W, s1, s2) : s3 -- return color from palette

PaletteColor() returns the color indexed by character s2 in palette s1. The result is in the form produced by ColorValue().

Default: s1   "c1"

See also: ColorValue(), PaletteChars(), PaletteGrays(), and PaletteKey()

PaletteGrays(W, s1) : s2 -- return grayscale entries of palette

PaletteGrays() returns the string of characters that index the achromatic entries within palette s1, ordered from black to white.

Link: color

See also: PaletteChars(), PaletteColor(), and PaletteKey()

PaletteKey(W, s1, k) : s2 -- return character of closest color in palette

PaletteKey() returns the character indexing the color of palette s1 that is closest to the color k.

Default: s1   "c1"

See also: PaletteChars(), PaletteGrays(), and PaletteColor()

Pattern(W, s) : W -- set fill pattern

Pattern() sets a pattern to be used for drawing when the fill style is set to "masked" or "textured". s can be a known pattern name or a specification of the form "width,#data" where the data is given by hexadecimal digits. Pattern() fails in the case of a bad specification or unknown name.

See also: DrawImage()

Pending(W) : L -- produce event list

Pending() returns the list that holds the pending events of a window. If no events are pending, this list is empty.

See also: Enqueue() and Event()

Pixel(W, x, y, w, h) : k1, k2, ... , kn -- generate pixel values

Pixel() generates the colors of the pixels in the given rectangle, left to right, top to bottom.

Defaults: x, y   upper-left pixel
          w, h   to edge of window

Raise(W) : W -- raise window to top of window stack

Raise() sets a window to be "above" all other windows so that it is not obscured by any other window.

See also: Lower()

ReadImage(W, s1, x, y, s2) : i -- load image file

ReadImage() loads an image from file s1, placing its upper-left corner at x,y. If a palette s2 is supplied, the colors of the image are mapped to those of the palette. ReadImage() fails if it cannot read an image from file s1. It normally returns the null value, but if some colors cannot be allocated, it returns the number of colors that cannot be allocated.

Defaults: x, y   upper-left pixel

See also: DrawImage() and WriteImage()

RightString(W, x, y, s) : W -- draw right-justified string

RightString() draws a text string that is right-justified at position x and centered vertically about y.

Link: gpxop

See also: CenterString(), DrawString(), and LeftString()

SaveDialog(W, s1, s2, i) : s3 -- display dialog for saving file

SaveDialog() displays a dialog box allowing entry of a text string of up to i characters, normally a file name, along with Yes, No, and Cancel buttons. s1 supplies a caption to be displayed in the dialog box. s2 is used as the initial value of the editable text string. The final text string value is stored in the global variable dialog_value. SaveDialog() returns the name of the button that was selected.

Defaults: s1   "Save:"
          s2   ""
          i    50

Link: dialog

See also: OpenDialog() and TextDialog()

SelectDialog(W, L1, L2, s, L3, i) :
s

-- display selection dialog

SelectDialog() constructs and displays a dialog box and waits for the user to select a button. The box contains zero or more captions specified by the list L1, zero or more radio buttons specified by L2 and s, and one or more buttons specified by L3. i specifies the index of the default button, with a value of 0 specifying that there is no default button. Any of the list arguments Ln can be specified by a single non-null value which is then treated as a one-element list.

For the radio buttons, L2 specifies the button names and s specifies the name for the default button. If L2 is omitted, there are no buttons.

SelectDialog() returns the name of the button that was selected to dismiss the dialog. The global variable dialog_value is assigned the name of the selected radio button.

Defaults: L1   []
          L2   []
          L3   ["Okay", "Cancel"]
          i    1

Link: dialog

See also: TextDialog() and ToggleDialog()

Shade(W, k) : W -- set foreground for area filling

Shade() sets the foreground color to k on a color or grayscale display. On a bi-level display, it sets the fill style to textured and installs a dithering pattern that approximates the brightness of color k.

Link: color

See also: Fg()

TextDialog(W, L1, L2, L3, L4, L5, i)
: s

-- display text dialog

TextDialog() constructs and displays a dialog box and waits for the user to select a button. The box contains zero or more captions specified by the list L1, zero or more text-entry fields specified by L2, L3, and L4, and one or more buttons specified by L5. i specifies the index of the default button, with a value of 0 specifying that there is no default button. Any of the list arguments Ln can be specified by a single non-null value which is then treated as a one-element list.

For the text-entry fields, L2 specifies the labels, L3 specifies the default values, and L4 specifies the maximum widths. If L2, L3, and L4 are not the same length, the shorter lists are extended as necessary by duplicating the last element. If omitted entirely, the defaults are: no labels, no initial values, and a width of 10 (or more if necessary to hold a longer initial value).

TextDialog() returns the name of the button that was selected to dismiss the dialog. The global variable dialog_value is assigned a list containing the name of the text fields.

Defaults: L1   []
          L2   []
          L3   []
          L4   []
          L5   ["Okay", "Cancel"]
          i    1

Link: dialog

See also: Notice(), OpenDialog(), SaveDialog(), and SelectDialog()

TextWidth(W, s) : i -- return width of text string

TextWidth() returns the width of string s, in pixels, as drawn using the current font.

See also: DrawString()

ToggleDialog(W, L1, L2, L3, L4, i)
: L

-- display toggle dialog

ToggleDialog() constructs and displays a dialog box and waits for the user to select a button. The box contains zero or more captions specified by the list L1, zero or more toggle buttons specified by L2, zero or more toggle states (1 or null) specified by L3, and one or more buttons specified by L4. i specifies the index of the default button, with a value of 0 specifying that there is no default button. Any of the list arguments Ln can be specified by a single non-null value, which is then treated as a one-element list.

For the toggle buttons, L2 specifies the labels and L3 specifies the corresponding states. If L2 and L3 are not the same length, the shorter list is extended as necessary by duplicating the last element. If omitted entirely, the defaults are: no labels and null states.

ToggleDialog() returns the name of the button that was selected to dismiss the dialog. The global variable dialog_value is assigned a list containing the states of the toggle buttons.

Defaults: L1   []
          L2   []
          L3   []
          L4   ["Okay", "Cancel"]
          i    1

Link: dialog

See also: SelectDialog() and TextDialog()

Uncouple(W) : W -- uncouple window

Uncouple() frees the window W. If no other bindings to the same canvas exist, the window is closed.

See also: Clone(), Couple(), and WClose()

WAttrib(W, s1, s2, ... , sn) : a1, a2, ...
, an

-- set or query attributes

WAttrib() sets and generates window attribute values. Each string of the form name=value sets a value; a string with just a name is an inquiry. First, any requested values are set. Then WAttrib() generates the values of all referenced attributes. Each value has the data type appropriate to the attribute it represents. WAttrib() ignores unrecognized names and illegal values, producing no result; if all arguments are invalid, WAttrib() fails.

WClose(W) : W -- close window

WClose() closes a window. The window disappears from the screen, and all bindings of its canvas are rendered invalid. Closing the subject window sets &window to the null value.

Link: wopen

See also: Uncouple(), WFlush(), and WOpen()

WDefault(W, s1, s2) : s3 -- get default value from environment

WDefault() returns the value of option s2 for the program named s1 as registered with the graphics system. If no such value is available, or if the system provides no registry, WDefault() fails.

WDelay(W, i) : W -- flush window and delay

WDelay() flushes any pending output for window W and then delays for i milliseconds before returning.

Default: i 1

Link: wopen

See also: WFlush()

WDone(W) -- wait for "quit" event, then exit

WDone() waits until a q or Q is entered, then terminates program execution. It does not return.

Link: wopen

See also: WQuit()

WFlush(W) : W -- flush pending output to window

WFlush() forces the execution of any window commands that have been buffered internally and not yet executed.

See also: WClose(), WDelay(), and WSync()

WOpen(s1, s2, ... , sn) : W -- open and return window

WOpen() creates and returns a new window having the attributes specified by the argument list. Invalid arguments produce failure or error as in WAttrib(). If &window is null, the new window is assigned as the subject window.

Link: wopen

See also: WAttrib() and WClose()

WQuit(W) : W -- check for "quit" event

WQuit() consumes events until a q or Q is entered, at which point it returns. If the event queue is exhausted first, WQuit() fails.

Link: wopen

See also: WDone()

WRead(W) : s -- read line from window

WRead() accumulates characters typed in a window until a newline or return is entered, then returns the resulting string (without the newline or return). Backspace and delete characters may be used for editing. The typed characters are displayed in the window if the echo attribute is set.

Link: wopen

See also: Event() and WReads()

WReads(W, i) : s -- read characters from window

WReads() returns the next i characters typed in a window. Backspace and delete characters may be used for editing prior to entry of character i. The typed characters are displayed in the window if the echo attribute is set.

Default: i   1

Link: wopen

See also: Event() and WRead()

WriteImage(W, s, x, y, w, h) : W -- write image to file

WriteImage() writes an image of the rectangular area (x,y,w,h) to the file s. It fails if s cannot be written or if the specified area, after clipping by the window's edges, has a width or height of zero. The file is normally written in GIF format, but some forms of file names may select different formats on some graphics systems.

Defaults: x, y   upper-left pixel
          w, h   to edge of window

See also: ReadImage()

WSync(W) : W -- synchronize with server

WSync() synchronizes the program with the graphics server on a client-server graphics system, returning after all pending output has been processed. On systems that maintain synchronization at all times, WSync() has no effect.

See also: WFlush()

WWrite(W, s1, s2, , sn) : sn -- write line to window

WWrite() writes a string to a window at the text cursor position. The area behind the written text is set to the background color. Newline, return, tab, backspace, and delete characters reposition the cursor. A implicit newline is output following the last argument.

Link: wopen

See also: DrawString() and WWrites()

WWrites(W, s1, s2, , sn) : sn -- write partial line to window

WWrite() writes a string to a window at the text cursor position. The area behind the written text is set to the background color. Newline, return, tab, backspace, and delete characters reposition the cursor. Unlike


WWrite()

, no newline is added.

Link: wopen

See also: DrawString() and WWrite()

Back to Contents