Conference hydra::amiga_v1

211.0. "Using Icons" by TLE::RMEYERS (Randy Meyers) Thu Dec 11 1986 10:28

In note 202.12, Paul Kyzivat asked some questions about how icon information
is passed to programs under the Workbench.  I thought that this was a topic
large enough to deserve its own note.

The documentation on how to write programs that get their arguments though
icons or manipulate .info files is Chapter 18, titled "Workbench," in the
"Rom Kernel Reference Manual: Libraries and Devices."  Of particular interest
is the example C program on page 497 that gets its arguments either from
a command line if started by the CLI or a Exec startup message if started
by the Workbench.

A C program gets information about its arguments either of two ways depending
on how the program was started.

If the program was started by the CLI, then it receives its arguments through
the normal argc and argv arguments to the main function just like Unix.  Argc
is the count of arguments and argv is a array of pointers to character strings.
Note that argc is always at least one if the program is started by the CLI
since according to the C language, every program has at least one argument--
the name of the program itself.

If the program was started by the workbench, then it receives its arguments
through argc and argv again, but with some differences.  Argc is set to zero
to indicate that an Exec message contains the true arguments to the program.
Argv is not an array of pointers to character strings, but a pointer to the
Exec message itself.  Inside the Exec message, is among other things, the
names of all the arguments to the program and locks for the arguments.

All of this is well enough documented that a programmer shouldn't have any
problems in using it.  The part that seems undocumented is the user's, not
the programmer's, interface.

Everyone knows that all the icons for "projects" under the Workbench have
a default "tool" associated with them.  The tool is the program to run to
process the project file when you double click on the icon for the project.
You can see, and change, the default tool associated with a project by
selecting the icon for the project, and then selecting "Info" from the
workbench menu.

Since the designers of Workbench called the tool name stored in the icon
the default tool, there is an implication that it is possible to use
other tools with the same project.  However, there doesn't seem to be any
documentation on how to do this.  You could always use the info menu option
to associate name of a new tool with a project, but that is fairly clumsy.

It turns out there is another way:  Remember extended selection described
on page 4-7 of "Introduction to Amiga"?  That is when you hold down the
shift key while selecting an icon.  The new icon is selected along with
any other icons that were selected previously (as opposed to normally
selecting an icon which has the side effect of unselecting any previously
selected icon.)  About the only use that I could find mentioned for extended
selection was using the snapshot menu item to save the positions of icons
on the screen.

However, it turns out that extended selection can be used to use a
different tool with a project.  If you use extended selection to select
both a project and a tool, and either select open from the workbench menu
or double click on either the tool or project icon while holding down
on the shift key, then the tool you selected, not the default tool will
be called on the project.  In fact, if a tool can process several projects,
you can select several project files and a tool to act on them.

Some of the rules about this that I have experimentally discovered:

The name of the tool being run is always the first argument in the Exec
startup message to the program (this is regardless of what order the
icons where selected in).  The other arguments appear in the order that
the icons were selected.

It is possible to have a tool that processes tools (for example, an
object file dumper that disassembles a program).  If you select two
or more tools at once, the first one selected is treated as the tool
to run.  The other tool is treated exactly as a project.  (There seems
to be a discrepancy between double clicking and using the open menu item
if two tools are selected at once.  Double clicking does not do anything;
you must use the open menu item.)

Also, there seems that there is an easy mistake to make when using
extended selection.  When starting to select a sequence of icons using
extended selection, do not hold down the sift key when selecting the
first icon.  Otherwise, you will not unselect any previously selected
icons.  When I was playing around with this, I noticed that getting
extra blank arguments (arguments with locks but no character string
associated with them).  It turned out that the disk icon for the
window I had just opened was still selected.  Disks, when used as
arguments, do not have a text string associated with them.  Just a
lock that can be used to access the disk directory.

The example program from the Rom Kernel Manual is a good way to play
around with extended selection to see how it works.