Create your own icons

By David E. Smith

In last month’s column, we presented a complete program shell for creating a Mac application from assembly language. We did not cover menus or menu bars, which we will save for next time. Also, we did not cover resources. This month, we begin examining resources and in particular, icons, including how to install an icon on the desktop. If you’ve wanted to know how to create your own icons for your applications, then read on for a complete cook-book approach to this most unfamilar of Mac topics.

Macintosh and Resources

Resources have to be the most frustrating aspect of learning how to program the Macintosh. It has been said the only reason they exist at all is to get around limitations of Lisa Pascal; a statement made by a programmer no doubt. But they do serve a useful purpose once the program design is completed in that they allow text oriented program aspects like menus and dialogues to be seperated from the code to facilitate translation into foreign languages. Apple is the first company to design into it’s product a universal market appeal. To date few developer’s have taken advantage of this feature, but it’s there.

The main problem of resources facing new developer’s is that the concept is unique to the Macintosh, and almost totally undocumented. “Inside Macintosh”, the only offical Mac documentation from Apple, mentions only resource compi- lation on the Lisa using the Resource Compiler. It also mentions a “Resource Editor”, but says it doesn’t exist yet. What about the Mac environment? For the most part, that has to be dug out by hacking to translate Lisa resource formats into one of the Macintosh formats shown in figure 1. Both the Apple assembler/ linker and the RMaker utility can compile resources ON the Mac, FOR the Mac. The problem is, the formats are different than those described in the IM manuals for Lisa’s Resource Compiler.

In addition to RMaker or the assembler system, other utilites are needed as shown in figure 2. Both icons and fonts are complicated enough to require their own editors for creating them. These utilities are available with the Software Supplement on Macintosh disks, or can be found in many public domain libraries. The remainder of this column will assume you have access to at least the icon editor and the Apple assembler/editor written by Bill Duvall of Consulair Corp.

ICONS ON THE DESKTOP

The first thing most people want to do with resources is to create a unique icon on the desktop for their application program. Like a logo, an icon is often created before the first line of code is written! Creating an icon is easy. Getting it onto the desktop is not. The desktop file exhibits many peculiar properties when it comes to icons. If you move a file from one disk to another, you may be surprised to find the icon changes. This is because the Finder keeps a list of icons and the creator tags that go with each icon. If the desktop file already has an icon for a creator tag, it uses it, ignoring the icon resource in the application file. If it has never seen that creator tag before, it reads the file’s resource to match the new icon with that creator type.

DESKTOP FILE NEVER FORGETS!

The key to icons is the fact that the desktop file never forgets icon/creator tag combinations even if the file or applciation has been trashed. The only way to make it forget is to destroy the desktop file and force the Finder to re-create it from the resources in each application file. This is most easily done by booting up with the option/command key held down. This forces a new desktop file to be created, but throws everything out of the folders onto the desktop.

CREATOR BYTES MUST BE UNIQUE

If a file is moved to a disk where it never existed, but the creator tag has existed, the file will come up with the icon previously associated with that creator. This is why Apple requires icons and creator tags to be registered with them. The four byte creator tag must be unique or the whole Macintosh Icon scheme will be frustrated as applications and documents lose track of each other.The TYPE and CREATOR tags tell the Finder which applications should be launched for which documents, and the icons are the visual indication of that linkage. Changing the creator tag of a resource file to something unique that the desktop file for that disk has never seen, will cause the new icon to appear without trashing the desktop file. Let’s see how we go about creating new icons for our applications.

ICON EDITOR

The icon editor utility is used to create the new icon by using a “fat bits” mode to click in the icon form. A small window shows the acutal icon proportions. An additional window displays the hex code format for the icon. Figure 3 shows the icon editor output as seen on the screen. The hex code for the icon, shown in figure 4, is saved to disk, with an appropriate name such as “WIND.ICON”. The problem is, this binary information represents the graphic bit pattern of the icon and is incompatable with all our other resource tools. What is needed is a simple utility to read each byte of our icon file and re-write it in text format that either the assembler or RMaker can read.

ICON CONVERTER UTILITY

