textfiles/apple/DOCUMENTATION/tie

-----------------
   T he              12 Feb 88
   I con             Version 1.0
   E ditor           Copyright (c) 1988 by ACE Software
-----------------


General
-------

The Icon Editor (TIE) is used to edit existing Icon files for the Apple IIGS
Finder. The Finder uses these Icons to set certain files apart from other files
and to launch applications from document files.

The Finder can match files with Icons by any combination of three fields:
FileName, FileType, or AuxType. Finder keeps a list of "Icon Blocks" (one Icon
Block is contained in each Icon file) that have been read in when Finder was
started. The first file the Finder reads is FINDER.ICONS from the boot disk's
ICON folder. After that, Finder will read in any and all Icon files that it
finds in the ICON folders of any inserted disk. These other Icon Blocks are
inserted in front of the list in memory so that FINDER.ICONS is always the last
block in the list.

When Finder needs to match a file to an Icon, it starts with the first Icon in
the list. There can be either an exact match or a match by use of a wildcard. If
ALL THREE fields in the Icon match the file, the Icon is assigned to that file.
All three fields must match or Finder will try again with the next Icon in the
list. The last Icon in the list is the last Icon in FINDER.ICONS. This is the
generic document Icon and will ALWAYS match all three fields.


File Menu Display
---- ---- ------

The File Menu Display is used to select the Icon file that you desire to work
on. When the program is run, this is the first display that will be shown. In
the center area of the display, all of the Icon files and any "Folders" (DIR
files) are shown. At the top left of the display, the current disk device is
shown and at the bottom of the display, brief instructions for selecting a file
are shown.

To select a file, use the up and down arrows to move the cursor to the desired
file and press Return. If the current file is an Icon file, it will be opened
and all of its Icons will be read by the program (up to a maximum of 40 Icons).
If the current file is a Folder (DIR file), the prefix will be set to that
Folder and the contents will be displayed for further selection. If the Folder
contains no selectable files, the prefix will be set to the root directory and
its files will be displayed. If the root directory contains no selectable files,
the program will attempt to find a disk that contains either Icon files or
Folders.

To return to the root directory, press the space bar.

To switch disk devices, press C. TIE will search through the device chain for a
ProDOS disk that has selectable files on it. If no such disk is found, you will
be prompted to insert a ProDOS disk in a disk drive. TIE will NOT recognize the
Auxilliary 64K bank RAM disk.

To exit this display, press the Escape key. If no Icons have been read, TIE will
end. Otherwise, the Icon Menu Display will be shown.

Once an Icon file has been selected and read, the Icon Menu Display is shown.


Icon Menu Display
---- ---- -------

The Icon Menu Display is used to select an Icon for editing, delete an Icon, add
more Icons, or save all the Icons in memory to disk. The Icons in memory are
shown in the center of the display. At the bottom of the display, brief
instructions for this display, the total number of Icons in memory, and the
number of free bytes left for Icon image data are shown.

To edit an Icon, use the Up and Down arrow keys to move the cursor to the
desired Icon and press Return. You will then be asked which aspect of the Icon
you wish to edit. Typing F or S will show the Icon Edit Display and allow you to
edit either the Full-sized or Small version of the Icon. Typing E will allow you
to edit the Extended Parameters attached to the Icon.

To delete an Icon, move the cursor to the desired Icon and press D. If you
delete all of the Icons in memory, the File Menu Display will be shown and you
must select another file for editing or exit the program.

To add more Icons, press A. The File Menu Display will be shown and you may
either set the prefix (by selecting Folders), select an Icon file to add to
memory, or return to the Icon Menu Display. As said in the previous section, a
maximum of 40 Icons can be contained in memory at one time.

To save the Icons in memory to disk, press S. The current prefix will be shown
and you will be prompted for a FileName. The name of the Icon file last read is
the default. You may either use the prefix and type just the filename or you may
type the full pathname of the file you wish to save the Icons in. The Icon file
must be in a folder called ICONS in the root directory of the disk in order to
be recognized by Finder. It is recommended, although not required, that you
attach .ICONS to the end of the Icon file's name.

To exit the program press Escape.

