ScriptingTutorial

Rezilla logo

This is a tutorial about AppleScript support in Rezilla. It explains and demonstrates how to drive Rezilla using scripts written with the AppleScript language. It is assumed that the reader is already familiar with the basics of this language. This document corresponds to version 1.1 of Rezilla.

AppleScript support
- Opening and closing a resource map
- Saving a resource map
- Creating a new resource map
- Rezilla's object model
- Editing a resource
- Modifying in hexadecimal windows
- Creating a new resource
- Basic objects and properties
- Count of objects
- Existence of objects
- Inspector window
- Comparing resource maps
- Exporting resource maps
- Importing resource maps
- External plugins
- Resource pickers
Rezilla's dictionary

AppleScript support

A complete AppleScript support has been introduced in Rezilla starting from version 1.0.5b. AppleScript is Apple's scripting language for automating operations and controlling other applications. Rezilla defines a set of commands and classes which make it easy to automatically manipulate the resource documents: they let you simulate almost all the actions defined by the application, that is to say all the commands defined in the various menus.

All the commands explained in this tutorial have to be addressed to the application using the usual tell statements, like for instance:

	tell application "Rezilla"
		-- here come the commands...
	end tell

In the remaining of this document, we will not repeat in each example the complete tell block for the sake of legibility but it is always implied.

Opening and closing a resource map

One can open documents using the open command.

To open a resource file named somefile.rsrc and located in the directory HD:foo:bar:, use the instruction:

	open "HD:foo:bar:somefile.rsrc" as alias

Similarly, to choose some resource file and open it in Rezilla, just do:

	set theFile to {choose file}
	open theFile as alias

There are three optional parameters to the open command:

with the readOnly parameter, one can force the file to be opened in read-only mode in order to make all modifications impossible. For instance:
```
	open "HD:foo:bar:somefile.rsrc" as alias with readOnly
```
with the from parameter, one can restrict the opening to a particular fork (resource fork or data fork). By default, Rezilla looks in both forks (data fork before resource fork). For instance:
```
	open "HD:foo:bar:somefile.rsrc" as alias from data fork
```
The possible values for the from parameter are data fork, resource fork, or any fork (the default).
with the createFork parameter, one can specify if a resource fork should be created in the case where the file does not have any resource fork already (this is not the same thing as a file with an empty fork). This is possible only if the from parameter is not specified or has value any fork. For instance:
```
	open "HD:foo:bar:file_with_no_fork_at_all" as alias with createFork
```

A map document can be closed with the close command. The optional argument saving is supported in order to decide if the file should be saved before closing (the possible values are yes, no or ask). For instance:

close first map document saving no

Saving a resource map

Modifications made in a resource map document can be saved directly using the save command. Two additional parameters are supported:

the in parameter lets you specify the file in which you want to create the export file. This parameter is optional.
the as parameter lets you specify the fork in which you want to save the resource map. The possible values are data fork, resource fork, same fork (the latter only for Save As). This parameter is optional. It is ignored if the in parameter is not specified because, in that case, Rezilla executes a simple save command on the resource map.

save document 1 in "HD:foo:bar:otherMap.rsrc" as resource fork

It is also possible to discard changes made in a resource map and return to the last saved version of the map using the revert command. For instance:

revert map document 1

Creating a new resource map

One can create a new empty resource map with the make command. This command accepts three parameters. The first two are required, the other is optional:

the parameter new indicates the class of the object to create (map or map document)
the parameter in is used to designate the folder containing the new resource file
the parameter with properties is used to specify some additional properties. It is a list containing key:value pairs (a record in AppleScript parlance). The keys can be any of name, fork and readOnly. This parameter is optional.

Here is a complete example:

-- ask the Finder to make the folder object tell application "Finder" set theFolder to folder "HD:foo:bar:" as alias end tell -- create the new map document in this folder make new map document in theFolder with properties ¬ {name:"newmap.rsrc",fork:data fork,readOnly:true}

Note that the folder containing the new map document must be declared in a tell block addressed to the Finder rather than to Rezilla. This is because the word folder belongs to the Finder's terminology and not to Rezilla's.

Rezilla's object model

There are basically three types of objects in Rezilla: documents, windows and maps. The term map is used to designate the entire contents of a resource fork.

Each map can be considered as a data base whose elements are characterized by a type and an ID. Rezilla's object model uses a similar structure: a map object contains type objects, and these type objects themselves contain resource objects. A map object is always associated with a resource map document, just like a resource belongs to a map.

There are two kinds of documents:

resource map documents correspond to the outline window displayed when a resource file is opened by Rezilla.
editor documents correspond to the editing windows in which individual resources can be edited. An editor document necessarily belongs to a resource map document.

For instance, one can get a list of all the windows, maps or documents with a command like this (the word get is optional):

	get windows
	get maps
	get documents

Map document properties

Map documents can be specified by name or by index. The name is the name of the file this document was opened from: it is not unique since different files can have the same name (if they are in different folders). On the contrary, the index is unique at a given time: it is the index of the document among all the other map documents opened in Rezilla. The index is not permanent though: it can vary as other documents get closed.