The icon converter utility is written in MS/Basic 1.0 and is shown in the listing in figure 10. The output and set-up for the program is shown in figure 5. Icon Converter reads the icon file created by the icon editor and produces either a text file in assembly source code format for use by the assembler, or a text file in resource format for use by RMaker, the resource compiler on the Macintosh. As the questions in figure 5 indicate, the user can specify assembly or resource format for the output. Also, the program can generate an icon mask or read in a second icon file created by the icon editor for the mask.

ICON MASK

The icon mask is used when the icon is clicked. The mask icon is XOR’d with the icon to produce a black outline of the icon when it is selected. If the automatic mask option is selected with icon converter, then a mask of $FFFF will be generated, which will result in the black outline shown for the icon in figure 6A. This produces a black square with the icon in white. To get the mask limited to the outline of the icon, a second icon must be created with the icon editor by filling an outline of the icon with solid black. This second icon can be saved as “WIND.ICON.MASK” for example, and loaded by the icon converter by selecting the load mask option. The icon shown in figure 6B was created with a second icon for it’s mask. In either case, the program writes a text file of both the icon and it’s mask (either the automatic mask or the mask icon) to disk and names it with the “.ASM” or “.R” suffix, depending on if the assembler output or resource output is selected. The resulting output file can then be “INCLUDED” by the assembler in the assembly resource file, or merged with a resource file for compilation by RMaker.

PUTTING IT ALL TOGETHER

Figure 7 shows an outline of the whole icon process. The assembler/linker system is the most reliable way to create icons and resources. The only problem is that the format of resources compiled with the assembler is not documented in the assembler manual. This format is different from the IM documentation for the Lisa resource compiler, as is the format for RMaker, which is only slightly better documented than the assembler format. After much trial and error, and an example file from Bill Duvall, the author of the assembler/linker, the correct assembly format for icons was found. The assembly source code is shown in figure 8. Icons that will be recognized by the Finder must include an ID string resource, a bundle resource, a file reference resource, and finally, the icon resource itself. Notice that all four of these resource types are shown in the assembly listing in figure 8.

Instead of copying the hex format for the icon from the icon editor, into the resource file, we simply use the INCLUDE function at the botton of the file to read in the assembly source code for our icon created by the Icon Converter program. This produces the necessary “DC.L $FF...” information for us. The resource file is compiled seperately from the code file and then linked together using the Linker.

ID TAG CRUCIAL

The key to getting the resource file to be recognized by the Finder, and the icon installed on the desktop, is to place the creator tag in several key places within the resource file. This includes the TYPE field in the identification string, the signature name in the bundle resource, and the creator field in the linker file. These three locations must contain the same four byte tag if the icon is to be loaded by the Finder. The first two locations are shown highlighted in figure 8. The creator tag is set in the linker file shown in figure 11. If RMaker is being used instead of the assembler, then both the id string and bundle tags can be set along with the creator tag within the resource file itself. Figure 9 shows the same resource file as figure 8, but in RMaker format instead of assembly format.

ASSEMBLER VERSUS RMaker

Which is easier to use, the assembler or RMaker, for creating resources? The assembler/linker is far more dependable and the files shown in this column are guaranteed to work. But the RMaker is a little better documented in the Apple assembler manual. After talking with Apple and Bill Duvall, it appears that Apple prefers to use RMaker for resources and the assembler for code, while Bill Duvall uses the assember for both code and resources and never uses RMaker. Hence, resource creation on the Mac suffers from a dual personality. If the IM syntax were completely translated into Mac assembly syntax, then the assembler/linker method would be the most flexible and easiest to use.

A few words on using the Icon Converter program. The assembly and resource files created by this utility have neither a type or creator tag. This works fine with the assembler. The INCLUDE function is able to find and load the icon source code and assemble it along with the rest of the resources. The RMaker program, however, will not recognize the output of the Icon Converter program until the file’s type and creator have been set to TEXT and EDIT by the Set File utility. In many respects, RMaker is very much like a stripped down Linker program. It produces an application file just as the linker does. Once the icon is created, code segments can be moved into the resource file to create a complete application. With the linker, code and resources are combined at link time. Both RMaker and the linker set the type, creator tags, and the bundle bit by using the new linker options “/BUNDLE”, and “/TYPE” commands. The bundle bit tips off the Finder to check for an icon in the resource fork of the application. If the bundle bit is not set, no new icon!

The Linker File

