[net.micro.mac] Resource Editor Documentation

lsr@apple.UUCP (Larry Rosenstein) (02/25/85)

I just received some documentation on the resource editor, and so I thought
pass along a summary of it. 

I assume that you have used the resource editor already, and so I will
describe only the things that are not very obvious.  Also, this
documentation applies to the Resource Editor of 2/6/85, which is somewhat
later than the version that has been posted already, so I don't know how
much of the following is applicable to the old version.  (Please don't ask
me to post the resource editor, it is available in a variety of places
including CompuServe, USENET, and the Info-Mac archives.  I expect that the
latest version will be available soon, since it has just gone out with the
latest Software Supplement.)

----------

The first thing to note is that the resource editor still has some bugs in
it, so you are advised to backup your resource files before editing them.
It is recommended that you NOT edit the resources in the currently open
System file; use a system file on a non-boot disk.  Also, never reboot
before closing all file windows, otherwise your resource files may be in an
inconsistent state.  The resource editor does not check for write protected
disks.

----------

Some definitions:

Disk Window: 1 per disk inserted in the machine, displays all resource
  files on that disk.
File Window: 1 per opened resource file, displays all resource types
  contained in the file.
Type Window: 1 per opened resource type, displays all the resources of that
  type.
Edit Window: 1 per opened resource, allows you to edit the resource.

----------

Some Useful Hints:

In the disk window, clicking the go away box, ejects the disk.  You should
be careful about ejecting hard disks, RAM Disks, etc.

You can double click on an item (file name, type name, ...) to open it.  In
general, if you hold down the option key while openeing an object you will
get the default view of that object.  For example, if you open the ICON
resource type you usually see pictures of the icon resources.  If you hold
down the option key, however, you will see the default display that gives
the the resource name & number.

The name of a font is stored as the name of a resource with font size 0,
which is not normally displayed.  If you want to change a font name, bring
up the generic list of font resources by holding down the option key while
you open the FONT resource type.  Then you can use the Get Info command to
edit the appropriate resource name.

In a Type Window: if you hold down the option and command keys while
opening a resource, you will be asked to enter an alias resource type.
This is useful, for example, with the version resources that applications
have.  They are really string resources but with a special resource type.
You must be careful because the resource editor does not do much checking
to see if the resource is really of the type you say it is.

Besides selecting and copying (cutting, etc.) individual resources, you can
select a resource type and copy all the resources of that type.

If you hold down the option key during a copy or cut the selected objects
are appended to the clipboard file.

In a Disk or File Window: Typing a character scrolls the list to the first
item beginning with that letter (as in the Standard File dialog).

To install a new icon (something everyone has been waiting for):
First edit the icon in the application.  Then edit the Desktop file to make
the Finder install the new icon.

  Open the Desktop file.
  Find the BNDL resource that contains OwnerName = <your application
    creator> & remember its ID.
  Open the BNDL and write down the types and rsrcID's (not localID's)
    of all the resources it "bundles".  (Usually FREF and ICN#.)
  Remove from the Desktop file the following resources: the BNDL, the
    resource with the same type as your application creator, and the
    ones you wrote down.
  When you exit the resource editor your new icons should appear.

In edit windows, you will often find lists of items seprated by something
like *****.  To edit such a list, select one of the separators and use the
appropriate editing command.  (Cut applies to the element following the
selection.)

----------

Extensibility

The resource editor has specific code to edit certain types of resources
(icons, cursors, patterns, fonts, etc.)  This is done with special
resources of type RSSC.

When you open a Type or Edit window, the resource editor looks for an RSSC
resource whose name is the same as the resource type. If it is found, it is
loaded and executed as code (much like a driver).  This piece of code
handles both the Type and Edit windows.  I don't have any information on
how to create specialized editors, so I can't tell you the format of this
resource.

There is another level of extensibility, using resources of type TMPL.  If
one of these is found for a particular resource type, it is used to
generate the dialog allowing you to fill in the fields of the resource.
The TMPL resources will handle all the resource types that the Macintosh
uses and most structures that can be defined by a Pascal RECORD type.

When you create a TMPL resource, you specify a series of fields (much like
a RECORD definition).  Each field has a name and type.  The following
are the allowed types (all 4 characters):

  DBYT, DWRD, DLNG: decimal byte, word, long
  HBYT, HWRD, HLNG: hexidecimal byte, word, long
  HEXD: hex dump of remaining bytes in resource
  PSTR: Pascal string
  LSTR: long string; long length followed by characters
  ESTR, OSTR: Pascal string padded to even, odd length
  CSTR: C string
  BOOL: Boolean
  BBIT: binary bit
  TNAM: type name (like a resource type -- 4 characters packed into a long)
  CHAR: character
  
There are also array-like types.  Each of these consists of a list
beginning field, followed by any other fields, followed by a list end field.
Each element of the list consists of the record defined by the types in the
middle.  There are several list types (use these to start a list):

  LSTZ: list with a trailing 0 byte
  ONCT/LSTC: the ONCT is an uneditable count and the LSTC begins the list
             itself; this list is indexed from 1
  ZCNT/LSTC: like ONCT only indexed from 0
  LSTB: list that ends at the end of the resource

The end of the fields that make up each list element is marked with a LSTE
field.  Lists can be nested (look at the TMPL for BNDL resources).  The
name of the fields used to start/end a list are used as the separators of
the list elements.  

This TMPL stuff is difficult to explain, but there are lots of examples in
the resource editor.  You can use the resource editor to edit itself and
install or modify a TMPL resource.  The next time you edit a resource of
that type, the resource editor will use the latest TMPL.

Good luck.

Larry Rosenstein

-- 

UUCP:  {nsc, dual, voder, ios}!apple!lsr
CSNET: lsr@Apple.CSNET

lsr@apple.UUCP (Larry Rosenstein) (02/25/85)

There was one  mistake in my earlier resource editor documentation.  If you
want to specify an alias resource type you hold down the option and SHIFT
keys (not the option and command keys as I said) when you open the
resource.

Sorry for the error.



-- 
Larry Rosenstein

UUCP:  {nsc, dual, voder, ios}!apple!lsr
CSNET: lsr@Apple.CSNET

lsr@apple.UUCP (Larry Rosenstein) (02/27/85)

Yet another typo in the resource editor documentation.

To define a 1-based list you create a field with type OCNT not ONCT as I
had originally stated.  (This was in fact a typo in the documentation I
received.)

Don't worry, eventually, I will get it right.



-- 
Larry Rosenstein

UUCP:  {nsc, dual, voder, ios}!apple!lsr
CSNET: lsr@Apple.CSNET