IconEd 1.3 Copyright (c) 1988, Paul Elseth Documentation version 11/23/88 (4th draft) IconEd is a shareware program for creating and editing Apple IIGS icons. With IconEd, you can change the appearance of icons, change the names of their files, and tell the Finder where to find the application that created a particular document file. You can also add icons to and remove icons from existing icon files, as well as copy icons between files. In short, IconEd is a complete icon maintenance utility. -------------------- Please note that IconEd is _shareware_, not public domain. You are welcome and encouraged to give copies away to anyone and everyone. If after using IconEd for a trial period you find is useful, you should send in the shareware fee of $15 (see below). If you do not want to pay the shareware fee, you should stop using IconEd. -- Any commercial distribution of IconEd is expressly forbidden without -- prior written permission from the author. I plan frequent and substantial improvements (and bug fixes), so registering would definately be to your advantage. Here is the shareware deal: When you send your $15, I will send you back a 3.5" disk with the latest version of IconEd, plus the next update free. After you register your copy of IconEd with me, you may use any future updates free. Updates ordered directly from me will cost five dollars or three dollars plus a blank disk. Send your $15 to: Paul Elseth 2739 Fairview Ct SE Rochester, MN 55901 CompuServe: 73457,226 BIX: pelseth ALPE: PElseth NOTE: Apple IIGS, GS/OS and Finder are trademarks of Apple Computer, Inc. -------------------- MENU REFERENCE -------------- APPLE Menu About IconEd... gives the version number and brief shareware information about this copy if IconEd. FILE Menu New Use New to create a new file of icons. A new icon window will appear, titled "Untitled.0n", without any icons in it. You may copy icons from other icon windows, or create new icons from scratch. Open Use Open to load an existing icon file from disk. Icon files are usually stored in the folder called ICONS in the main directory of a disk. There must be a file called FINDER.ICONS in the ICONS folder on the boot disk. In addition, any disk can contain a folder called ICONS containing additional icons (see ICONS AND THE FINDER below). IconEd can handle any number of icon files open simultaneously. Close Close closes the front window. If the front window is an icon file window and changes have been made to that file, you will be asked if you want to save the changes (just like selecting Save from the FILE menu). Save Saves the front icon file using it's current name. If you originally loaded this file from disk, it will be saved in the file it was loaded from. If this is a new icon file, you will be given a chance to indicate where you want the file save (just like using Save as... from the FILE menu). If you've moved the icons in the window, the new positions are not saved with the file, however, the current order of the icons _is_ saved. Save as... Similar to Save, but allows you to change the files name, and select where to save the file. If you want to Finder to use the icons in the current file, save it in the ICONS folder on the boot disk (or in the ICONS folder on another disk). Save as source... Saves the front icon file as an APW ASM65816 source file. This option can be used to generate source code for icons to be included in a pro- gram. Quit Use quit to leave IconEd. If you have any changed icon windows open on the desktop, you will be asked if you want to save them before quitting. EDIT Menu Undo Undo will cancel the last change editing change made in the Fat Pixels window. Cut Cut will copy the first selected icon in the front window to the clipboard and remove the icon from the window. Cut will allow icon images to be "exported" into any program that supports the graphic clipboard. Copy Copy copies the first selected icon in the front window to the clipboard without removing it from the window. Copy will allow icon images to be "exported" into any program that supports the graphic clipboard. Paste Paste will copy a previously cut or copied icon from the clipboard to the front icon window. Paste also allows graphics to be "imported" from any program that properly supports the graphical clipboard, such as Deluxe Paint II. Note that icons in IconEd use 640 mode (with dithered colors). If you copy an icon from a program in 320 mode, you may end up with an icon of only the left have of what you intended. If this happens, either convert the original to 640 mode, or cut a section twice as wide as the intended icon. I am looking into this, and will hopefully come up with a better solution soon. Clear Clear removes the first selected icon without copying it to the clipboard. Revert Similar to Undo, but more extreme. Revert changes the icon being editing in Fat Pixels back to it's original form. SPECIAL Menu Cleanup Cleanup repositions the icons in the front window in the current order (which can be changed by dragging the icons in the window - see REORDERING ICONS below). Select all Select all selects all of the icons in the front icon window. Add new icon Use Add new icon to create a new icon in the front icon window. Add new icon creates a generic document icon which can be edited to your liking. Fat pixels Use Fat Pixels to edit the first selected icon in the front icon window. This option will bring up the Fat Pixels window which allows you to change the appearance of the icon. Edit attributes... Edit attributes allows you to change the filename, file type, aux type, and application pathname associated with the currently selected icon. Colored mask The colored mask option allows color in the icon mask. This provides for "special effects" when the icon is selected. Experiment. Copy icon to mask Copies all the pixels in the icon image to the icon mask in the Fat Pixels window. All colors except white are copied as black. Copy mask to icon Copies all the pixels in the icon mask to the icon image in the Fat Pixels window. Fill image Fills the icon image in the Fat Pixels window with the currently selected color. Fill mask Sets the icon mask in the Fat Pixels window to all black pixels. (If Colored mask option is selected, Fill mask will set the icon mask to the current color.) Clear mask Clears the icon mask in the Fat Pixels window to all white pixels. (If Colored mask option is selected, Clear mask will clear the icon mask to all black pixels.) VIEW Menu by icon Displays all of the icons in the front icon window in their large icon form. If the Fat Pixels window is currently in front, displays the large icon for editing. by small icon Displays all of the icons in the front icon window in their small icon form. If the Fat Pixels window is currently in front, displays the small icon for editing. by name Displays the filename associated with each icon beneath the icons in the icon windows. by application Displays the application pathname associated with each icon beneath the icons in the icon windows. COLORS Menu The colors menu allows you to select the current color for editing icons in the Fat Pixels window. This menu is only active when the Fat Pixels window is in front. For convenience in selecting colors, the Colors menu can be "torn-off", and placed anywhere on the screen. To tear off the Colors menu, pull it down, and hold the mouse button down while dragging the mouse off the menu proper. An outline of the menu will follow the cursor around the screen - just like moving a window. When the mouse button is released, the Colors menu will be placed at the current point on the screen. The torn-off Colors menu can be moved or closed just like a window. The torn-off menu is only active when the Fat Pixels window is current (the menu's title bar will be gray, instead of white). ICON FILE WINDOW REFERENCE -------------------------- Icons may be selected by clicking on them with the mouse. Icons turn black to show that they are currently selected. A group of icons may also be selected together. To select a group of icons, press the mouse button and drag. A gray rectangle outline will stretch out with the mouse. Any icons within the rectangle will be selected. Icons may be reordered by dragging them in the window. Although the new order will be maintained, the exact new location is _not_ saved with the icon file. If an icon or group of icons is dragged into another icon window, those icons are copied to that file. Double-clicking on an icon allows you to edit that icon in the Fat Pixels window. FAT PIXELS REFERENCE -------------------- The Fat Pixels window is used to change the appearance of an icon. Each pixel in the icon is "blown-up" to four times it's normal size in the Fat Pixels window. An icon is made up of two parts: the icon image, and the icon mask. The icon's image defines the colors of the icon, while the mask generally defines it's shape. When the Finder draws an icon on the screen, the image is "masked" against the icon mask. Every black pixel in the mask allows the corresponding image pixel to be displayed, while the white pixels in the mask allow the background to show through. The icon image may be editing using all sixteen colors, while the mask normally may only be black and white. If the Colored mask option is selected, masks may also consist of all sixteen colors. With colored masks, white pixels allow the corresponding image pixel to be displayed, while black mask pixels allow the background to show through. This is the reverse of when Colored mask is off. The purpose of colored masks is to allow a selected or "open" icon to be colored also. Experiment with colored masks, and watch the sample icons to see what happens. Note that to prevent confusion, you should generally not switch Colored mask mode between on and off repeatedly during an edit session. To the right of the icon mask is the actual icon as it would appear in the Finder, shown normal, selected, and open - on both on white and colored backgrounds. Beneath the icon image is shown the current height and width of the icon. On the lower-right corner of the icon image is a small square - the icon "grow box". Dragging the grow box will change the size of the icon, similar to the grow box on a regular window. If an icon is intended to be used with the Finder, the large icon should be around 16x16 pixels. The small icon cannot be resized - it is always 8x8 pixels. Colors for editing the icon image can be selected from the Colors menu. For convenience, the colors menu can be "torn-off" and placed near the Fat Pixels window. A color can also be "picked-up" from a color in the image by holding the "apple" key while clicking on a pixel. If you change a pixel by mistake, clicking on it a second time will change the pixel color back. Clicking on a pixel in the icon mask simply toggles the color of the clicked- on pixel. You cannot "pick" colors from the icon mask unless Colored mask is on. If Colored mask is ON, the mask pixels work just like the image pixels. At the top of the Fat Pixels window (in the "Infobar"), IconEd displays the location (offset) of the pixel under the cursor in either the image or the mask. This will make it easier to align parts of the mask to the correspon- ding parts of the image. The icon being edited can also be "shifted". Holding down the shift key while the cursor is in the image area changes the cursor to the "shift cursor" which appears as arrows pointing in all four directions. Clicking on the image with the shift key down and dragging allows you to move the icon image around. When you release the mouse button, the image and mask will be shifted to the new location (the image and mask can only be shifted together). ICON ATTRIBUTES REFERENCE ------------------------- Every icon dealt with by the Finder has associated with it four attributes: file name, file type, auxiliary type, and application pathname. These four attributes help the Finder to match files with their icons. Document icons will generally use only the file type, aux type, and application pathname. Application icons will generally use the file name and type. Name to match: The file name of the icon matches the name of the file the icon belongs to. The "*" character can be used as a wildcard character to match "don't-care" sequences of characters. For example: ICONED will match only a file called ICONED *.ICONS will match any file with a name ending in ".ICONS" * will match any filename File type to match: The file type matches the type of the file the icon belongs to. A file type of $0000 matches any file type. The file type can either be selected from the list provided or entered, if it does not appear in the type list. The filetype can also match hardware devices. Appendix B contains a list of file types and devices currently included in the IconEd list. Aux type to match: The aux type matches the auxiliary filetype of the file the icon belongs to. An aux type of $0000 matches any aux type. Application pathname: This field is used by document icons only. When a document is opened from the Finder, the Finder attempts to run the application that created the document. The application pathname associated with the icon tells the Finder what program to launch. This field must contain the _full_ pathname of the application. The pathname cannot include a wildcard character. If the first character of the application pathname is a "*", it is taken to symbolize the boot disk. You should always indicate the boot disk with "*/" rather than it's literal name. ICONS AND THE FINDER -------------------- The Apple IIGS Finder gets it's icons from the files in the ICONS subdirectory on any disk. The icons can be in any file with a type of $CA (ICN) in the ICONS subdirectory. The only required icon file is the file called FINDER.ICONS in the ICONS subdirectory on the boot disk. This file contains the generic icons and icons for disks and disk devices. When the finder searches for an icon to match a particular file, it searches through all the icon files found, searching FINDER.ICONS last, so the icons in FINDER.ICONS are used only if another match is not found. You should normally not add any new icons to FINDER.ICONS. When you create new icons for files and documents, it is best to put them in another file, leaving FINDER.ICONS uncluttered, and used only for generic icons. Any time a new disk is inserted into a drive, the FINDER checks for an ICONS subdirectory on that disk, and loads any icon files it finds there. Most application disks will have an ICONS subdirectory containing a file with the icons that are specific for that application. When a document is opened from the Finder, it tries to run the document's application from the application pathname associated with the document's icon. This means that if you move or rename an application, it's document icon must be changed to reflect the new pathname. REORDERING ICONS ---------------- New in version 1.3 of IconEd, the icons in an individual icon file can be reordered. When an icon is dragged to a different position within it's window IconEd reorders the icons internally to reflect the new order. The first icon in the file is always in the upper-left corner, while the last icon is always in the lower-right corner. If things become somewhat muddled, selecting Cleanup from the Special menu will redisplay all the icons in the current order. Reordering icons can be useful since when the Finder is searching for an icon for a particular file, it searches only until the first matching icon is found. Therefore, the most general icons (such as the generic file icon) must appear last in each icon file. For example, the icon for IconEd (name = "ICONED*") must appear before the generic GS/OS application icon (name = "*") otherwise when the FINDER is looking for an icon for ICONED, it will stop when it finds the generic GS/OS application icon, and use it. Note that since the FINDER.ICONS file is always last in the list, generic type icons should generally be in FINDER.ICONS. Appendix A: ICON FILE STRUCTURE ------------------------------- This is a brief description of the format of an icon file on the disk. Fields used by the Finder internally are filled with zeroes in the disk file. ICONBLK (icon file): IBlkNext LONG ;used internally by the Finder IBlkID WORD ;ID number for this ICONBLK ($0001) IBlkPath LONG ;used internally by the Finder IBlkName BYTE[16] ;used internally by the Finder IBlkIcons ICONDATA[n] ;list of icon records ICONDATA (icon record): iDataLen WORD ;length of the record (0 terminates list) iDataPath BYTE[64] ;application pathname iDataName BYTE[16] ;file name associated with this icon iDataType WORD ;file type associated with this icon iDataAux WORD ;aux type associated with this icon iDataBig ICON ;icon image data iDataSmall ICON ;small icon image data ICON (icon record - see QDAux chapter in ToolBox Ref II for more info): imType WORD ;flags imSize WORD ;size (bytes) of icon image imHite WORD ;hite (pixels) of icon image imWidth WORD ;width (pixels) of icon image, (4 bits/pixel) imImage BYTE[imSize] ;icon image imMask BYTE[imSize] ;icon mask Appendix B: FILE AND DEVICE TYPES --------------------------------- This appendix lists the filetypes and device types currently known by IconEd, and has been newly updated for GS/OS. Files Devices Type Name Type Name ------------------------------------ ----------------------------------- $0001 Bad Blocks (BAD) $FFF1 SCSI partition $0004 ASCII Text (TXT) $FFF2 CD-ROM partition $0006 Binary Data (BIN) $FFF3 HD partition $0008 Double Hi-Res (FOT) $FFF4 Network (generic) $000B Word Proc file (WPF) $FFF5 File Server $000F Folder (DIR) $FFF6 SCSI (generic) $0019 AppleWorks DB (ADB) $FFF7 Tape Drive $001A AppleWorks WP (AWP) $FFF8 CD-ROM disk $001B AppleWorks SS (ASP) $FFF9 5.25" drive $0050 Word Processor $FFFA RAM disk $0051 Spreadsheet $FFFB 3.5" disk $0052 Data Base $FFFC 5.25" disk $0053 Object Graphics $FFFD Hard Drive $0054 Desktop Publishing $FFFE Full Trash $0055 Hypermedia $FFFF Empty Trash $0056 Educational data $0057 Stationery $0058 Help file $0059 Communications $005A Configuration $00AB GS BASIC Program $00AC GS BASIC Tools $00AD GS BASIC Data $00B0 APW Source (SRC) $00B1 APW Object (OBJ) $00B2 APW Library (LIB) $00B3 GS Application (S16) $00B4 Run-time Library (RTL) $00B5 Shell Application (EXE) $00B6 Permanent Init (STR) $00B7 Temporary Init (TIF) $00B8 New Desk Accessory (NDA) $00B9 Classic Desk Acc (CDA) $00BA Toolset (TOL) $00BB Device Driver (DVR) $00BC Generic load file $00BD File System Trans (FST) $00BF Sound file $00C0 SHR Screen (PNT) $00C1 SHR Picture (PIC) $00C8 Font (FNT) $00C9 Finder Data $00CA Icons (ICN) $00D5 Music Sequence $00D6 Instrument $00D7 MIDI file $00E0 Telecom data (TEL) $00E2 AppleTalk File $00EF Pascal partition $00F0 Basic command (CMD) $00F8 Merlin Link (LNK) $00F9 System file $00FA Integer Basic Program $00FB Integer Basic Vars $00FC Applesoft Program (BAS) $00FD Applesoft Vars (VAR) $00FE Relocatable Obj (REL) $00FF ProDOS 8 Application (SYS)