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