Moving from Microsoft Office VBA to AppleScript:
MacTech's Guide to Making the Transition

Page Prev and Page Next buttons at bottom of the page.

April, 2007
Page 114

So to specify the actual message on which the rule (or schedule) is running, you need to get item 1 of that list. Same goes if you have selected just one message in a message list. So far so good, but you'll find that if you try

tell application "Microsoft Entourage"

     set theMsg to item 1 of current messages

end tell

you get an error: "Microsoft Entourage got an error: Can't get item 1 of current messages."

That is because current messages is one of the rare properties that requires an explicit get command, or else setting a variable to it in a separate line – which does the same thing as get, namely evaluates the reference (the list of specific messages) from which you can select your item 1.

set theMsg to item 1 of (get current messages)

--> incoming message id 120434

That works, and is what you need to remember to do every time you need item 1 of current messages.

It's exactly the same with selection, another property of the application: you need the explicit get, or a variable, to be able to work with it further. selection, or rather get selection, will return whatever (*almost) is selected in the UI, as one of the following classes: 1) a list, 2) a folder, or 3) text, depending on what is selected. Selected objects such as contacts, groups, events, tasks, notes, messages are always returned as a list, even when only a single object is selected – it is returned as a one-item list. The only exception is for a selected folder or custom view in the Folders List, which is returned as a folder (only one can be selected at a time). Selected text in a message or note (including the note sections and all text fields in contact, event and task windows) is returned as Unicode text.

You always need to check for the class of the selection to make sure you have what you want and can operate on it (you can't even get 'item 1' of the selection if it's a folder, and 'item 1' turns out to be the first character if it's text): it's very easy to miss the fact that you selected a folder rather than a message in it. (This is why using current messages instead of selection is preferable for messages: current messages works even if the folder, rather than the messages, has the focus in the UI.) So usually it's best to set a variable to selection, then check its class, and finally whatever you need from it:

tell application "Microsoft Entourage"

     set theSelection to selection

     if class of theSelection is list then

          set theObject to item 1 of theSelection

          -- will then check class of theObject for contact, etc.

     else

          beep

          display dialog "First make sure you have selected one or more " & ¬

              "contacts in the Address Book." buttons {"Cancel"} with icon 2

     end if

     --rest of script

end tell

(*Even a single calendar event selected in the Calendar returns a single-item list of the selected event. But a few odd things – mostly popup objects like mini-calendars for date selections, buttons in Print dialogs and the like, things for which Entourage has no AppleScript class – baffle the script and return an error if you try the get selection when they're selected. For most "blank" selections, though, such as a place-holder for a new calendar event which hasn't been opened yet, or an open event or contact window in which you've selected nothing at all, it will return an empty list {} or empty text "", as it should.)

One more device that needs to be mentioned is Entourage's own script menu. Entourage has had a script menu since long before the OS ever had one. It is still used by long-time Entourage users, although the system's script menu works perfectly fine for Entourage too. Entourage's script menu has two advantages over the system's script menu:

1) scripts run from it run marginally faster, but that's much less noticeable now in Tiger OS 10.4 where the system script menu no longer is handicapped by slow calls to applications, and

2) there is an excellent method for adding keyboard shortcuts to scripts. Go to the Entourage Help menu and enter "About the script menu" to see how keyboard shortcuts work.

Being able to run scripts manually several times a day via a keyboard shortcut is a great boon. But there is currently also a major disadvantage of the Entourage script menu for some scripts. Most scripts are fine, but those that have script properties (see your AppleScript books) whose values persist between script runs may have issues.