 |
Icon Project Document IPD271a http://www.cs.utsa.edu/research/icon/ipd271.htm Division of Computer Science The University of Texas at San Antonio San Antonio, TX 78249 |
Clinton L. Jeffery
February 13, 1998
Technical Report CS-97-9
Abstract
|
Icon Project Document IPD271a http://www.cs.utsa.edu/research/icon/ipd271.htm Division of Computer Science The University of Texas at San Antonio San Antonio, TX 78249 |
The basic reference for Version 9 of Icon is the third edition of the book
The Icon Programming Language [1]. This book is available from the Icon
Project at The University of Arizona and in better bookstores. The graphics
facilities are detailed in a separate report [2].
Windows Icon and the Wi environment are products of Clinton Jeffery of the
University of Texas at San Antonio. Send requests, and bug reports to
jeffery@cs.utsa.edu. General Icon language questions can be
sent to icon-group@cs.arizona.edu.
a:\setup.exe to install Windows Icon
from drive a:. You may substitute a different
drive letter and directory name if your source files are located elsewhere.
For example, on a CD-ROM distribution you might run
d:\mswin\setup.exe.
During installation, you will be asked for a drive and directory into which
the Icon files will be installed, which defaults to
C:\WINICON. Files will be installed into several
subdirectories of the location you specify.
Installation also results in the creation
of a Windows Icon program group with a set of icons that allow you read
on-line documentation, uninstall the software, and launch Windows Icon. The
collection of Windows Icon icons will look something like this:
Complete installation also requires setting some environment variables,
such as IPATH and LPATH, to indicate the location of the Icon Program
Library directories. This is done differently on different versions of
Windows. See Section 5.3 below for details.
To install Icon on Windows 3.1 or Windows for Workgroups, you must also
install OS support for the Microsoft Win32 API, provided by a package from
Microsoft called "Win32s". Many people already have Win32s as a result of
installing other 32-bit binaries. If you do not have a version of Win32s
installed, you can obtain one from Microsoft or by FTP to ringer.cs.utsa.edu
in directory /pub/icon/nt/win32s. Copy all the files there onto a floppy
disk, insert the disk in your Windows 3.1 machine, launch Windows, and run
a:setup.exe (or b:setup.exe if the floppy is in your b: drive). Follow the
setup program's instructions.
Within the directory that Icon was installed, the most important subdirectory
is the bin directory, which contains the Icon system binaries.
Two executable binary files are required to use Icon, the executor and the
compiler that produces virtual machine code files for the executor. The
executor and compiler are normally invoked by the integrated
development environment called Wi (pronounced "Wye" or sometimes
"why?"), an editor/project builder that provides a visual
interface to the program development process. Applications that provide a
graphical interface are usually constructed by means of a visual interface
builder called VIB, a drawing program that generates Icon code for a program's
interface. The following table summarizes the contents of the bin
directory:
bin directory, normally C:\WINICON\BIN
should be added to your PATH specification. The
names start with an initial w- (or nt-) that distinguishes them
from Icon for MS-DOS.The distribution is contained in several files a compressed archive format. Files are uncompressed and extracted automatically by the installation program.
The distribution files are organized for distribution on four 1.44MB diskettes. They may also be installed from a single combined directory on a hard disk or CD-ROM.
You can easily select an existing Icon source file, or name a new one.
If you click "Open" without choosing a name, you will be given the default
name of "noname.icn". Icon source files generally must use the extension
.icn and should be plain text files without line numbers or
other extraneous information. Editing your program occurs within the main
Wi window, which might look like this:
The top area shows program source code, while the bottom portion shows messages such as compiler errors. You can change the font and the number of lines used to show messages from the Edit menu.
When you are done editing your program, you can save it, compile it, or just "make" (save, compile and link an executable) and run your program with menu options. The Arguments command in the Run... menu let's you specify any command-line arguments the program should be given when it is executed.
Run-time errors also result in a message for which the source line is
highlighted. The message for a run-time error includes Icon's standard
traceback of procedures from main() to the procedure in which
the error occurred. When the error messages get long, you can either
increase the number of lines for the message window (as was done here) or
scroll through the message window's entire text using the scrollbar.
.icn source file, Wi switches the editor and compile and
link commands to work on a different program.
Project files are plain text files with extension .icp. They
list source files, one file per line. When you open a project file, Wi goes
into "project mode", and adds the source files in the project to your File
menu, allowing you to switch easily between files in the project. If you
subsequently open a source file not in the project, Wi asks if you want to
add that source file to the project, or switch out of project mode and edit
that file as a separate program. In general, project files allow you to
"make" large projects efficiently. Underneath the covers, Wi invokes the
other Icon program executables to do the work of compiling and running
programs, described below.
When Wi "makes" a program executable, it recompiles those modules listed in
the project file whose modified time is newer than their corresponding
object files. On the other hand, Wi knows nothing about link declarations
embedded in source files, and recompilation will not be triggered by such
dependencies. When you use Wi, you should generally use link statements for
library files (such as Icon Program Library modules), and use
.icp files for your own sources. Files listed in the .icp file
must not also be referenced in a link statement; linking the same module
twice causes link errors. For projects, the executable .bat
that is produced by "make" is named after the first program in the project
file.
The font in the edit window can be picked from the Font... command in the Edit menu. The number of lines to use for messages can be picked with the Message window... menu item in the Edit menu.
The font and message line options, as well as a default window width and
height, may be specified in a file called WI.INI
that Wi reads when it starts up. The file WI.INI
from the current directory is used, unless a WICONINI environment
variable is set, in which case it is taken to be the pathname of
the initialization file that Wi is to use. An example WI.INI
file is the following:
width=800 height=800 font=times,28 msglines=3
nticont prog.icn
Command line execution does not work under Windows 3.1, whose MS-DOS prompts
cannot invoke 32-bit Windows binaries. If command line execution is desired,
such machines should use MS-DOS/386 Icon instead.
Windows Icon also includes a compiler (wicont) and virtual-machine interpreter (wiconx) that do support graphics facilities and do run on Windows 3.1; while these tools can be invoked from the command-line under Windows95 and NT, they are usually invoked by Wi. The instructions below refer to nticont and nticonx, but generally would also be true for wicont and wiconx. The Windows icode files that result of compilation have the extension .bat, for example, the above compilation would produce a file prog.bat. Under Windows NT or Windows95 this file can be run by
prog
Alternatively, nticont can be instructed to execute the icode file after
translation by appending a -x to the command line, as in
nticont prog.icn -x
If nticont is run with the -x option, the file prog.bat is left and can be
run subsequently using an explicitly named executor as described above.The extension .icn is optional on the command line. For example, it is sufficient to use
nticont prog
nticont hello
hello
Note that this can be done in one step with
nticont hello -x
nticont roman -x
and provide some Arabic numbers from your console.
If these tests work, your installation is probably correct and you should have a running version of Windows Icon.
prog text.dat log.dat
runs the icode file prog.bat, passing its main procedure a list of two
strings, "text.dat" and "log.dat". The program also can be translated and
run with these arguments with a single command line by putting the arguments
after the -x:
nticont prog -x text.dat log.dat
These arguments might be the names of files. For example, the main procedure
might begin as follows:
procedure main(args)
in := open(args[1]) | stop("cannot open file")
out := open(args[2], "w") | stop("cannot open file")
.
.
.
wicont prog1 prog2
translates the files prog1.icn and prog2.icn and produces one icode file,
prog1.exe. In addition to supplying files on the command line, files may be
linked or included using appropriate commands in the source file.A name other than the default one for the icode file produced by wicont can be specified by using the -o option, followed by the desired name. For example,
wicont -o probe prog
produces the icode file named probe.bat rather than prog.bat. If the -c option is given to wicont, the translator stops before producing an icode file and intermediate ``ucode'' files with the extensions left for future use (normally they are deleted). For example,
wicont -c prog1
leaves prog1.u1 and prog1.u2, instead of producing prog1.bat. These ucode
files can be used in a subsequent wicont command by using the .u1 name. This
saves translation time subsequently. For example,
wicont prog2 prog1.u1
translates prog2.icn and combines the result with the ucode files from a
previous translation of prog1.icn. Note that only the .u1 name is given; the
.u2 name is implied. The extension can be abbreviated to .u, as in
wicont prog2 prog1.u
Ucode files also can be added to a program using the link declaration.The informative messages from the translator can be suppressed by using the -s option. Normally, both informative messages and error messages are sent to standard error output.
The -t option causes &trace to have an initial value of -1 when the icode file is executed. Normally, &trace has an initial value of 0.
The option -u causes warning messages to be issued for undeclared identifiers in the program.
Environment variables are particularly useful in adjusting Icon's storage requirements. Particular care should be taken when changing default values: unreasonable values may cause Icon to malfunction.
The following environment variables can be set to adjust Icon's execution parameters. Their default values are listed in parentheses after the environment variable name:
set ICONFONT=Lucida Sans Typewriter
A:\ICON\TEST.ICN
A:/ICON/TEST.ICN
The goal of the native facilities is not to provide the entire Windows repertoire, any more than the entire X Window repertoire is provided to UNIX users. Instead, features have been chosen that are (1) important to the Windows look and feel, (2) general enough to be implementable on other platforms, and (3) can co-exist or be integrated with existing IPL facilities.
WinMenuBar(W, ["&File", "&Open", "&Save", "E&xit"], ["&Edit", "C&ut", "&Paste", "C&opy"], ["&Help", "&About"])This function converts approximately the top text line of the window into a menu bar. The appearance of the above example is given in Figure 6. When menu items are selected, they are produced as entire strings (such as
"&Open") by Event().
WinScrollBar(W, "sb_1", x, y, wd, ht)This function places a scrollbar with a particular size and position, which default to a standard size on the right edge of the window. The appearance of a typical scroll bar is illustrated in Figure 7. When scroll bar activity takes place, the scroll bar's string id is produced (in this case,
"sb_1") by Event(), and
&x and &y are both set to the scroll bar's
position.
WinButton(W, "hello", x, y, wd, ht)This function places a button with a particular size and position. The size defaults to a standard size large enough display the button's label. The appearance of a pair of buttons is illustrated in Figure 8. When a button is pressed, the button's string label is produced (in this case,
"hello") by Event().
| Defaults: | wd | width of text in system font + 10 pixels |
| ht | height of text in system font * 7/4 |
system("cmd /C /Q " || command)
 |
 |
 |
 |
 |
Clinton Jeffery
Division of Computer Science
The University of Texas at San Antonio
San Antonio, TX 78249
U.S.A.
(210) 691-5557 (voice)
(210) 691-4437 (fax)
jeffery@cs.utsa.edu
In order to minimize response times, the preferred method for reporting
problems is by e-mail. I would also like to hear suggestions and success
stories from satisfied users; e-mail is great but letters and postcards are
even better for this kind of feedback. Think of TROUBLE.TXT as a
"registration" for your free software.
Ralph Griswold and Gregg Townsend collaborated with the author in the development of Version 9.3. Bob Goldberg and Steve Schiavo wrote prototype program launchers that inspired the Wi integrated development environment.
This work was made possible in part by a software donation from Microsoft, a hardware donation from Icon Project, and a UTSA faculty research award. The author is supported by National Science Foundation award CCR-9409082.
2. Gregg M. Townsend, Ralph E. Griswold, and Clinton L. Jeffery, Graphics Facilities for the Icon Programming Language Version 9.3, The Univ. of Arizona Icon Project Document IPD281, 1996.