Besides the properties shared by all the document objects (see below), map documents also have a set of specific properties:

index: the index of the document among other map documents
readOnly: is this document read-only?
window: the window associated with this document
refnum: the reference number of the map in memory
fork: the fork this document is editing (data fork or resource fork)
map: the resource map associated with this document
file: the file on disk corresponding to this resource map document
format: the format used for export

For instance, the following script lets you retrieve the values of all these properties:

set mapDoc to map document 1 set a to the name of mapDoc set b to the refnum of mapDoc set c to the fork of mapDoc set d to the index of mapDoc set e to the readOnly of mapDoc set f to the window of mapDoc set g to the file of mapDoc set h to the format of mapDoc {a, b, c, d, e, f, g, h}

The format property can be modified using the set command. All the others are read only properties. For instance:

set the format of map document 1 to html

Editor document properties

Editor documents also have properties of their own, besides the properties shared by all the document objects Rezilla defines the following:

index: the index of the editor document among all the editor documents depending from the same map document
kind: the kind of the editor document (hexadecimal, template or interface)
readOnly: is this document read-only?
window: the window associated with this document
resource: the resource edited by this document
owner doc: the rezmap document that owns this editor document

For instance, the following script lets you retrieve the values of all these properties (supposing an editor document is currently open):

set theEd to editor 1 of map document 1 set a to the index of theEd set b to the kind of theEd set c to the readOnly of theEd set d to the window of theEd set e to the resource of theEd set f to the owner doc of theEd {a, b, c, d, e, f}

All these properties are read only properties. They cannot be modified using the set command.

Map window properties

The map window class designates the window displayed by resource map documents. These objects have two properties corresponding to the count fields located at the bottom of the window:

types count: number of types in this map, as displayed at the bottom of the map window
resources count: total number of resources in this map, as displayed at the bottom of the map window

You obtain these values like this for instance:

set mapWin to map window 1 set a to the types count of mapWin set b to the resources count of mapWin {a, b}

These are read-only properties.

Editing window properties

The editing window class designates the windows displayed by editors. They have only one specific property, kind, which indicates the kind of the corresponding editor (it is one of hexadecimal, template or interface).

For instance:

set editWin to editing window 1 get the kind of editWin

This is a read-only property.

As a convenience, it is possible to designate editing windows directly as elements of a map document. So, as a shortcut, one can write

    get editing window 1 of map document 1

instead of

    get window of editor 1 of map document 1

Similarly

    get hexadecimal window 1 of map document 1

is equivalent to

    get window of hexadecimal editor 1 of map document 1

The same is true when designating the editing windows by name rather than by index:

	get editing window "name_of_window" of map document 1

instead of

	get window of editor "name_of_window" of map document 1

Similarly

	get template window "name_of_window" of map document 1

is equivalent to

	get window of template editor "name_of_window" of map document 1

Map properties

The resource maps are considered as objects directly contained in the application. They are characterized by a unique ID: this is a reference number attributed by the System's Resource Manager when the map is opened. For instance, the following instruction

	get map of map document 1

would return something like:

map id 22 of application "Rezilla"

The map could thus be subsequently invoked in a script as map id 22. The ID of a map is guaranteed to be unique.

Resource maps have the following properties:

refnum: the reference number of the map in memory
all types: the list of all the types contained in this map (in alphabetical order)
attributes: the global value of the map attributes (a numeric value, sum of the individual flags)
readOnly: the map's ReadOnly flag (a boolean value)
compact: the map's Compact flag (a boolean value)
changed: the map's Changed flag (a boolean value)

Here is a sample script to retrieve the properties of a resource map:

set theMap to the map of map document 1 set a to the refnum of theMap set b to the attributes of theMap set c to the readOnly of theMap set d to the compact of theMap set e to the changed of theMap {a, b, c, d, e}

A map is a container itself: the objects it contains are types as we will see in the next section. To get the list of all types (as text) within the map:

set theMap to the map of map document 1 get all types of theMap

The attributes, readOnly, compact, and changed properties can be modified using the set command. The others are read only properties. For instance:

set theMap to map document 1 -- 160 is mapReadOnly _and_ mapChanged (128 + 32) set the attributes of theMap to 160 -- This unsets the mapReadOnly flag (-128) set the readOnly of theMap to 0 -- This sets the mapCompact flag (+64) set the compact of theMap to 1 -- This unsets the mapChanged flag (-32) set the changed of theMap to 0

Type properties

A type is an object containing resource objects. Its elements are all the resources of this type. The types are elements of a map object: they can be designated by index or by name. The index of a type is its index in the list of all types belonging to its owner map. The name is the four-characters string representing this type (like "TEXT", "icns", "MENU", etc.)

The following properties can be obtained:

index: the index of the type in the document (types are ordered alphabetically)
name: the type's string
all IDs: the list of all IDs of the resources belonging to this type

Here is a sample script to retrieve the properties of a type in a resource map:

set theType to type "TEXT" of map 1 set a to the index of theType set b to the name of theType {a, b}

To get the list of all resources within the type:

