tcl/mac/AppleScript.html

   1 <HTML>
   2
   3 <HEAD>
   4
   5 <TITLE>tclOSAScript -- OSA</TITLE>
   6
   7 </HEAD>
   8
   9 <BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF0000" ALINK="#00FF00">
  10
  11 <H2 ALIGN="CENTER">TclAppleScript Extension Command</H2>
  12
  13 <H3>NAME</H3>
  14 <DL>
  15 <DT>
  16 AppleScript - Communicate with the AppleScript OSA component to run
  17         AppleScripts from Tcl.
  18 </DL>
  19 <H3>SYNOPSIS</H3>
  20 <DL><DT>
  21 <B>AppleScript <A NAME="compile">compile</A> </B><I>?-flag value?</I> <I>scriptData1
  22            ?ScriptData2 ...?</I><I>componentName</I>
  23 <BR>
  24 <B>AppleScript <A NAME="decompile">decompile</A></B> <I>scriptName</I>
  25 <BR>
  26 <B>AppleScript <A NAME="delete">delete</A> </B><I>what scriptName</I>
  27 <BR>
  28 <B>AppleScript <A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
  29         ?scriptData2 ...?</I>
  30 <BR>
  31 <B>AppleScript <A NAME="info">info</A> </B><I>what</I>
  32 <BR>
  33 <B>AppleScript <A NAME="load">load</A></B> <I>?flag value? fileName</I>
  34 <BR>
  35 <B>AppleScript <A NAME="run">run</A></B> <I>?flag value?</I>
  36                     <I>scriptName</I>
  37 <BR>
  38 <B>AppleScript <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
  39 <BR>
  40 </DL>
  41
  42 <H3>DESCRIPTION</H3>
  43 <DL>
  44 <DT>
  45
  46
  47 This command is used to communicate with the AppleScript OSA component.
  48 You can <A HREF="#compile"><B>compile</B></A> scripts, <A
  49 HREF="#run"><B>run</B></A> compiled scripts, <A
  50 HREF="#execute"><B>execute</B></A> script data (i.e.  compile and run at a
  51 blow).  You can get script data from a compiled script (<A
  52 HREF="#decompile"><B>decompile</B></A> it), and you can <A
  53 HREF="#load"><B>load</B></A> a compiled script from the scpt resource of a
  54 file, or <A HREF="store"><B>store</B></A> one to a scpt resource.  You can
  55 also get <A HREF="#info"><B>info</B></A> on the currently available scripts
  56 and contexts.  It has the general form
  57
  58 <DL>
  59 <DT>
  60 <P>
  61 <I>AppleScript option ?arg arg ...?</I>
  62 <P>
  63 </DL>
  64 The possible sub-commands are:
  65 <P>
  66 <DL>
  67         <DT>
  68         <I>AppleScript</I> <A NAME="compile"><B>compile</A> </B><I>?-flag value?</I> <I>scriptData1
  69            ?ScriptData2 ...?</I>
  70         <BR>
  71
  72         <DD>
  73         The scriptData
  74         elements are concatenated (with a space between each), and
  75         sent to AppleScript
  76         for compilation.  There is no limitation on the size of
  77         the scriptData, beyond the available memory of the Wish interpreter.
  78         <P>
  79         If the compilation is successful, then the command will return a token
  80         that you can pass to the <A HREF="#run">"run"</A> subcommand.  If the
  81         compilation fails, then the return value will be the error message from
  82         AppleScript, and the pertinent line of code, with an "_" to indicate
  83         the place where it thinks the error occured.
  84         <P>
  85         The
  86         compilation is controlled by flag value pairs.  The available flags
  87         are:
  88         <P>
  89         <DL>
  90                 <DT>
  91                 <A NAME="first compile switch"><B>-augment Boolean</B></A>
  92                 <DD>
  93                 To be used in concert with the <A HREF="#-context">-context</A> flag.
  94                 If augment is yes,
  95                 then the scriptData augments the handlers and data already in the
  96                 script context.  If augment is no, then the scriptData replaces the
  97                 data and handlers already in the context.  The default is yes.
  98                 <P>
  99                 <!-- I'm leaving this flag out for now, since I can't seem to get the
 100                      AE manager to obey it.  Even when I hard code the value, applications
 101                      still switch to the foreground.  Oh, well...
 102
 103                 <DT>
 104                 <B>-canswitch Boolean  </B>
 105                 <DD>
 106                  If yes, then applications activated by the code in scriptData will
 107                  be allowed to switch to the foreground.  If no, then they will use
 108                  the notification manager to indicate they need attention (this
 109                  usually means they blink the Finder icon, and put a check in the
 110                  application's entry in the Finder menu).
 111                  -->
 112
 113                 <DT>
 114                 <B><A NAME="-context">-context</A> Boolean</B>
 115                 <DD>
 116                 This flag causes the code given in the scriptData to be compiled
 117                 into a "context".  In AppleScript, this is the equivalent of creating an Tcl
 118                 Namespace.  The command in this case returns the name of the context as
 119                 the its result, rather than a compiled script name.
 120                 <P>
 121                 You can store data and procedures (aka
 122                 handlers) in a script context.  Then later, you can
 123                 run other scripts in this context, and they will see all the data and
 124                 handlers that were set up with this command.  You do this by passing the
 125                 name of this context to the -context flag of the run or execute subcommands.
 126                 <P>
 127                 Unlike the straight compile command, the code compiled into a
 128                 script context is run immediatly, when it is compiled, to set up the context.
 129                 <DT>
 130                 <P>
 131                 <B>-name string</B>
 132                 <DD>
 133                 Use <I>string</I> as the name of the script or script context.  If there is
 134                 already a script
 135                 of this name, it will be discarded.  The same is true with script
 136                 contexts, unless the <I>-augment</I> flag is true.  If no name is provided, then a
 137                 unique name will be created for you.
 138                 <DT>
 139                 <P>
 140                 <B>-parent contextName  </B>
 141                 <DD>
 142                 This flag is also to be used in conjunction with the <A HREF="#-context">-context</A> flag.
 143                 <I>contextName</I> must be the name of a compiled script context.  Then
 144                 the new script context will inherit the data and handlers from the
 145                 parent context.
 146         </DL>
 147         <P>
 148         <DT>
 149         <I>AppleScript</I> <B><A NAME="decompile">decompile</A></B> <I>scriptName</I>
 150         <BR>
 151         <DD>
 152         This decompiles the script data compiled into the script scriptName,
 153         and returns the source code.
 154         <P>
 155         <DT>
 156         <I>AppleScript</I> <B><A NAME="delete">delete</A> </B><I>what scriptName</I>
 157         <BR>
 158         <DD>
 159         This deletes contexts or script data.  The allowed values for "what" are:
 160         <P>
 161         <DL>
 162             <DT>
 163                 <P>
 164             <B>context</B>
 165             <DD>
 166             This deletes the context scriptName,
 167             and frees up all the resources associated with it.
 168             <DT>
 169                 <P>
 170             <B>script</B>
 171             <DD>
 172             This deletes the script data compiled into the script scriptName,
 173             and frees up all the resources associated with it.
 174         </DL>
 175         <P>
 176         <DT>
 177         <I>AppleScript</I> <B><A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
 178         ?scriptData2 ...?</I>
 179         <BR>
 180         <DD>
 181         This compiles and runs the script in scriptData (concatenating first), and
 182         returns the results of the script execution.  It is the same as doing
 183         <I>compile</I> and then <I>run</I>, except that the compiled script is
 184         immediately discarded.
 185    <P>
 186         <DT>
 187         <I>AppleScript</I> <B><A NAME="info">info</A> </B><I>what</I>
 188         <DD>
 189         This gives info on the connection.  The allowed values for "what" are:
 190         <P>
 191         <DL>
 192             <DT>
 193                 <P>
 194             <B>contexts </B> <I>?pattern?</I>
 195             <DD>
 196             This gives the list of the script contexts that have been.
 197             If <I>pattern</I> is given, it only reports the contexts
 198             that match this pattern.
 199             <DT>
 200         <!--    <P>
 201             <B>language</B>
 202             <DD>
 203             Returns the language of this OSA component
 204             <DT>
 205         -->
 206                 <P>
 207             <B>scripts</B> <I>?pattern?</I>
 208             <DD>
 209             This returns a list of the scripts that have been compiled in the
 210             current connection.  If <I>pattern</I> is given, it only reports the
 211             script names that match this pattern.
 212         </DL>
 213         <P>
 214         <DT>
 215         <I>AppleScript</I> <B><A NAME="load">load</A></B> <I>?flag value? fileName</I>
 216         <DD>
 217         This loads compiled script data from a resource of type 'scpt' in the
 218         file fileName, and returns a token for the script data.  As with the
 219         <I>compile</I> command, the script is not actually executed.  Note that all
 220         scripts compiled with Apple's "Script Editor" are stored as script
 221         contexts.  However, unlike with the "<I>compile -context</I>" command, the <I>load</I>
 222         command does not run these scripts automatically.  If you want to set up
 223         the handlers contained in the loaded script, you must run it manually.
 224         <P>
 225         <I>load</I> takes the following flags:
 226         <P>
 227         <DL>
 228             <DT>
 229             <B>-rsrcname string</B>
 230             <DD>
 231             load a named resource of type 'scpt' using the rsrcname
 232             flag.
 233             <DT>
 234                 <P>
 235             <B>-rsrcid integer</B>
 236             <DD>
 237             load a resource by number with the rsrcid flag.
 238         </DL>
 239         <DD>
 240         <P>
 241         If neither the <I>rsrcname</I> nor the <I>rsrcid</I> flag is provided, then the load
 242         command defaults to -rsrcid = 128.  This is the resource in which
 243         Apple's Script Editor puts the script data when it writes out a
 244         compiled script.
 245         <P>
 246         <DT>
 247         <I>AppleScript</I> <B><A NAME="run">run</A></B> <I>?flag value?</I> <I>scriptName</I>
 248         <DD>
 249         This runs the script which was previously compiled into <I>scriptName</I>.  If the script
 250         runs successfully, the command returns the return value for this command,
 251         coerced to a text string.
 252         If there is an error in
 253         the script execution, then it returns the error result from the
 254         scripting component.  It accepts the following flag:
 255
 256    <DL>
 257         <DT>
 258                 <P>
 259                 <B>-context contextName</B>
 260                 <DD>
 261                 <I>contextName</I> must be a context created by a previous call to <I>compile</I> with
 262                 the -<I>context</I> flag set.  This flag causes the code given in the
 263                 <I>scriptData</I> to be run in this "context".  It will see all the data and
 264                 handlers that were set up previously.
 265    <!-- <DT>
 266                 <B>-canswitch Boolean  </B>
 267                 <DD>
 268                 If yes, then applications activated by the code
 269                 in scriptData will be allowed to switch to the foreground.  If no, then
 270                 they will use the notification manager to indicate they need attention
 271                 (this usually means they blink the Finder icon, and put a check in the
 272                 application's entry in the Finder menu). -->
 273    </DL>
 274    <P>
 275         <DT>
 276         <I>AppleScript </I> <B> <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
 277         <DD>
 278         This stores a compiled script or script context into a resource of type 'scpt' in the
 279         file fileName.
 280         <P>
 281         store takes the following flags:
 282         <P>
 283         <DL>
 284             <DT>
 285             <B>-rsrcname string</B>
 286             <DD>
 287             store to a named resource of type 'scpt' using the rsrcname
 288             flag.
 289             <DT>
 290                 <P>
 291             <B>-rsrcid integer</B>
 292             <DD>
 293             store to a numbered resource with the rsrcid flag.
 294         </DL>
 295         <P>
 296         <DD>
 297         If neither the rsrcname nor the rsrcid flag is provided, then the load
 298         command defaults to -rsrcid = 128.  Apple's Script Editor can read in files written by
 299         tclOSAScript with this setting of the <I>-rsrcid</I> flag.
 300 </DL>
 301 </DL>
 302 <H2>Notes:</H2>
 303
 304 The AppleScript command is a stopgap command to fill the place of exec
 305     on the Mac.  It is not a supported command, and will likely change
 306     as we broaden it to allow communication with other OSA languages.
 307 <H2>See Also:</H2>
 308
 309
 310 </BODY>
 311
 312 </HTML>