----------------- 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 . 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$;"-") 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.