set theType to type "TEXT" of map 1 get all IDs of theType

All these properties are read only properties. They cannot be modified with the set command.

Resource properties

A resource within a type object can be specified by index, by name or by ID. The specification by ID is unique. A resource can also be specified directly in a resource map using a pair made of its type name and its ID, like for instance:

	resource {"TEXT", 128} of map id 22

Note that it is also possible to refer to a resource as if it were directly an object of the resource map document rather than an object of this document's map. This is a shortcut which allows to write constructs like:

	resource {"TEXT", 128} of theDoc

instead of

	resource {"TEXT", 128} of the map of theDoc

The various properties of a resource object can be obtained using the following terms:

name: the resource's name
typename: the type of the resource as text
ID: the ID of the resource
index: the index of the resource within its type (in the order used by the resource manager)
attributes: the global value of the resource's attributes (a numeric value, sum of the individual flags)
sysHeap: the resource's SysHeap flag (a boolean value)
purgeable: the resource's Purgeable flag (a boolean value)
locked: the resource's Locked flag (a boolean value)
preload: the resource's Preload flag (a boolean value)
protected: the resource's Protected flag (a boolean value)
changed: the resource's Changed flag (a boolean value)
size: the size of the resource data (in bytes)
sizeOnDisc: the size of the resource on disk
hex data: the resource data (in hexadecimal format)

Here is a sample script to retrieve some of these values:

set therez to resource {"TEXT", 128} of map id 22 set a to the name of therez set b to the ID of therez set c to the changed of therez set d to the size of therez set e to the sizeOnDisc of therez set f to the attributes of therez set g to the system heap of therez set h to the purgeable of therez set i to the locked of therez set j to the preload of therez set k to the protected of therez {a, b, c, d, e, f, g, h, i, j, k}

The name, attributes, sysHeap, purgeable, locked, preload, protected, changed, sizeOnDisc, and hex data properties can be modified using the set command. The others are read only properties. For instance:

set theRez to resource {"MENU", 128} of map document 1 set the name of theRez to "Apple menu" -- 12 is resProtected _and_ resPreload (8 + 4): set the attributes of theRez to 12 -- This unsets the resProtected flag: set the protected of theRez to 0 -- This sets the resPurgeable flag: set the purgeable of theRez to 1 -- This unsets the resLocked flag: set the locked of theRez to 1 -- This sets the resChanged flag: set the changed of theRez to 1 -- Modifiy the size on disc (use at your own risk): set the sizeOnDisc of theRez to 512

Resource contents

The data of the resource can be obtained using the hex data property, like this:

	set theRez to resource {"ALRT", 128} of map 1
	get the hex data of theRez

The result is returned in hexadecimal form, like, for instance:

	"002800280096019000805555300a"

The set command can be used to install different data in the resource. For instance:

set theRez to resource {"ALRT", 128} of map 1 set the hex data of therez to "001400140087016800805555300a"

Note that there are two exceptions to the hexadecimal representation of resource data. They concern resources of type TEXT and resources of type STR#. In that case, Rezilla will use the textual representation directly:

resources of type TEXT are represented by a text string
resources of type STR# are represented by an AppleScript list of textual strings

For instance, the command

	get hex data of resource {"TEXT", 128} of map 1

would return Viva Rezilla instead of the equivalent hexadecimal 566976612052657a696c6c61 value.

The opposite is true. To set the value of a TEXT or a STR# resource, use the following syntax:

-- simple string set txtRez to resource {"TEXT", 128} of map 1 set the hex data of txtRez to "Viva Rezilla!!!" -- list of strings set strRez to resource {"STR#", 128} of map 1 set the hex data of strRez to {"Viva Rezilla!!!", "Rezilla is great!!!"}

Editing a resource

Editing a resource with a particular editor can be done using the edit command. This command accepts two optional arguments:

the like argument lets you specify that the resource should be edited like resources of another type than its own type. This is the equivalent of the Edit as menu item in Rezilla.
the using argument lets you specify a particular kind of editor. The values can be hexadecimal, template or interface. If there is no editor of the required kind, then Rezilla uses its usual fallback mechanism: in last resort, the resource would be edited in the hexadecimal editor.

Here are a few examples:

	edit resource {"MENU", 128} of map 1 using interface	edit resource {"MENU", 128} of map 1 using template
	edit resource {"MENU", 128} of map 1 using hexadecimal
	edit resource {"aeut", 128} of map 1 as "aete"

Other basic actions are duplicating and deleting a resource in the resource map. They can be achieved using the duplicate and delete commands respectively.

	duplicate resource {"MENU", 128} of map 1	delete resource {"STR#", 128} of map 1

The delete command can also be used to delete all the resources of a certain type simultaneously, like this:

delete type "MENU" of map 1

Modifications made in an editor can be saved using the save command:

save first editor of map document 1

Note that the usual in and as arguments of the save command are ignored in that case.

An editing document can be closed with the close command, like this:

close first editor of map document 1

or, alternatively, by closing the window directly:

set thewin to window of first editor of map document 1 close thewin

