The process of selecting a message is not fully explained in the Microsoft Entourage dictionary. How do you specify the selected message(s) on which you want to run a script, and how do you specify the message on which the running rule should operate? You use the current messages application property, which is always a list of messages.
To specify the actual message on which the rule (or schedule) is running, you need to get
item 1
of that list. The same goes if you have selected just one message in a message list. However, if you try the following:
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.
This is because the current messages property 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 the get command; it evaluates the reference (the list of specific messages) from which you can select
item 1.
set theMsg to item 1 of (get current messages) --> incoming message id 120434
It works. You must use it when you need
item 1
of current messages.
It's exactly the same with selection, which is another property of the application. You need the explicit get command, or a variable, to be able to work with it further.
The statement
get selection
will return nearly anything that is selected in the UI as one of the following classes: a list, a folder, or text, depending on what is selected. Selected objects such as contacts, groups, events, tasks, notes, and messages are always returned as a list, even when only a single object is selected. Then it's 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 object (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.
Note Even a single event selected in the Calendar returns a single-item list of the selected event. But a few minor things, mostly pop-up objects like mini-calendars for date selections, buttons in Print dialog boxes, and others for which Entourage
has no AppleScript class, baffle the script and return an error if you try the
get
selection
statement when they're selected. For most "blank" selections, though, such as a placeholder for a new calendar event that hasn't been opened yet, an open event, or contact window in which you've selected nothing at all, it will return an empty list
{}
or empty text,
"".)
You always need to check for the class of the selection to make sure that you have what you want and can operate on it. (For example, if you're trying to get a folder, it is not possible to get
item 1
of the selection, and if you're trying to get text,
item 1
will be the first character.) It's very easy to miss the fact that you selected a folder rather than a message in it. This is why using the current messages property instead of the selection property 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 perform the operation you want to perform on the selection.
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