Icon Graphics Facilities; Appendix H: Changes Since Version 8.10

Appendix H

Changes Since Version 8.10

Version 9.0 of Icon introduced major changes with respect to the previous Version 8.10. These changes improve the programming interface, reduce inconsistencies, add utility, and reduce the orientation towards a single underlying platform. Some changes, including function renaming, introduce incompatibilities. This is a one-time effort; no further major changes are planned.

For some changes, especially those affecting attribute names and values, both old and new forms function correctly. The general documentation notes only the new forms; this appendix notes cases where old forms are still implemented for compatibility. New programs, of course, should use the new methods. A further discussion of compatibility and conversion appears at the end of this appendix.

This appendix focuses on major changes visible to the programmer. New features are mentioned only briefly; see the rest of the document for more details. A large number of minor changes are not listed here. These include bug fixes, performance enhancements, and output quality improvements.

Terminology

Graphics facilities no longer are considered a special addition known as X-Icon but rather a standard part of Icon identified by the term graphics when a distinction is needed.

The word window now has fewer meanings, its main uses now being a data type in Icon or an area on a display monitor. The term window system has been replaced by graphics system in the Icon documentation. The two types of window attributes are now canvas attributes and graphics context attributes.

The Library

The Icon program library has been expanded greatly and now includes a large number of graphics procedures. Some of these procedures, such as the Dialog procedures, are documented as part of Icon's graphics repertoire. The distinction between built-in functions and library procedures is less important than before and most Icon graphics programs include link graphics, at least, to access the library. This implies, in turn, that the library must be built and available, and that the IPATH and LPATH environment variables must be set at translation time.

Function Names

All of the graphics functions have been renamed. In most cases, the renaming consists of removing the initial X. XAttrib(), XDefault(), XFlush(), and XSync() were renamed by replacing the X with a W (for window).

XBind() has been deleted; its capabilities are subsumed by Clone() and Couple() and by the "canvas=hidden" attribute for creating invisible windows. XUnbind() has been replaced by Uncouple().

Three other functions also were deleted. XClearArea() can be replaced directly by EraseArea() in most applications. The function of XWindowLabel() can be accomplished by setting the label attribute. The pointerx and pointery attributes provide the same information as the former XQueryPointer().

New functions have been added. DrawCircle() and FillCircle() draw or fill a circle or circular arc given the center and radius. DrawPolygon() has been added for symmetry with FillPolygon(). Alert() emits a beep or other signal to attract attention.

Windows as Files

New procedures WOpen(), WClose(), WRead(), WReads(), WWrite(), and WWrites() are similar to open(), close(), and so on. The W procedures, however, deal with graphics windows and use the subject window, &window, by default.

To present a more uniform interface, the documentation now uses these procedures for opening and using windows as files. However, window creation via open(name, "x") and other such direct file accesses are still supported.

A minor change in Version 9 is that open(name, "x") now fails if graphics operations are not configured. Previously, a run-time error occurred.

Measurement Changes

Uniform rules apply to the defaulting of x, y, w, and h for functions whose arguments specify rectangular areas: x and y default to the window's upper-left pixel, while w and h default to the value needed to reach the edge of the window. These defaults are changes in some cases.

Negative values of w and h now are allowed when specifying rectangles, with the effect of extending the rectangle left and/or upward from the starting point.

Angles are now measured in radians instead of 64ths of a degree and are measured in a clockwise instead of counterclockwise direction. This change, which affects DrawArc() and FillArc(), makes the graphics functions consistent with the trigonometric functions.

`WAttrib()` Changes

WAttrib() now fails if an attempt is made to assign an illegal value, or if an invalid attribute name is given. WOpen() and Clone() behave similarly.

WAttrib() now returns integer values (instead of string values) for numeric attributes such as width.

When clipping is disabled, WAttrib() now returns the null value for the clipping attributes clipx, clipy, clipw, and cliph.

Attribute Changes

The windowlabel attribute has been renamed label. The rows attribute has been renamed lines. The geometry attribute has been removed from the documentation in favor of the pos attribute and the new size attribute. For compatibility, rows, windowlabel, and geometry are still accepted.

Several attribute values have been renamed:


old                       newlinestyle=onoff           linestyle=dashed
linestyle=doubledash      linestyle=striped
fillstyle=stippled        fillstyle=masked
fillstyle=opaquestippled  fillstyle=textured
iconic=window             canvas=normal
iconic=icon               canvas=iconic

Again, the old names are still accepted. The iconic attribute has been removed from the documentation, and the previous function of iconic=root is no longer available.

The visual attribute, an X-Windows feature of dubious value, has been removed from the documentation. The more portable depth attribute remains available.

Color Specifications

Decimal and hexadecimal color components are now interpreted in a linear color space. This makes their values device-independent within the limits of Icon's ability to compensate for variations in graphics systems. A new gamma attribute controls the amount of this compensation.

In the color naming system, the adjective pale now means very light instead of light moderate.

ColorValue() can now be used to translate a color even if no window is open; however, system-dependent names may not be recognized in this case.

Font Specifications

There is a new, platform-independent font naming system. System-dependent font names are still allowed, but in the case of ambiguity the Icon interpretation takes precedence.

Pattern Specifications

A set of sixteen predefined pattern names has been added. Decimal pattern specifications have been removed from the documentation; hexadecimal values are preferred. With hexadecimal values, the width of a pattern is no longer limited to 32 pixels.

Images

A new DrawImage() function allows the construction and display of bit-mapped images without the use of external files.

ReadImage() and WriteImage() now use GIF as the default file format. ReadImage() accepts a new, additional argument to quantize an incoming image to a particular color palette. GIF images can also be used with the image and iconimage attributes.

Pixel() now produces string values (comma-separated integer r,g,b values) instead of packed integers. Pixel generation now produces row elements (instead of column elements) consecutively. The background color is now produced for pixel addresses outside the bounds of the window; before, those addresses were omitted.

CopyArea() now allows the omission of window arguments for copying within the subject window. If the source rectangle for CopyArea() extends beyond the window boundary, the outside area is treated as if filled with the background color.

Events and Synchronization

Event() now adjusts the mouse location by the values of the dx and dy attributes to make the keywords &x and &y properly reflect the location's effective address within the window.

The documentation no longer mentions the ability of Pending() to add values to the event queue. The preferred method is to use put(Pending(), a, x, y).

WSync() no longer has a second "discard" argument, which was nonportable and unreliable.

When a graphics program blocks awaiting input from a non-graphics terminal, such as standard input, buffered graphics output is first written to the screen. This eliminates the need for an explicit WFlush() call in such cases.

Keyboard Encodings

The library file xkeysyms.icn, which defines the event codes for special keys such as the Home key, has been renamed to keysyms.icn. Some incorrect values in this file have been fixed, and some symbolic names have changed, but the actual codes returned by Icon have not changed.

Users of the X Window System should read the section about keyboard event codes in Appendix I.

Conversion Assistance

The Icon program library contains files to aid in the transition to Version 9 . Many existing graphics programs can be run under Version 9 by adding the following two lines at the beginning:

   link xcompat
   $include "xnames.icn"

The environment variables IPATH and LPATH must be set correctly to access the library.

The xcompat package contains procedures XBind(), XUnbind(), XWindowLabel(), XDrawArc(), and XFillArc() that are compatible with Version 8.10. The file xnames.icn contains preprocessor directives that redefine old names as new names for cases not covered by xcompat.icn.

Ultimately, it is best to revise the source code permanently. For Unix systems, an ed script is provided to convert the names of graphics functions called from an Icon program. This script is in the Icon program library as gdata/xnames.ed.

Back to Contents