Figure 11 shows the linker file used to link both the resources and the code file together to form a complete application. The code file is the same relocatable code we created last month for the windows program. It simply opens a window and draws a box on the screen. Due to space limitations, we have not re-printed the source listing for it here, but you can get that from last month’s column. The important thing here is that any program code can be linked in place of our windows3 code, and the remaining linker commands will then link in the icon resource file to create a new icon on the desktop. Note the new linker commands for setting both the file type, creator and the bundle bit. To get this capability, you must have the final release version of the linker. Thanks for joining us in the Assembly Lab, and if you have something you’ve discovered, please write and share it with our readers.

RESOURCE FILE IN ASM FORMAT
; WINDOWS3_RSRC.ASM
; resource file for windows3
; created using the assembler
; signiture is creator tag 
;
RESOURCE ‘BOSW’ 0 ‘IDENTIFICATION’

DC.B  32, ‘WINDOWS3 MACTECH 1-2 - 23 NOV 84’
 
.ALIGN 2
RESOURCE ‘BNDL’ 128 ‘BUNDLE’

DC.L  ‘BOSW’      ;NAME OF SIGNATURE
DC.W  0,1          ;DATA (DOESN’T CHANGE)
DC.L   ‘ICN#’       ;ICON MAPPINGS
DC.W  0             ;NUMBER OF MAPPINGS-1
DC.W  0,128      ;MAP 0 TO ICON 128
DC.L   ‘FREF’      ;FREF MAPPINGS
DC.W  0             ;NUMBER OF MAPPINGS-1
DC.W  0,128      ;MAP 0 TO FREF 128

RESOURCE ‘FREF’ 128 ‘FREF 1’
 
DC.B   ‘APPL’, 0, 0, 0
 
.ALIGN 2
RESOURCE ‘ICN#’ 128 ‘MY ICON’

; FIRST APPLICATION ICON BIT MAP

INCLUDE WIND.ICON.ASM
fig. 8
!codeexampleend!

RESOURCE FILE IN .R FORMAT
WINDOWS3c
APPLZSOB
*
* set up id string
*
TYPE ZSOB = GNRL
 ,0                ;; id name is signiture
.I
10
.P
ABCDEFGHIJ

*
* set up file reference
*
TYPE FREF
 ,128              ;; resource id
APPL 0             ;; file type, id of icon

 ,129              ;; resource id
WIND 1             ;; file type, id of icon

*
* set up bundle resource
*
TYPE BNDL
 ,128             ;; resource id
ZSOB 0            ;; bundle owner
ICN#              ;; bundled icons for appl
0 128 1 129        ;; local id 0 maps to 128
FREF
0 128 1 129       ;; appl  ref 128, doc 129

*
* icon and shadow for application
*
TYPE ICN# = GNRL
  ,128
.H
FFFFFFFF A80600E1 A81F0191 A8108119 
A8008201 A8001801 A8001801 A8200005 
A8300009 A80C0011 A8038061 A8007F81 
A8000001 A8000001 AFFFFFFF AFFFFFFF 
A8000001 A8000001 A8010001 AA080009 
AA080009 AA080009 AA093209 AA492A39 
AAA92649 AB192279 A8000001 A8000001 
A8000001 A8000001 A8000001 FFFFFFFF 
 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF 
Fig. 9

ICON CONVERTER
10 ‘    ICON CONVERTER
20 ‘    (C) DAVID SMITH MACTECH 1-2
30 ‘
40 DIM SEC$(32),MEC$(32),LIN$(8)
50 CLS
60 CALL TEXTFONT(4)
70 INPUT “Name of Diskette (no colon)            “;DSK$
80 INPUT “Name of File  (CR for Finder )          “;FIL$
90 ‘
100 IF  FIL$=”” THEN SYSTEM
110 INPUT “ASM FILE OR RMAKER FILE            (A  or R) “;ASMFLG$:ASMFLG=0:IF 
                ASMFLG$=”A” THEN ASMFLG=1
