Syntax

(* 
Identify detector in Script Editor Description window with the 
package::detector-name syntax as in Apple::Email Address  for the Email 
Address Internet Address Detector.
*)
Apple::Email Address  -- Name of detector to handle
New OutLook Express Message Recipient  (* string that will appear in 
contextual menu *)
(*
end of Script Editor Description Window phrases
*)
(*
define the handle detection routine ; it has a parameter of data type 
record that contains the detected text
*)
on handle detection theDetector
   --actual script with 'handle detection' handler, statements, and code ...
end handle detection

Dictionary commands

handle detection (from the Apple Data Detectors Scripting osax)

This event is fired when the user chooses the action containing this routine in the contextual menu. For example, the user might select and Control-click the text "user@hersite.com." The resulting contextual menu may have a submenu displaying the title "New OutLook Express Message Recipient." If the user chooses this title in the contextual menu, then the script action associated with that title is executed and it calls its handle detection routine. This routine stores the detector instance, an object of type record, in the handle-detection routine's parameter. An example code snippet is: on handle detection theDetector...end handle detection (theDetector is the parameter or detector instance). For example, an email-related script could find out the selected email address with the code:

detected text of theDetector

(which might evaluate to a string such as "user@hersite.com"). The functionality you want this action script to have is defined in the handle detection routine, including calling other functions.

Dictionary classes

detector instance (from the Apple Data Detectors Scripting osax)

This class represents a record type sent as a parameter to the handle detection routine of your action scripts. The detector instance record has the following properties:

name (string)

This is the name of the detector that detected the text, as in "Apple::Email Address."

detected text (string)

This is the string that was detected by the detector identified in the name property, as in "theuser@hersite.com."

sub detections (list)

sub detections is a property of type list; each item of this list is data of type record. Not very many detectors return anything but an empty list for this property. Some detectors return a list of record objects. Consider, for example, the Apple US Geographic::USCityState detector. If you wrote an action script for this detector, then you could obtain the detected city/state string (e.g., "San Francisco, CA") by using the code (if the variable theDetector was the parameter for the handle detections routine):

detected text of theDetector

Let's say the string the user had selected was "San Francisco, CA." The property

sub detections of theDetector

would contain a list of records that looks like this: { {name: "theCity",detected text:"San Francisco"}, {name: "theSeparator", detected text: ","}, {name: "theState", detected text: "CA"} }. Each of the three records in this sub detections list contains two properties—name and detected text—with strings for the property values. A list of records is certainly difficult to look at. Another way to conceive of sub detections is as an array that contains associative arrays as array elements.

Examples

on handle detection theDetector
   try
      set emailAdd to detected text of theDetector   (* store the detected text in a variable *)
      set theSubject to the text returned of¬
      (display dialog "Please enter the email subject:"¬
      default answer "" buttons {"Okay", "Cancel"}¬ 
            default button 1)
         set theContent to the text returned of¬
         (display dialog "Please¬ 
   enter the message content:" default answer  "" buttons {"Okay", ¬ 
            "Cancel"} default button 1)
      tell application "Outlook Express"
         activate
         make new draft window with properties {subject:theSubject,¬ 
         content:theContent, to recipients:emailAdd} (* make a new 
         email-message window *)
      end tell
      on error errMessage
      display dialog "You could not create a new email message" &¬
      " due to the following  error:" & errMessage
   end try
end handle detection

You have to install any new detectors that you download by using the Apple Data Detectors control panel. Use the File Install Detector File... command from the control panel's window. Use the File Install Action File... command to install the AppleScripts or actions that you write for Apple Data Detectors. Once installed, the actions are kept in the directory startup disk:System Folder:Apple Data Detectors:Actions.

When you write an ADD action, you have to include certain information in the Script Editor Description field, or the ADD control panel will not install the action. The Description field is a text area at the top of the Script Editor window (Chapter 2 is devoted to Script Editor). This information includes the detector that is used to handle the action, as in Apple::HTTP for the HTTP detector, and the action title that the contextual menu will display. The contextual menu displays when the user Control-clicks some selected text that contains data which ADD looks for, such as a web site address. The next example shows the text that you must add to the Script Editor Description field for a script that opens a web site in Internet Explorer:

(* the first two lines go in the Script Editor Description field *)
Apple::HTTP  -- Name of detector to handle
Get website in IE4.5  -- Contextual menu string
on handle detection decRecord
   set theURL to detected text of decRecord
   tell application "Internet Explorer 4.5"
      Activate
      OpenURL theURL
   end tell
end handle detection

Table 20-1 shows the detector names that scripters use with their action scripts. The first four detector names identify the detectors that are a part of the Internet Address Detectors package; the last two are part of the U.S. Geographic Detectors package.

Table 20-1. Detector Packages and Names

Detector Name	Package
Apple::FTP	Internet Address Detectors
Apple::Host	Internet Address Detectors
Apple::HTTP	Internet Address Detectors
Apple::Newsgroup	Internet Address Detectors
Apple US Geographic::USCityState	U.S. Geographic Detectors
Apple US Geographic::USState	U.S. Geographic Detectors

The AppleScript statements that you include outside of the handle detection subroutine do not run when the action script executes, unless you include them in another routine that handle detection calls. For example, the statement:

display dialog "I am called in handle detection"

executes because it is part of a doDisplay function that is called by handle detection:

On handle detection decRecord
   Set theSel to detected text of decRecord
   Display dialog "here's what you selected: " & theSel¬
   doDisplay(  )
End handle detection

On doDisplay(  )
   display dialog "I am called in handle detection"
End doDisplay