When editing the Extended Parameters:

 o The Name field can be no longer than 15 letters, numbers, periods and
   asterisks. Use the asterisk as a wildcard character. If an asterisk is
   entered as the Name, it will match all FileNames.

 o The FileType field can either be entered as a decimal number or the code seen
   in the Icon Menu Display under "Typ" (i.e., 4 or TXT, 182 or $B6, etc.). ALL
   (or 0) may be entered in order to match all FileTypes, however, this field is
   the best way to match Icons to files and normally should not be set to All.
   The FileType field can also indicate that the Icon is a hardware device. If
   you wish to make an Icon represent a hardware device, enter one of the
   following codes instead of a normal FileType:

          265: 5.25" Drive
          266: RAM/ROM Disk
          267: 3.5" Disk
          268: 5.25" Disk
          269: Hard Drive
          270: Full Trash
          271: Empty Trash

 o The AuxType MUST be entered as a decimal number from 0 to 65535. If this
   number is zero, it will match all AuxTypes.

 o The Application field can be no longer than 63 characters and must be a FULL
   pathname. This field indicates to Finder what application to launch if this
   Icon (usually a document) is opened. It may be blank and should be so if this
   Icon represents an application.


Icon Edit Display
---- ---- -------

The Icon Edit Display is used to change the shape and colors of Icons. In the
black area of the display are two boxes containing aspects of the current Icon.
Inside each box are little blocks. Each block corresponds to a pixel in the
Icon. The color of each pixel can be selected by you to create the final image
and shape. In the text area of the display, the Icon number and aspect of the
Icon are displayed. Available commands and the current color are also shown
here.

Each aspect of the current Icon is normally bordered in grey, but if the Icon is
too big for TIE to display (more than 36 pixels wide or high) then either the
bottom or right sides (respectively) of the display boxes will be drawn in red.
If this condition does happen, you may still edit the part of the Icon that is
shown.

The left hand box contains the Icon Image and may be edited using 16 colors. The
right hand box contiains the Icon Mask associated with that Image and may only
be edited with two colors, black and white. Each white pixel in the Mask will
allow the corresponding pixel in the Image to be displayed in the Icon. When
editing the Mask, the current color has no effect.

NOTE: For the most part, the colors that TIE uses to display Icons correspond
      with the actual colors used on the Finder screen. However, some colors do
      not match what is seen in Finder.

To change a pixel, select a color by pressing the corresponding key shown below
each color at the bottom of the screen (Hexadecimal number: 0 - F). The name of
the current color will show up in inverse. Then move the cursor to the pixel you
wish to change with the arrow keys and press the space bar. If you make a
mistake, just press the space bar again and the pixel will be restored to its
original color.

To edit the Icon Mask, press the backslash key (\) and the cursor will switch
edit boxes. Now follow the instructions for changing a pixel, except that color
need not be selected (when a pixel is changed in the Icon mask, it is toggled
between black and white). Press backslash again to continue editing the Icon
image.

When your Icon is finished, press Escape or Return to exit the Icon Display.


          ------------------------------------------------------------

TIE Internals
--- ---------

TIE is written in AppleSoft BASIC and poor, old Dr. BASIC is really pushed to
his limits.

 o BASIC simply cannot handle the amount of raw data involved with storing Icons
   in memory, so I wrote my own variable storage routines (mostly in BASIC, but
   they do include a short ML subroutine) for the Icon image data.

 o The Icon Edit Display, if you will notice, is done on the Double Lo-Res
   Screen using a little known trick that Uncle-DOS (aka Tom Weishaar) reported
   in Open-Apple magazine on page 43 (June '85 issue). It was found in the //c
   ROM, but it seems that Apple used the same trick in the IIGS! It also seems
   that Apple didn't correct the bug that Uncle-DOS found! Maybe if we all bug
   Apple, they will fix it. If you don't know what I'm talking about, bug Tom
   Weishaar to "reprint" the article online! (Or maybe I will if he gives the
   go-ahead)

 o If you look carefully at the Initialization code in the beginning of the
   program, you will notice that the program relocates itself in order to make
   room for a File buffer and Icon storage. If you rename the program, you must
   also change the name used in the statement that relocates the program or else
   it WILL crash! (change the :::: PRINT D$;"-TIE" to
   :::: PRINT D$;"-<New.Name>")

         --------------------------------------------------------------

The Icon Editor is copyright (c) 1988 by ACE Software

This program is ShareWare and may be distributed freely as long as it is not
sold or separated from these docs.

If you find this program useful, send $5.00 to:

  Chris Budewig
  457 Harr Dr.  Apt G
  Midwest City, OK 73110