Some editors (but sadly not all) understand the revert command. As of version 1.0.6 of Rezilla, this concerns the template editor, the Aete editor, and the Menu editor. For instance:

revert editor "somefile.rsrc - 'MENU' #128" of document 1

Modifying in hexadecimal windows

The hexadecimal windows associated with the hexadecimal editor have several properties which can be used to modify directly the contents of a resource displayed in the hexadecimal pane or in the text pane. The following properties are defined by Rezilla:

maxPos: the index of the last position (i-e the position after the last character)
startPos: the position of the beginning of selection
endPos: the position of the end of selection
hex selection: the contents of the selected region in the hex pane
text selection: the contents of the selected region in the text pane

Here is a sample script to retrieve these properties:

edit resource {"TEXT",128} of map document 1 using hexadecimal set theWin to hexadecimal window 1 of map document 1 set a to the startPos of theWin set b to the endPos of theWin set c to the maxPos of theWin set d to the hex selection of theWin set e to the text selection of theWin {a, b, c, d, e}

The maxPos property is read-only. All the others can be set using the set command. Here is a short example:

set theWin to hexadecimal window 1 of map document 1 set the startPos of win to 6 set the endPos of win to 9 set the hex selection of win to "52657a696c6c61"

In this example, the bytes located between the specified positions would be replaced by the bytes corresponding to the hexadecimal string. Alternatively, the replacement can be achieved in the text pane with the following instruction:

    set the text selection of theWin to "Rezilla"

In order to erase some bytes, just specify an empty string.

Creating a new resource

One can create a new empty resource in a map document with the make command. This command accepts four parameters. The first two are required, the others are optional:

the parameter new indicates the class of the object to create (resource)
the parameter in is used to specify the map document containing the new resource
the parameter with properties is used to specify some additional properties. It is a record containing key/value pairs. The keys can be any of ID, type, name, attributes, locked, preload, protected, purgeable, and sysHeap. This parameter is optional.
the parameter with data is used to specify the contents of the resource. It is optional. If it is not present, the resource is created with empty data.

If no ID is specified, Rezilla will attribute an unique ID. If the ID is specified and if there is already a resource with this ID, the creation of the new resource will fail: Rezilla preserves already existing resources. If no type is specified, Rezilla will create a TEXT resource by default.

Here is a complete example:

set theDoc to map document 1 -- create an empty 'MENU' resource make new resource in theDoc with properties {type:"MENU"} -- create an 'ALRT' resource with ID 128 make new resource in theDoc with properties ¬ {ID:128, type:"ALRT", name:"An alert", protected:true} ¬ with data "001400140087016800805555300a" -- create a 'TEXT' resource with the specified string -- ('TEXT' is the default when no type is specified) make new resource in theDoc with data "Hello Rezilla"

Basic objects and properties

The top container of all Rezilla's objects is the application itself. Rezilla also defines basic document and window classes which all the more specific documents (editor documents for instance) and windows (map windows for instance) inherit from.

This section describes the properties of the application, document and window classes.

Application properties

The application itself can provide some information. It has a version property which returns a string describing the version number. For instance:

get the version

The inspector window is also a property of the application but it can be considered as an object of its own. Its properties are explained in the Inspector window section below.

Document properties

There are a few properties inherited by all the document classes (map documents, editor documents). Rezilla defines the following common properties:

name: the title of the document
modified: a boolean value indicating whether the document has been modified since the last save

Here is a sample script retrieving these properties for two different kinds of documents:

set theDoc to map document 1 set a to the name of theDoc set b to the modified of theDoc edit resource {"TEXT", 128} of theDoc set theEditor to editor 1 of theDoc set c to the name of theEditor set d to the modified of theEditor {a, b, c, d}

These are read only properties. They cannot be modified with the set command.

Window properties

All Rezilla windows (map windows, editor windows, inspector window, etc.) share a set of common properties:

name: the title of the window
index: the number of the window
bounds: the boundary rectangle for the window
closeable: does the window have a close box?
titled: does the window have a title bar?
floating: does the window float?
modal: is the window modal?
resizable: is the window resizable?
zoomable: is the window zoomable?
zoomed: is the window zoomed?
visible: is the window visible?
position: upper left coordinates of the window

Here is a sample code illustrating these properties:

set win2 to the second window set a to the name of win2 set b to the bounds of win2 set c to the position of win2 set d to the visible of win2 set e to the closeable of win2 set f to the titled of win2 set g to the resizable of win2 set h to the zoomed of win2 (a, b, c, d, e, f, g, h)

The name, bounds, zoomed, visible, and position properties can be modified using the set command. The others are read only properties.

Count of objects

The count command can be used to count several kinds of objects. Here are a few examples concerning windows and documents:

-- windows count set a to count windows set b to count map windows set c to count editing windows set d to count hexadecimal windows set e to count template windows set f to count interface windows -- documents count set g to count documents set h to count map documents set i to count editors set j to count hexadecimal editors set k to count template editors set l to count interface editors

{a, b, c, d, e, f, g, h, i, j, k , l}

One can also get a count of maps, types and resources. For instance:

set a to count maps set b to count types of map 1 set c to count resources of type "TEXT" of map 1

