os/persistentdata/persistentstorage/sqlite3api/TEST/TCL/tcldistribution/mac/AppleScript.html
5 <TITLE>tclOSAScript -- OSA</TITLE>
9 <BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF0000" ALINK="#00FF00">
11 <H2 ALIGN="CENTER">TclAppleScript Extension Command</H2>
16 AppleScript - Communicate with the AppleScript OSA component to run
17 AppleScripts from Tcl.
21 <B>AppleScript <A NAME="compile">compile</A> </B><I>?-flag value?</I> <I>scriptData1
22 ?ScriptData2 ...?</I><I>componentName</I>
24 <B>AppleScript <A NAME="decompile">decompile</A></B> <I>scriptName</I>
26 <B>AppleScript <A NAME="delete">delete</A> </B><I>what scriptName</I>
28 <B>AppleScript <A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
31 <B>AppleScript <A NAME="info">info</A> </B><I>what</I>
33 <B>AppleScript <A NAME="load">load</A></B> <I>?flag value? fileName</I>
35 <B>AppleScript <A NAME="run">run</A></B> <I>?flag value?</I>
38 <B>AppleScript <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
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
61 <I>AppleScript option ?arg arg ...?</I>
64 The possible sub-commands are:
68 <I>AppleScript</I> <A NAME="compile"><B>compile</A> </B><I>?-flag value?</I> <I>scriptData1
74 elements are concatenated (with a space between each), and
76 for compilation. There is no limitation on the size of
77 the scriptData, beyond the available memory of the Wish interpreter.
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.
86 compilation is controlled by flag value pairs. The available flags
91 <A NAME="first compile switch"><B>-augment Boolean</B></A>
93 To be used in concert with the <A HREF="#-context">-context</A> flag.
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.
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...
104 <B>-canswitch Boolean </B>
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).
114 <B><A NAME="-context">-context</A> Boolean</B>
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.
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.
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.
133 Use <I>string</I> as the name of the script or script context. If there is
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.
140 <B>-parent contextName </B>
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
149 <I>AppleScript</I> <B><A NAME="decompile">decompile</A></B> <I>scriptName</I>
152 This decompiles the script data compiled into the script scriptName,
153 and returns the source code.
156 <I>AppleScript</I> <B><A NAME="delete">delete</A> </B><I>what scriptName</I>
159 This deletes contexts or script data. The allowed values for "what" are:
166 This deletes the context scriptName,
167 and frees up all the resources associated with it.
172 This deletes the script data compiled into the script scriptName,
173 and frees up all the resources associated with it.
177 <I>AppleScript</I> <B><A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
178 ?scriptData2 ...?</I>
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.
187 <I>AppleScript</I> <B><A NAME="info">info</A> </B><I>what</I>
189 This gives info on the connection. The allowed values for "what" are:
194 <B>contexts </B> <I>?pattern?</I>
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.
203 Returns the language of this OSA component
207 <B>scripts</B> <I>?pattern?</I>
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.
215 <I>AppleScript</I> <B><A NAME="load">load</A></B> <I>?flag value? fileName</I>
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.
225 <I>load</I> takes the following flags:
229 <B>-rsrcname string</B>
231 load a named resource of type 'scpt' using the rsrcname
235 <B>-rsrcid integer</B>
237 load a resource by number with the rsrcid flag.
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
247 <I>AppleScript</I> <B><A NAME="run">run</A></B> <I>?flag value?</I> <I>scriptName</I>
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:
259 <B>-context contextName</B>
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.
266 <B>-canswitch Boolean </B>
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). -->
276 <I>AppleScript </I> <B> <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
278 This stores a compiled script or script context into a resource of type 'scpt' in the
281 store takes the following flags:
285 <B>-rsrcname string</B>
287 store to a named resource of type 'scpt' using the rsrcname
291 <B>-rsrcid integer</B>
293 store to a numbered resource with the rsrcid flag.
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.
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.