A few things to keep in mind before we get started:

• You can find the basic .rsrc file that contains the AETE resource in the Revolution IDE application, at: Revolution.app/Contents/Resources/Revolution.rsrc
• When you build a standalone from Revolution, the generic Revolution.rsrc file is compiled into your application, so make sure to keep a copy of your own .rsrc somewhere outside your application so you can copy it into new standalones as you build them (and delete the Revolution.rsrc file).
• IMPORTANT!! Each time you rebuild your application and reinstall the .rsrc file, make sure you THROW OUT your previous application and EMPTY THE TRASH. You really need to make sure that Apple's Script Editor can only find ONE version of your application to connect to; if you have more than one, it will confuse the Script Editor and you may get very unpredictable results!
• You will need to make sure the .rsrc file is named the same as your standalone engine file otherwise it won't be 'attached' properly. So if you create an application called "MyApp", the engine file in the bundle should be called "MyApp" and the .rsrc file should be "MyApp.rsrc".
• You will need to download ResFool, or some other app that can edit the AETE resource, like Rezilla, and have it installed on your Mac. The instructions below assume you're using ResFool.
• For the step-by-step below, I'll use the name "MyApp" for the name of your standalone; obviously change it to reflect your true standalone application name.

Here's the steps:

DOWNLOAD THE SAMPLE FILES

The CustomASDictionary archive contains the following files:

• MyApp.rev - A generic Rev application that displays any appleEvents that it receives, and responds to the custom 'show card', 'show greeting', and 'animate' commands. Look in MyApp's AppleScript dictionary for how call these!
• MyApp.rsrc - The resource file containing the AETE resource with the AppleEvent suite called 'MyApp Custom Commands' containing the 'show card', 'show greeting', and 'animate' commands.
• MyApp.app - The standalone built from MyApp.rev and MyApp.rsrc.
• MyApp.script - An AppleScript file that calls on the MyApp application to show how the 'show greeting' command is executed.

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:

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