{a, b, c}

Existence of objects

The exists command lets you verify if an object is known in Rezilla. Here are a few examples:

first window exists exists second window exists third window exists map of document 1 set theMap to map 1 exists theMap exists type "TEXT" of theMap exists type "XYZT" of theMap set theType to type "TEXT" of map 1 exists resource id 128 of theType exists resource "Vivat" of theType exists resource id 128 of type "MENU" of map 1 exists resource {"MENU", 128} of map document 1 exists hexadecimal editor 1 exists template editor 1 exists interface editor 1 exists editing window 1 exists hexadecimal window 1 exists template window 1 exists interface window 1 exists window of document 1 exists editor 1 of document 1 exists second editor of document 1 exists window of first editor of document 1 exists inspector

Inspector window

The inspector window is always present in Rezilla (it may be hidden but still it is there lurking in the background). To display information about a particular resource, one can use the inspect command like this:

	inspect resource {"MENU", 128} of map 1

This brings the Inspector window with all the information relative to the specified resource. Each field of the inspector window can be accessed using the properties of the inspector:

ID field: the value of the 'ID' field
name field: the value of the 'Name' field
system heap: the value of the 'System Heap' checkbox
purgeable: the value of the 'Purgeable' checkbox
locked: the value of the 'Locked' checkbox
preload: the value of the 'Preload' checkbox
protected: the value of the 'Protected' checkbox
current resource: the resource for which info is currently displayed

set a to the ID field of the inspector set b to the name field of the inspector set c to the system heap of the inspector set d to the purgeable of the inspector set e to the locked of the inspector set f to the preload of the inspector set g to the protected of the inspector (a, b, c, d, e, f, g)

The ID and name fields, as well as all the checkboxes, can be modified using the set data command. For instance:

set the name field of inspector to "Viva Rezilla!!!" set the ID field of inspector to 130 set the system heap of inspector to false set the purgeable of inspector to true set the locked of inspector to true set the preload of inspector to false set the protected of inspector to true

The current resource property gives a reference to the resource currently inspected so that one can write instructions like:

	get the hex data of the current resource of the inspector

The actual properties of the resource should not be confused with what is displayed in the inspector window. If you make modifications in the inspector, they will be validated in the resource only when the Apply button is pressed. To do this in AppleScript, use the save command, like this:

	save the inspector

On the contrary, if you've made changes in the inspector but do not want to keep them, use the revert command to go back to the last saved modifications, like this:

	revert the inspector

To hide the inspector window, use the close command:

	close the inspector

Equivalently, one can hide the inspector with the following commands:

	close inspector window 1

	set the visible of the inspector to false

To make the inspector visible, either use the inspect command as explained above or execute this:

	set the visible of the inspector to true

Comparing resource maps

A comparison between two resource maps can be executed using the compare command. One must specify the two files to compare: the first one is usually refered to as the old one, and the second one as the new one. The command also accepts three optional boolean parameters to set the comparison criteria:

if the ignoreName parameter is set to true, differences concerning the name of the resources will be ignored
if the ignoreAttrs parameter is set to true, differences concerning the attributes of the resources will be ignored
if the ignoreData parameter is set to true, differences concerning the contents of the resources will be ignored

The default is to ignore name and attributes differences.

This command returns a comparison object whose properties indicate which resources differ or are identical between the resource maps. One can query the following properties from the result:

old only resources: list of resources which are only in the old map
new only resources: list of resources which are only in the new map
differing resources: list of resources which are in both maps and are different
identical resources: list of resources which are in both maps and are identical
criteria: the criteria which have been used for the comparison, presented as a keyworded list
ignoreName: have name differences been ignored?
ignoreAttrs: have attributes differences been ignored?
ignoreData: have data differences been ignored?

Here is a complete example:

set theComp to compare "HD:foo:bar:file1" as alias ¬ and "HD:foo:bar:file2" as alias ¬ with ignoreName without ignoreAttrs -- get information out of the result get the old only resources of theComp get the new only resources of theComp get the differing resources of theComp get the identical resources of theComp -- get the criteria get the criteria of theComp

Exporting resource maps

The export command corresponds to the Export menu item in Rezilla's File menu. It lets you generate an export of a resource map in various formats. This command accepts two parameters:

the in parameter lets you specify the folder in which you want to create the export file. This parameter is required.
the with properties parameter lets you specify the name of the export file and the export format. Its value is a record using the name and format keywords. The possible values for the format are xml, html, text and DeRez (default is xml). If no name is provided, Rezilla will use a default name. This parameter is optional.

For instance:

export map document 1 in "HD:foo:bar:" as alias ¬ with properties {name:"exportedMap.xml", format:xml}

Importing resource maps

The import command corresponds to the Import menu item in Rezilla's File menu. It lets you import a resource map from an XML file conforming to the Rezilla DTD (Rezilla.dtd). This is the case, for instance, of the files generated by the Export command in XML format. This command accepts two parameters:

the direct parameter designates a resource map document opened in Rezilla. This map must be empty (a newly created map, for instance). One cannot import in a non empty resource map.
the from parameter specifies the XML file containing the data to import. This parameter is required.

