Creating a Custom AppleScript Dictionary For a Revolution Application
Mac Only Mac Only

A few things to keep in mind before we get started: Here's the steps:

DOWNLOAD THE SAMPLE FILES

The CustomASDictionary archive contains the following files:

These files are for your reference to see how something was created with a custom AppleScript dictionary. Here's what the dictionary looks like in Script Editor:

MyAppASDict

The instructions below are for creating an custom AppleScript dictionary from scratch:

PREPARE THE RSRC FILE

  1. Make a copy of the Revolution.rsrc file into any folder you wish.
  2. Change the name of the file to MyApp.rsrc.
RENAME THE TERMINOLOGY RESOURCE NAME
  1. Double-click on the MyApp.rsrc file to launch ResFool.
  2. Toggle open the "aete" resource to show "aete ID 0" resource called "Revolution Terminology"
  3. Select the line that says "Revolution Terminology", and select "Selection Info" from the Window menu; change the name of the resource to "MyApp Terminology" and click "Change".
SET UP YOUR SUITES
  1. Double-click on the line "MyApp Terminology".
  2. If you want to keep the "do script" and "evaluate" events, you'll need to decide if you want to have just ONE suite that contains the "do script" and "evaluate" events in addition to the custom events you want to create, or whether you want to have TWO suites (one for "do script"/"evaluate", and the other for your custom events). If you don't want to keep them, you will need to delete them. Either way you'll need to rename the current suite, and may optionally want to add one or more additional suites.
  3. Click the "Edit..." button next to the Suite popup menu.
  4. In the dialog that is displayed, you can click on the "Revolution Miscellaneous Commands" suite and change its name in the "Name" field. You may optionally change the "Code" field to provide a four-character Class code that will be used as the default Class code whenever you create a new event for that suite. If you don't want to add another suite, click "Done". If you want to add another suite, click the "Add" button, give the new suite a name, enter a code for it, and then click "Done".
ADD YOUR EVENTS
  1. Select the suite you want to add your event(s) to from the Suite popup menu.
  2. Click the "Add" button under the event list.
  3. In the Name field, give your event a name (like "show greeting"). This name is basically the string that will be entered just before any parameters are provided (if you need parameters for the event).
  4. The Class should fill in based on the Class Code that was assigned to the suite (see #4 in the previous section). Enter a four character ID code for the event. You should be safe with all-caps ID codes, but you can choose what you want.
  5. Enter a description for the event below the Class/ID codes.
  6. If the event will return a value from Revolution, you can set the Reply popup to "TEXT" (note that this is "TEXT", not "Text"; you will need to type it in, overwriting the "null" that is in there by default); otherwise leave it "null".
  7. If your event has one or more parameters, the first one is called the "Direct Parameter" and needs to be set in the Direct Parameter group; enter a type of parameter (can be "TEXT", "bool", "long", or "shor"; if you don't know what you want, use "TEXT"), and provide a description for the parameter.
    NOTE: This is what is retrieved from Rev using "request appleEvent data".
  8. If your event has two or more parameters, these are added to the "Parameters" group; click "Add", set the name of the parameter, add a description, set a four character keyword and enter the type of the parameter (same restrictions as #7 above). If the parameter is to show as an optional parameter (i.e. surrounded in square brackets), click the "Flags" button and turn on the "Optional" checkbox.
    NOTE: This is what is retrieved from Rev using:
    request appleEvent data with keyword <code>.
FINISH UP
  1. Save the AETE resource and exit ResFool.
  2. Copy the MyApp.rsrc file into your application's bundle at:

    MyApp.app/Contents/Resources/MyApp.rsrc
That's it!

The next part is to trap the events in your Rev app, and for that you should look at the code in the MyApp.rev stack's stack script.

Once you have your appleEvent handler set up properly, you can test your app:

TESTING

  1. Launch the Apple Script Editor.
  2. Browse your app's AppleScript dictionary by choosing "Open Dictionary..." from the File menu and selecting your app that you created.
  3. Create a new script using a "tell" statement directed at your app, including your custom command you'd like to test, like:

    tell app "myApp"
      show greeting
    end tell
  4. Then click "Run" and see if it works!
If you ever get confused as to how to structure your custom events, look at the MyApp.rsrc file in ResFool and compare it to how Apple's Script Editor represents the events in the AppleScript dictionary.

Enjoy!

Ken Ray
Sons of Thunder Software