120 INPUT “ADD MASK ICON OR GENERATE              DEFAULT (A OR D)  “;MSK$
130 IF MSK$=”A” THEN MSK=1 ELSE MSK=0
140 IF MSK THEN INPUT “Name of Mask                 File “;FIL2$
150 NAM$=DSK$+”:” + FIL$
160 NAM2$=DSK$+”:”+FIL2$
170 I=0:J=1:K=0:L=1
180 OPEN NAM$ FOR INPUT AS #1
190 IF MSK THEN OPEN NAM2$ FOR INPUT             AS #2
200 ‘
210 WHILE NOT EOF(1)
220 KEY$= INPUT$(1,#1) :IF MSK THEN               KEY2$=INPUT$(1,#2)
230 REC$= HEX$(ASC(KEY$)):IF                           LEN(REC$)=1 THEN 
REC$=”0"+REC$
240 IF MSK THEN  MAS$=                                    HEX$(ASC(KEY2$)):IF 
LEN(MAS$)=1              THEN MAS$=”0"+MAS$
250 IF MSK=0 THEN                                            MAS=255:MAS$=HEX$(MAS):IF 
                     LEN(MAS$)=1 THEN MAS$=”0"+MAS$
260 SEC$(J)=SEC$(J)+REC$:                                MEC$(J)=MEC$(J)+MAS$:I=I+1:IF 
I=4            THEN J=J+1:I=0
270 WEND
280 ‘
290 ‘     END OF FILE FOUND
300 CLOSE #1:IF MSK THEN CLOSE #2
310 IF ASMFLG THEN OPEN NAM$+”.ASM”             FOR OUTPUT AS #1
320 IF ASMFLG=0 THEN OPEN NAM$+”.R”              FOR OUTPUT AS #1
330 ‘
340 ‘  COMPOSE TEXT STRINGS ICON
350 IF ASMFLG=0 THEN GOTO 480
360 ‘
370 ‘   ICON FOR ASSEMBLY FILE
380 FOR L=1 TO 8
390 LIN$(L)=”DC.L    “:FOR J=1 TO 4:                  LIN$(L)=       
                                              LIN$(L)+”$”+SEC$(4*(L-1)+J)
400 IF J<4 THEN LIN$(L)=LIN$(L)+”, “
410 NEXT J
420 NEXT L
430 ‘
440 FOR L=1 TO 8:PRINT LIN$(L):PRINT                #1, LIN$(L):NEXT 
L:PRINT:PRINT#1, “ “
450 GOTO 530
460 ‘
470 ‘    ICON FOR RESOURCE FILE
480 FOR L=1 TO 8:LIN$(L)=””
490 FOR J=1 TO 4: LIN$(L)=                                LIN$(L)+SEC$(4*(L-1)+J)+” 
  “: NEXT J
500 NEXT L
510 FOR L=1 TO 8:PRINT LIN$(L):PRINT                #1, LIN$(L):NEXT 
L:PRINT:PRINT#1, “ “
520 ‘
530 ‘    COMPOSE TEXT STRINGS FOR             MASK ICON
540 IF ASMFLG=0 THEN GOTO 650
550 ‘
560 ‘   MASK FOR ASSEMBLY FILE
570 FOR L=1 TO 8
580 LIN$(L)=”DC.L    “:FOR J=1 TO 4:                   LIN$(L)=LIN$(L)+”$”+ 
                                  MEC$(4*(L-1)+J)
590 IF J<4 THEN LIN$(L)=LIN$(L)+”, “
600 NEXT J
610 NEXT L
620 FOR L=1 TO 8:PRINT LIN$(L):PRINT                #1, LIN$(L):NEXT 
L:PRINT:PRINT#1, “ “
630 GOTO 710
640 ‘
650 ‘    MASK FOR RESOURCE FILE
660 FOR L=1 TO 8:LIN$(L)=””
670 FOR J=1 TO 4: LIN$(L)=                                LIN$(L)+MEC$(4*(L-1)+J)+” 
“:NEXT J
680 NEXT L
690 FOR L=1 TO 8:PRINT LIN$(L):PRINT              #1, LIN$(L):NEXT L:PRINT:PRINT#1, 
“ “
700 ‘
710 ‘     INITIALIZE AND GO AGAIN
720 CLOSE #1
730 FOR I=0 TO 32:                                            SEC$(I)=””:MEC$(I)=””:NEXT 
I
740 FOR I=1 TO 8:LIN$(I)=””:NEXT I
750 GOTO 80
760 END
Fig 10.

LINKER FILE
!START
[
)
/OUTPUT WINDOWS3b

WINDOWS3

/TYPE ‘APPL’ ‘BOSW’
/BUNDLE
/RESOURCES
WINDOWS3_RSRC

$

Fig. 11