The following example shows how to select a file and import it in the first resource map document:

	set theFile to (choose file)
	import map document 1 from theFile

External plugins

Since version 1.1, Rezilla supports the addition of external editors defined via plugin extensions. The AppleScript terminology has a new plugin keyword to get information about the currently available plugins.

The plugin objects directly belong to the application object. They can be designated by name or by index. Here are a few simple AppleScript instructions:

to get the list of plugins
```
	get name of plugins
```
to count the plugins
```
	count plugins
```

The plugin objects have the following properties:

name: the name of the plugin. This is the name of the plugin bundle. For instance RezImagePlugin.plugin.
index: the index of the plugin
version: the current version number of the plugin
typecode: the type code of the plugin
creator: the creator code of the plugin
loaded: is this plugin already loaded by Rezilla? Plugins are loaded lazily, when the user attempts for the first time to edit a resource via a plugin.
supported types: the list of all resource types which can be edited by the plugin

All these properties are read-only: they cannot be modified with the set command. Here are simple instructions to query the properties of a plugin:

set a to name of plugin 1 set b to version of plugin 1 set c to typecode of plugin 1 set d to creator of plugin 1 set e to loaded of plugin 1 {a, b, c, d, e}

To get a list of the supported types:

get supported types of plugin "RezImagePlugin.plugin"

In the case where several plugins support the same resource type, Rezilla allows you to specify the preferred plugin to use for editing a resource of this type. This can be set in the application in the Plugin Order panel of the dialog window displayed when the Plugins... command is invoked in the File menu. This can also be controlled by the means of an AppleScript. There is a property of the application called preferred plugins for this: it returns a record (a sort of dictionary) where the keys are resource types and the values are the name of the preferred plugin associated with this type. For instance, the following script:

get preferred plugins

could return something like:

	{JPEG:"RezImagePlugin.plugin", PStr:"RezSamplePlugin.plugin", etc.}

This property can be modified using the set command in order to change the preferred plugin for some types (not necessarily all of them). This makes sense only for types which are supported by several plugins. For instance:

	-- Assume the 'jpg ' and 'tiff' resource types can be edited by several
	-- plugins and you want Rezilla to use the RezImagePlugin plugin for them
	set preferred plugin to {«class tiff»:"RezImagePlugin.plugin", «class jpg »:"RezImagePlugin.plugin"}

For this call to succeed the plugins must exist.

Resource pickers

Picker documents (introduced in version 1.1) have the following properties:

name: the name of the picker. This is the name of the associated type (as a string), not the title of the picker window.
index: the index of the picker
readOnly: is this picker read-only?
window: the window of the picker
type: the type of the resources displayed by this picker
owner doc: the rezmap document that owns this picker
selection: the ID of the selected resource

The pickers, as objects, are considered elements of a map document object, just like editor objects. They can be designated by index or by type (the type is used as a name for the picker). For instance:

    set thePik to picker "icl8" of map document 1

The following script lets you retrieve the values of all these properties (supposing a picker document is currently open):

set thePik to picker 1 of map document 1 set a to the name of thePik set b to the index of thePik set c to the readOnly of thePik set d to the window of thePik set e to the type of thePik set f to the owner doc of thePik set g to the selection of thePik

{a, b, c, d, e, f, g}

Only the selection property can be modified using the set command. All the others are read only properties. The ID of the resource to select must be passed as a string. For instance:

    set the selection of picker 1 of map document 1 to "128"

To remove the selection in a picker window, use the selection with an empty string like this:

    set the selection of picker 1 of map document 1 to ""

A picker can be opened using the pick command like this:

pick type "cicn" of map 1

If there is a picker defined for the type, the command returns the object specifier of the newly opened picker.

To close a picker, use the close command like this:

close picker "cicn" of map document 1

Caveat: the pick command applies to types. These are elements of a map object, not of a map document object. On the other hand, pickers are elements of the map document object, not of the map object. So one must carefully make the distinction between map and map document, as in the following code:

    pick type "TEXT" of map 1
    count pickers of map document 1
	close picker "TEXT" of map document 1

Rezilla's dictionary

Here is, for reference, the complete formal description of Rezilla's scripting terminology dictionary.

Required Suite: Terms that every application should support

open: Open the specified object(s) open reference -- Objects to open. Can be a list of files or an object specifier. [from data fork/resource fork/any fork/same fork] -- restrict to a particular fork (default is anyFork) [readOnly boolean] -- specify if the file should be opened in read-only mode (by default it is not) [createFork boolean] -- specify if a resource fork should be created when the file does not have any resource fork already (by default it is not)

quit: Quit the application quit

Standard Suite: Common terms for most applications

Class application: the application Elements: window by numeric index, by name, as a range of elements document by numeric index, by name map document by numeric index, by name map by ID plugin by numeric index, by name Properties: name international text [r/o] -- Rezilla's name version international text [r/o] -- the version of the application inspector inspector window [r/o] -- the inspector preferred plugin record -- the preferred plugin for each supported type: the property is a record whose keys are the types and the values are the plugin names.

