💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Graphics › Icons › TIE.V1.2 ›… captured on 2024-12-17 at 22:53:52.
-=-=-=-=-=-=-
-----------------
T he 10 March 88
I con Version 1.2
E ditor by Chris Budewig
-----------------
General
-------
The Icon Editor (TIE) is used to create and edit Icon files for the Apple IIGS
Finder (v1.0). Each file contains a number of Icon definitions which the Finder
uses to set certain files apart from others and to launch applications from
document files.
The Finder can match files with Icons by any combination of three fields: Name,
FileType, or AuxType. Finder keeps a list of Icon Blocks in memory which is
composed of the Icon files found in the ICONS folder (one Icon Block is
contained in each Icon file). The first file the Finder reads is FINDER.ICONS
from the boot disk's ICON folder. After that, Finder will read in any other Icon
files that it finds in the ICON folders of any inserted disks. 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 being the
generic document Icon, it ALWAYS matches all three fields.
File Menu Display
---- ---- -------
The File Menu Display is used to select the Icon file that you desire to work
with. When the program is run, this is the first display that will be shown. In
the center area of the display, all Icon files and directories contained in the
current prefix are shown. At the top left of the display, the current disk
device is shown and at the bottom, brief instructions for loading Icons.
To select a file, use the up and down arrows to move the cursor to the desired
file and press Return. If this file is an Icon file, all of its Icons will be
read by the program (up to a maximum of 99 Icons). If it is a directory, the
prefix will be set to that directory and the contents will be displayed for
further selection. If the new directory contains no selectable files, the prefix
will be set to the root directory and its files will be displayed. If the root
directory of a volume contains no selectable files, the program will attempt to
find a disk that contains either Icon files or directories. If no such disk is
found, you will be prompted to insert a ProDOS disk in a disk drive.
To create an Icon from scratch, press S. TIE will then show that it is
processing the new Icon.
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. TIE will NOT recognize the
Auxilliary 64K bank RAM disk and will give an error if it is RUN when the prefix
is set to it.
To exit this display, press the Escape key. If there are no Icons in memory, TIE
will end. Otherwise, the Icon Menu Display will be shown.
Once a new Icon has been created or an Icon file has been loaded, the Icon Menu
Display is shown.
Icon Menu Display
---- ---- -------
The Icon Menu Display is used to select an Icon for editing, delete an Icon, and
add to or save Icons in memory. Icons 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 show the
Extended Edit Display and 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 create another Icon, 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 directories), create an Icon from scratch,
select an Icon file to add to memory, or return to the Icon Menu Display. As
said in the previous section, a maximum of 99 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 accessed
is the default (or UNTITLED.ICONS if no Icon file has been accessed accessed).
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. If the file already
exists, TIE will ask before overwriting it. The Icon file must be in a folder
called ICONS in the root directory 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. If you change your mind and no longer desire to save, enter a
null pathname (a single slash - /).
Pressing Escape from this display will exit the program.
Icon Edit Display
---- ---- -------
The Icon Edit Display is used to change the shape and colors of Icons. In the
top section of the display are two boxes containing aspects of the current Icon.
Inside each box are small blocks, each of which 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 version 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 high or wide) then either the
bottom or right sides (respectively) of the display boxes will be drawn in red.
This condition is for information only and you may still edit the visible
portion of the Icon.
The left hand box contains the Icon Image and may be edited using 16 colors. The
right hand box contains 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 Image pixel to be displayed when the Icon is drawn. The
current color has no effect when editing the Mask.
NOTE: The colors that TIE uses to display Icons roughly correspond to the actual
colors used on the Finder screen. However, most colors are not EXACT
matches and some do not resemble what is seen in Finder at all.
To change pixels, 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 select a color, press the corresponding key shown below the color name at the
bottom of the screen (Hexadecimal number: 0 - F). The name of the current color
will show up in inverse. The current color can also be "picked up" from under
the cursor by pressing <Open-Apple><Space>.
To edit the Icon Mask, either press the backslash key (\) to move the cursor to
the corresponding pixel in the Mask edit box or move the cursor off either side
of the Image edit box to move the cursor to the other side of the Mask. 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 or move the cursor off either side to continue
editing the Icon image.
When your Icon is finished, press Escape or Return to exit the Icon Display.
Extended Edit Display
-------- ---- -------
The Extended Parameter Edit Display is used to edit an Icon's Extended
Parameters as follows:
1) The Name field can be no longer than 15 letters, numbers, periods and
asterisks. Use the asterisk as a wildcard character. If a single asterisk is
entered as the Name, it will match all Names.
2) 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
3) The AuxType may be entered as a decimal number from 0 to 65535 or as a
hexadecimal number from $0000 to $FFFF. If this number is zero, it will
match all AuxTypes. Hexadecimal numbers must be preceded by a dollar sign
($) and only the first four character positions after the dollar sign are
recognized.
4) 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 or hardware Icon. To make the
Application field blank, enter a null pathname (a single slash - /).
5) The Height is the height of the Full-sized Icon Image and TIE will accept
values in the range of 4 to 44. The suggested range is from 10 to 30 with
the average being 16. Values outside this suggested range could make the
Icon look out of place.
6) The Width is the width of the Small Icon Image and TIE will only accept EVEN
values from 4 to 44. The suggested range is from 10 to 30 with the average
being 16. Values outside this suggested range could make the Icon look out
of place.
Creating Icons
-------- -----
To create an Icon, you must first have an idea of what you want it to look like
and whether it is to be an application or document Icon. Drawing the shapes on
graph paper can really help. You'll need two shapes for each Icon, one for when
it's viewed Full-size (any size you'd like, average of about 16 x 16, viewable
maximum of 36 x 36 in TIE) and one when it's viewed as Small (8 x 8).
Once you have decided on the appearance of the Icon, follow these steps:
o Run The Icon Editor by typing RUN TIE from the BASIC prompt or by
double-clicking on the TIE Icon from Finder.
o (A)dd an Icon from (S)cratch.
o Select the new Icon and edit the Extended Parameters. Change the parameters
for your Icon as described in the previous section.
o Edit the Full-size Image (by following the procedures in the Icon Edit
Display section) and turn on the pixels that you want to be seen by making
the corresponding pixels in the Mask white. Do the same for the Small Image.
o Now that the Icon is complete, (S)ave it to disk.
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 for the Icon image
data and have used almost the entire auxilliary bank of RAM (bank 01) for
Icon storage. The Auxilliary Bank RAM Disk is not disabled during this
process and any further accesses to it after loading Icons will produce I/O
Errors. Needless to say, any data currently on this RAM Disk will be lost.
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. 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>")
Icon File Structure
---- ---- ---------
The following is what I have found out about the structure of Icon files. Most
of the information was gained from S.LEPISTO (thanks Stephen) or by examining
Icon files myself. If you are not concerned about writing your own Icon editor
or using Icons in your programs, then you may skip this section of the
documentation.
Icons are defined in a structure known as an Icon Block. This is the equivalent
of an Icon file as far as you and I are concerned. Each file contains a header
that Finder uses to store such information as where this block came from and
where (in memory) the next one is. Obviously, the space in this header is only
used by Finder when the block of Icons is loaded into memory and can, except for
the version word, be ignored.
Following this header, are all of the Icon Data records, one per Icon. These
Data records are stored one after the other with no space inbetween. Each one of
these Icon Data records also has a header which includes the length of the
record, its owning application, name, filetype, and auxilliary type.
Following each Icon Data header are two Icon image records, one for the normal
size Icon and one for the small size Icon. Each image record includes a set of,
as yet, unused flags (I think; they're all set to zero), the number of bytes in
the image, the height and width of the image, and the image buffer. The image
buffer contains the image itself and the mask for the image.
All numbers shown below are in Hexadecimal.
All word values are stored in Hi/Lo format.
byte description
---- -----------
Icon Block Header:
00 - 03 Handle (in memory) of next Icon Block.
04 - 05 Version of this type of Icon Block. It is currently set to 0001.
06 - 09 Handle of pathname that the Block came from.
0A - 19 Filename that the Block came from prefixed by a length byte.
1A - A list of Icon Data records.
Icon Data Record:
00 - 01 Length of this Icon Data record. A zero here terminates the list.
02 - 41 Name of the owning application prefixed by a length byte. See Note 1.
42 - 51 Name of the file associated with this Icon prefixed by a length byte.
See Note 1
52 - 53 FileType associated with this Icon. Includes the Hardware Flag.
53 Hardware Flag. When this flag is clear (00) the FileType is used to
match a ProDOS FileType. If this flag is set (FF) then the FileType
translates as follows:
F9: 5.25" Drive
FA: RAM/ROM Disk
FB: 3.5" Disk
FC: 5.25" Disk
FD: Hard Drive
FE: Full Trash
FF: Empty Trash
If the Hardware Flag is set, TIE will add 10 (decimal 16) to the
lower byte of this word (the FileType), and use the resulting value
while in memory. So to tell TIE that an Icon is to represent a 3.5"
disk, enter a 010B (decimal 267) instead of an FFFB (decimal 65531).
54 - 55 AuxType associated with this Icon.
56 - Normal size Icon Image record.
Small size Icon Image record.
Icon Image Record:
00 - 01 Flags. Currently all set to zero.
02 - 03 Number of bytes (each) in Icon image and mask.
04 - 05 Height of Icon image (and mask) in pixels.
06 - 07 Width of Icon image (and mask) in pixels (4 bits per pixel). This
must always be an even number.
08 - Icon image data. Defines the appearance of the Icon. See Note 2
Icon mask data. Defines the shape of the Icon. See Note 2
Note 1: These fields may contain uppercase letters, numbers, and periods
combined in such a way as to make an acceptable ProDOS 16 Path or File
Name (respectively). The application field may contain slashes. These
fields may also use the asterisk as a wildcard character.
o If it is used at the beginning of the Application Path, it stands
for the boot volume (the asterisk, as well as the numbers 1 through
7, are used as prefixes before the initial slash in a ProDOS 16
pathname).
o If used in the FileName, it will match any set of characters. For
example, if the Icon is to match all files with a FileName ending in
".DOC", this field would contain "*.DOC". To match those files
beginning with "TIE", the FileName would be set to "TIE*".
Note 2: Each version of an Icon (Full-sized and Small) contains two parts - An
Image portion and a Mask portion. If a pixel in the Mask is white (set
to F) then the corresponding pixel in the Image will appear when the
Icon is drawn. If it is black (set to 0) the corresponding pixel will
not appear when the Icon is drawn. These pixels are stored here row by
row from top to bottom starting from the leftmost pixel, two pixels per
byte.
--------------------------------------------------------------
Version 1.1 Changes
------- --- -------
I have gone through the routines in this program and compressed most of what I
could. This left enough space to add the routine that allows you to change the
size of an Icon on the fly, the ability to "pick up" a color from off of the
screen, and a few cosmetic changes. I also speeded up the Save and Display Icon
routines. During this process, a couple of bugs were fixed and a few others
created. All of these bugs have now been fixed, but I'm sure someone will find
another one! If (or when) someone does, PLEASE let me know so that I can fix it
and reupload.
Version 1.1.1 Changes
------- ----- -------
This version fixes a small bug that occurs when setting the size of an Icon to
larger than 43 x 42. I "fixed" it by limiting the range to 42 x 42. Other bugs
having to do with Icons in memory being trashed when saving or deleting Icons
have been fixed.
Version 1.2 Changes
------- --- -------
Version 1.2 has the ability to create an Icon from scratch. The maximum number
of Icons in memory has been increased to 99. The maximum dimensions that an Icon
can be changed to have been set back to 44 x 44. The AuxType of an Icon may now
be entered in Hexadecimal by preceeding the number with a dollar sign ($).
Be watching for the next version of TIE - as of this date, I have received my
development package (APW, APW C, ToolBox References), so it should be coming
soon! Version 2.0 WILL be written in C and use the full ToolBox interface
(windows, menus and the like).
--------------------------------------------------------------
The Icon Editor is copyright (c) 1988 by Chris Budewig.
This program is ShareWare and may be distributed freely as long as it is not
sold or separated from this doc file.
If you find this program useful, send $5.00 to:
Chris Budewig
457 Harr Dr. Apt G
Midwest City, OK 73110
If you are wavering on the edge of sending the ShareWare fee, do it now! When
TIE v2.0 comes out (SHR, Windows, etc.) it will jump up to $10.00! However,
those who have already sent in their fee will not be obligated to send the extra
$5.00 for the new version.
Support for TIE is on GEnie and if you have any problems or find inaccuracies in
the documentation, PLEASE send EMail to my GEnie address: K.FLYNN
--------------------------------------------------------------
End of TIE Documentation.