20

Inspecting Resources

To obtain the number of different resource types in a file:

rez.countResTypes (pathname)

To obtain the string4 identifier of the n th resource type in a file:

rez.getNthResType (pathname, n, addrDestination)

To obtain the number of resources of a given type in a file:

rez.countResources (pathname, type)

To obtain the ID and name of the n th resource of a given type in a file:

rez.getNthResInfo (pathname, type, n, addrID, addrName)

rez.getNthResType() and rez.getNthResInfo() store the requested information by way of address parameters, but they also return a boolean reporting success, so you can loop through all resources without counting them first. For example, this script makes an outline giving the ID (and name if there is one) of every resource in a file chosen by the user.

local (f)

on whatDir()

    if y == 1 {return right}

    return down

if file.getFileDialog ("File to examine:", @f, 0)

    new (outlineType, @workspace.rezOutline); edit (@workspace.rezOutline)

    loop (local (x = 1, y, id, name, t); rez.getNthResType (f,x,@t); x++)

        op.insert (t, down)

        loop (y = 1; rez.getNthResInfo (f, t, y, @id, @name); y++)

            op.insert (id, whatDir())

            if name

                op.insert (name, right)

                op.go (left, 1)

        op.go (left, 1)

For a slightly different implementation of this example, refer to suites.sam-ples.basicStuff.resourceMap() .

Resource Data

Verbs that do things with a resource's data generally come in two flavors, to let you refer to the resource either by name or by ID. In getting a resource's data, there is a third option, to refer to the resource as the n th of its type.

To obtain the data of a resource referenced by ID:

rez.getResource (pathname, type, ID, addrDestination)

To obtain the data of a resource referenced by name:

rez.getNamedResource (pathname, type, name, addrDestination)

To obtain the data of a resource referenced as the nth of its type:

rez.getNthResource (pathname, type, n, addrName, addrDestination)

To set the data of a resource referenced by ID:

rez.putResource (pathname, type, ID, addrSource)

To set the data of a resource referenced by name:

rez.putNamedResource (pathname, type, name, addrSource)

To delete a resource referenced by ID:

rez.deleteResource (pathname, type, ID)

To delete a resource referenced by name:

rez.deleteNamedResource (pathname, type, name)

To check the existence of a resource referenced by ID:

rez.resourceExists (pathname, type, ID)

To check the existence of a resource referenced by name:

rez.namedResourceExists (pathname, type, name)

The data of a resource is always a binary. Dealing with this data - parsing it further to extract particular pieces of information, for example - is up to your script. For one type of resource, parsing utilities are supplied, namely resources of type 'STR ' (a Pascal-type string, which starts with a length byte).

To obtain the data, as a string, from a 'STR ' resource:

rez.getStringResource (pathname, ID, addrDestination)

To set the data of a 'STR ' resource:

rez.putStringResource (pathname, ID, theString)

Otherwise, you must know the structure of the resource in order to parse it. Since resources are designed to be parsed by a machine, this is usually simple enough. Consider, for example, a 'STR#' , which is a string collection. It is structured as follows: two bytes stating how many strings there are; then that number of Pascal strings, where a Pascal string is a length byte followed by the characters of the string. Knowing this, it is trivial to parse the resource; here, for example, is a utility that reads a 'STR#' and converts it to a table of strings.

on strListToTable (path, id, addrT)

    local (str, pos=3, howMany, x)

    rez.getResource (path, 'STR#', id, @str)

    howMany = number("0x" + str[1] + str[2])

    new (tabletype, addrT)

    for x = 1 to howMany

        local (length = string.nthChar (str, pos))

        addrT^.["s" + toys.padWithZeros(x,3)] = string.mid(str, pos+1, length)

        pos = pos + length + 1

The reverse utility, that writes out a table of strings as a 'STR#' resource, is left as an exercise for the reader.

To illustrate the rez verbs further, here is an example script that aids in the importing of XCMDs into the database; it lets the user choose a file, looks for XCMDs in it (using the technique from Example 20-1), lets the user choose from a list of these, and imports the chosen XCMD into the workspace table.

local (f, x, id, name, theOutline)

new (outlineType, @theOutline)

if file.getFileDialog ("File to look for XCMDs in:", @f, 0)

    target.set(@theOutline)

    loop (x = 1; rez.getNthResInfo (f, 'XCMD', x, @id, @name); x++)

        if name {op.insert(name, down); rollBeachBall()}

    loop (x = 1; rez.getNthResInfo (f, 'XFCN', x, @id, @name); x++)

        if name {op.insert(name, down); rollBeachBall()}

    op.firstsummit(); op.deleteLine(); op.sort(); op.firstsummit()

    name = listselect.getChoice \

        (toys.outlineToList(@theOutline), "XCMD to import:", 1, 1)

    if name

        if not rez.getNamedResource (f, 'XCMD', name, @workspace.[name])

            rez.getNamedResource (f, 'XFCN', name, @workspace.[name])

    target.clear()

An interesting utility verb showing the rez verbs in action is suites.sam-ples.basicStuff.resourceStealer() ; you specify a folder, a resource type, and a file pathname, and all resources of that type are copied from all the files in that folder, to a depth of infinity, into the specified file (which is created if necessary), which is then opened by ResEdit.

The Resource Chain

The resource chain is the set of resources available to the system at any given moment. Adding a resource to the resource fork of an open file brings the resource into the resource chain immediately. When Frontier is running, there is a file known to be open and whose resource fork we can modify: the database. A resource can be added to the database's resource fork, on the fly, while the database is open and Frontier is running, in order to make that resource available to the system. It can then be removed from the database's resource fork when we are finished using it.

Here, for example, is a script that plays a 'snd ' resource stored as a binary in the database; it adds the binary to the database's resource fork, plays it, and removes it from the database's resource fork (the database entry remains).

rez.putNamedResource \

    (frontier.getFilePath(), 'snd ', "mySound", @workspace.mySound)

speaker.playNamedSound("mySound")

rez.deleteNamedResource \

    (frontier.getFilePath(), 'snd ', "mySound")

Resource Attributes

With every resource is associated a set of resource attributes, coded as a short integer each of whose bits represents an attribute. Two verbs let you get and set this short integer.

To obtain a resource's attributes:

rez.getResourceAttributes (pathname, type, ID)

To change a resource's attributes:

rez.setResourceAttributes (pathname, type, ID, theShort)

The bit verbs (see Chapter 15, Math) can be used to manipulate the individual bits of the short. The bit flag meanings are:

• 1: resource has been changed
• 2: resource is to be preloaded
• 3: resource is protected
• 4: resource is locked
• 5: resource is purgeable
• 6: resource is to be read into the system heap

These are very advanced verbs, requiring an intimate understanding of Mac OS resources, and the vast majority of users will never call them.