Class document: A document Plural form: documents Properties: name international text [r/o] -- the title of the document modified boolean [r/o] -- Has the document been modified since the last save?

Class window: a window Plural form: windows Properties: name international text -- the title of the window index integer [r/o] -- the number of the window bounds bounding rectangle -- the boundary rectangle for the window closeable boolean [r/o] -- does the window have a close box? titled boolean [r/o] -- does the window have a title bar? floating boolean [r/o] -- does the window float? modal boolean [r/o] -- is the window modal? resizable boolean [r/o] -- is the window resizable? zoomable boolean [r/o] -- is the window zoomable? zoomed boolean -- is the window zoomed? visible boolean -- is the window visible? position point -- upper left coordinates of window

close: Close an object close reference -- the objects to close [saving yes/no/ask] -- specifies whether or not changes should be saved before closing

count: Return the number of elements of a particular class within an object count reference -- the object whose elements are to be counted each type class -- the class of the elements to be counted Result: integer -- the number of elements

data size: Return the size in bytes of an object data size reference -- the object whose data size is to be returned Result: integer -- the size of the object in bytes

exists: Verify if an object exists exists Result: boolean -- true if it exists, false if not

get: Get the data for an object get reference -- the object whose data is to be returned Result: anything -- The data from the object

make: Make a new element make new type class -- the class of the new element in reference -- the container in which to create the new element (it must already exist) [with properties record] -- properties of the element (for instance 'name', 'readOnly', 'fork') [with data anything] -- the initial data for the new element Result: reference -- Object specifier for the new element

revert: Revert an object to the most recently saved version revert reference -- object to revert

save: save an object save reference -- object to save [in alias] -- the file in which to save the object [as data fork/resource fork/any fork/same fork] -- the fork in which to save the data (in a Save As operation)

set: Set an object's data set reference -- the object to change to anything -- the new value

Rezilla suite: Rezilla specifics

Class comparison window: a maps comparison window Plural form: comparison windows Properties: inherits window [r/o] -- all properties of the 'window' class result comparison [r/o] -- a comparison result object

Class editing window: a resource editing window (hexadecimal, template or interface) Plural form: editing windows Properties: inherits window [r/o] -- all properties of the 'window' class kind interface/plugin/template/hexadecimal [r/o] -- the kind of the editing window (hexadecimal, template, plugin or interface)

Class editor: an editor document for a single resource Plural form: editors Properties: inherits document [r/o] -- all properties of the 'document' class index integer [r/o] -- the number of the document kind interface/plugin/template/hexadecimal [r/o] -- the kind of editor document (hexadecimal, template, plugin or interface) readOnly boolean [r/o] -- is this document read-only? window window [r/o] -- the window of the document. resource resource [r/o] -- the resource edited by this document owner doc map document [r/o] -- the rezmap document that owns this editor document

Class hexadecimal editor: a hexadecimal document editing a resource Plural form: hexadecimal editors Properties: inherits editor [r/o] -- all properties of the 'editor' class

Class hexadecimal window: a hexadecimal editing window Plural form: hexadecimal windows Properties: inherits editing window [r/o] -- all properties of the 'editing window' class maxPos integer [r/o] -- index of last position (i-e position after the last character) startPos integer -- position of beginning of selection endPos integer -- position of end of selection hex selection international text -- the contents of the selected region in the hex pane text selection international text -- the contents of the selected region in the text pane

Class inspector window: the inspector window Properties: inherits window [r/o] -- all properties of the 'window' class ID field small integer -- the value of the 'ID' field name field international text -- the value of the 'name' field system heap boolean -- the value of the 'System Heap' checkbox purgeable boolean -- the value of the 'Purgeable' checkbox locked boolean -- the value of the 'Locked' checkbox preload boolean -- the value of the 'Preload' checkbox protected boolean -- the value of the 'Protected' checkbox current resource resource [r/o] -- the resource for which info is currently displayed

Class interface editor: a dedicated interface document editing a resource Plural form: interface editors Properties: inherits editor [r/o] -- all properties of the 'editor' class

Class interface window: an interface editing window Plural form: interface windows Properties: inherits editing window [r/o] -- all properties of the 'editing window' class

Class map document: a resource map document (representing the contents of an entire fork) Plural form: map documents Elements: editor by numeric index, by name picker by numeric index, by name Properties: inherits document [r/o] -- all properties of the 'document' class index integer [r/o] -- the number of the document among other map documents readOnly boolean [r/o] -- is this document read-only? window window [r/o] -- the window of the document. refnum small integer [r/o] -- the reference number of the map in memory fork DataFork/ResourceFork/UnknownFork [r/o] -- the fork this document is editing (data fork or resource fork) map map [r/o] -- the resource map associated with this document file file specification [r/o] -- the file on disk corresponding to this resource map document format unknown export/xml/html/text/DeRez -- the format used for export

Class map window: a resource map window Plural form: map windows Properties: inherits window [r/o] -- all properties of the 'window' class types count integer [r/o] -- number of types in this map as displayed at the bottom of the map window resources count integer [r/o] -- total number of resources in this map as displayed at the bottom of the map window

Class picker: a picker document for a given type Plural form: pickers Properties: name international text [r/o] -- the name of the picker: this is the name of the associated type index integer [r/o] -- the index of the picker readOnly boolean [r/o] -- is this picker read-only? window window [r/o] -- the window of the picker type type [r/o] -- the type of the resources displayed by this picker owner doc map document [r/o] -- the rezmap document that owns this picker selection international text -- the ID of the selected resource (use an empty string to remove the selection)

Class picker window: a picker window Plural form: picker windows Properties: inherits window [r/o] -- all properties of the window class

Class plugin: a plugin object Plural form: plugins Properties: name international text [r/o] -- the name of the plugin index integer [r/o] -- the index of the plugin version international text [r/o] -- the version of the plugin typecode string [r/o] -- the type code of the plugin creator string [r/o] -- the creator code of the plugin loaded boolean [r/o] -- is the plugin loaded? supported types a list of list [r/o] -- the list of types supported by the plugin

Class plugin editor: a plugin document editing a resource Plural form: plugin editors Properties: inherits editor [r/o] -- all properties of the 'editor' class

Class plugin window: a plugin editing window Plural form: plugin windows Properties: inherits editing window [r/o] -- all properties of the 'editing window' class

Class template editor: a template document editing a resource Plural form: template editors Properties: inherits editor [r/o] -- all properties of the 'editor' class

Class template window: a template editing window Plural form: template windows Properties: inherits editing window [r/o] -- all properties of the 'editing window' class

compare: compare two resource maps compare alias -- first resource file for comparison and alias -- second resource file for comparison [ignoreName boolean] -- ignore name differences [ignoreAttrs boolean] -- ignore attributes differences [ignoreData boolean] -- ignore data differences Result: comparison -- a maps comparison object

delete: Delete the specified object delete reference -- the object to delete

duplicate: Duplicate a resource in the resource map. The duplicate is automatically attributed an unique ID. duplicate reference -- the object to duplicate Result: reference -- a specifier for the duplicated resource(s)

edit: edit one or more resources edit resource -- resource to edit [using interface/plugin/template/hexadecimal] -- specifies which kind of editor to use (if not specified, Rezilla tries to find successively an interface, a template or the hexadecimal editor) [like type class] -- use an another type's editor

export: export a rezmap document in a specified format export map document -- resource map document to export in alias -- the folder in which to save the export file. This folder must already exist. [with properties record] -- the initial values for the properties (essentially to specify a name and a format)

import: import a rezmap document from an XML file import map document -- the map document into which to import the data. This must be an empty document. from alias -- the XML file to import. It must be conform to the Rezilla DTD.

inspect: display info about the specified resource in the Inspector window inspect resource -- Resource object to display info about.

pick: open a picker pick type -- type of the resources to display in a picker [Result: picker] -- an object specifier for the picker

Resource suite: Resource maps handling

Class comparison: the result of a comparison between two maps Properties: criteria record [r/o] -- the comparison criteria ignoreName boolean [r/o] -- have name differences been ignored? ignoreAttrs boolean [r/o] -- have attributes differences been ignored? ignoreData boolean [r/o] -- have data differences been ignored? old only resources a list of list [r/o] -- the list of resources which are only in the old map new only resources a list of list [r/o] -- the list of resources which are only in the new map differing resources a list of list [r/o] -- the list of resources which exist in both maps and are different identical resources a list of list [r/o] -- the list of resources which exist in both maps and are identical

Class map: a resource map Plural form: maps Elements: type by numeric index, by name, by ID Properties: refnum small integer [r/o] -- the reference number of the map in memory all types list [r/o] -- the list of all types (in alphabetical order) attributes small integer -- the global value of the map attributes (sum of the individual flags) readOnly boolean -- the mapReadOnly bit compact boolean -- the mapCompact bit changed boolean -- the mapChanged bit

Class resource: a single resource with specific type and ID Plural form: resources Properties: name international text -- the resource's name typename string [r/o] -- the type of the resource as text ID small integer [r/o] -- the ID of the resource index integer [r/o] -- the index of the resource within its type (in the order used by the resource manager) attributes small integer -- the global value of the resource attributes (sum of the individual flags) sysHeap boolean -- the resSysHeap bit purgeable boolean -- the resPurgeable bit locked boolean -- the resLocked bit preload boolean -- the resPreload bit protected boolean -- the resProtected bit changed boolean -- the resChanged bit size integer [r/o] -- the size of the resource data (in bytes) sizeOnDisc integer [r/o] -- the size of the resource on disk hex data anything -- the resource data (in hex format)

Class specifier: a two-elements list containing the type and the ID of a resource

Class type: a resource type Plural form: types Elements: resource by name, by ID, by numeric index Properties: index integer [r/o] -- the index of the type in the document (types are ordered alphabetically) name international text [r/o] -- the type's name ID unsigned integer [r/o] -- a type as a long unsigned integer all IDs list [r/o] -- the list of all IDs of resources belonging to this type

Last updated 2006-11-01 15:24:27

Rezilla is hosted by