os/persistentdata/persistentstorage/sqlite3api/TEST/TCL/tcldistribution/mac/AppleScript.html
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/sqlite3api/TEST/TCL/tcldistribution/mac/AppleScript.html Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,312 @@
1.4 +<HTML>
1.5 +
1.6 +<HEAD>
1.7 +
1.8 +<TITLE>tclOSAScript -- OSA</TITLE>
1.9 +
1.10 +</HEAD>
1.11 +
1.12 +<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF0000" ALINK="#00FF00">
1.13 +
1.14 +<H2 ALIGN="CENTER">TclAppleScript Extension Command</H2>
1.15 +
1.16 +<H3>NAME</H3>
1.17 +<DL>
1.18 +<DT>
1.19 +AppleScript - Communicate with the AppleScript OSA component to run
1.20 + AppleScripts from Tcl.
1.21 +</DL>
1.22 +<H3>SYNOPSIS</H3>
1.23 +<DL><DT>
1.24 +<B>AppleScript <A NAME="compile">compile</A> </B><I>?-flag value?</I> <I>scriptData1
1.25 + ?ScriptData2 ...?</I><I>componentName</I>
1.26 +<BR>
1.27 +<B>AppleScript <A NAME="decompile">decompile</A></B> <I>scriptName</I>
1.28 +<BR>
1.29 +<B>AppleScript <A NAME="delete">delete</A> </B><I>what scriptName</I>
1.30 +<BR>
1.31 +<B>AppleScript <A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
1.32 + ?scriptData2 ...?</I>
1.33 +<BR>
1.34 +<B>AppleScript <A NAME="info">info</A> </B><I>what</I>
1.35 +<BR>
1.36 +<B>AppleScript <A NAME="load">load</A></B> <I>?flag value? fileName</I>
1.37 +<BR>
1.38 +<B>AppleScript <A NAME="run">run</A></B> <I>?flag value?</I>
1.39 + <I>scriptName</I>
1.40 +<BR>
1.41 +<B>AppleScript <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
1.42 +<BR>
1.43 +</DL>
1.44 +
1.45 +<H3>DESCRIPTION</H3>
1.46 +<DL>
1.47 +<DT>
1.48 +
1.49 +
1.50 +This command is used to communicate with the AppleScript OSA component.
1.51 +You can <A HREF="#compile"><B>compile</B></A> scripts, <A
1.52 +HREF="#run"><B>run</B></A> compiled scripts, <A
1.53 +HREF="#execute"><B>execute</B></A> script data (i.e. compile and run at a
1.54 +blow). You can get script data from a compiled script (<A
1.55 +HREF="#decompile"><B>decompile</B></A> it), and you can <A
1.56 +HREF="#load"><B>load</B></A> a compiled script from the scpt resource of a
1.57 +file, or <A HREF="store"><B>store</B></A> one to a scpt resource. You can
1.58 +also get <A HREF="#info"><B>info</B></A> on the currently available scripts
1.59 +and contexts. It has the general form
1.60 +
1.61 +<DL>
1.62 +<DT>
1.63 +<P>
1.64 +<I>AppleScript option ?arg arg ...?</I>
1.65 +<P>
1.66 +</DL>
1.67 +The possible sub-commands are:
1.68 +<P>
1.69 +<DL>
1.70 + <DT>
1.71 + <I>AppleScript</I> <A NAME="compile"><B>compile</A> </B><I>?-flag value?</I> <I>scriptData1
1.72 + ?ScriptData2 ...?</I>
1.73 + <BR>
1.74 +
1.75 + <DD>
1.76 + The scriptData
1.77 + elements are concatenated (with a space between each), and
1.78 + sent to AppleScript
1.79 + for compilation. There is no limitation on the size of
1.80 + the scriptData, beyond the available memory of the Wish interpreter.
1.81 + <P>
1.82 + If the compilation is successful, then the command will return a token
1.83 + that you can pass to the <A HREF="#run">"run"</A> subcommand. If the
1.84 + compilation fails, then the return value will be the error message from
1.85 + AppleScript, and the pertinent line of code, with an "_" to indicate
1.86 + the place where it thinks the error occured.
1.87 + <P>
1.88 + The
1.89 + compilation is controlled by flag value pairs. The available flags
1.90 + are:
1.91 + <P>
1.92 + <DL>
1.93 + <DT>
1.94 + <A NAME="first compile switch"><B>-augment Boolean</B></A>
1.95 + <DD>
1.96 + To be used in concert with the <A HREF="#-context">-context</A> flag.
1.97 + If augment is yes,
1.98 + then the scriptData augments the handlers and data already in the
1.99 + script context. If augment is no, then the scriptData replaces the
1.100 + data and handlers already in the context. The default is yes.
1.101 + <P>
1.102 + <!-- I'm leaving this flag out for now, since I can't seem to get the
1.103 + AE manager to obey it. Even when I hard code the value, applications
1.104 + still switch to the foreground. Oh, well...
1.105 +
1.106 + <DT>
1.107 + <B>-canswitch Boolean </B>
1.108 + <DD>
1.109 + If yes, then applications activated by the code in scriptData will
1.110 + be allowed to switch to the foreground. If no, then they will use
1.111 + the notification manager to indicate they need attention (this
1.112 + usually means they blink the Finder icon, and put a check in the
1.113 + application's entry in the Finder menu).
1.114 + -->
1.115 +
1.116 + <DT>
1.117 + <B><A NAME="-context">-context</A> Boolean</B>
1.118 + <DD>
1.119 + This flag causes the code given in the scriptData to be compiled
1.120 + into a "context". In AppleScript, this is the equivalent of creating an Tcl
1.121 + Namespace. The command in this case returns the name of the context as
1.122 + the its result, rather than a compiled script name.
1.123 + <P>
1.124 + You can store data and procedures (aka
1.125 + handlers) in a script context. Then later, you can
1.126 + run other scripts in this context, and they will see all the data and
1.127 + handlers that were set up with this command. You do this by passing the
1.128 + name of this context to the -context flag of the run or execute subcommands.
1.129 + <P>
1.130 + Unlike the straight compile command, the code compiled into a
1.131 + script context is run immediatly, when it is compiled, to set up the context.
1.132 + <DT>
1.133 + <P>
1.134 + <B>-name string</B>
1.135 + <DD>
1.136 + Use <I>string</I> as the name of the script or script context. If there is
1.137 + already a script
1.138 + of this name, it will be discarded. The same is true with script
1.139 + contexts, unless the <I>-augment</I> flag is true. If no name is provided, then a
1.140 + unique name will be created for you.
1.141 + <DT>
1.142 + <P>
1.143 + <B>-parent contextName </B>
1.144 + <DD>
1.145 + This flag is also to be used in conjunction with the <A HREF="#-context">-context</A> flag.
1.146 + <I>contextName</I> must be the name of a compiled script context. Then
1.147 + the new script context will inherit the data and handlers from the
1.148 + parent context.
1.149 + </DL>
1.150 + <P>
1.151 + <DT>
1.152 + <I>AppleScript</I> <B><A NAME="decompile">decompile</A></B> <I>scriptName</I>
1.153 + <BR>
1.154 + <DD>
1.155 + This decompiles the script data compiled into the script scriptName,
1.156 + and returns the source code.
1.157 + <P>
1.158 + <DT>
1.159 + <I>AppleScript</I> <B><A NAME="delete">delete</A> </B><I>what scriptName</I>
1.160 + <BR>
1.161 + <DD>
1.162 + This deletes contexts or script data. The allowed values for "what" are:
1.163 + <P>
1.164 + <DL>
1.165 + <DT>
1.166 + <P>
1.167 + <B>context</B>
1.168 + <DD>
1.169 + This deletes the context scriptName,
1.170 + and frees up all the resources associated with it.
1.171 + <DT>
1.172 + <P>
1.173 + <B>script</B>
1.174 + <DD>
1.175 + This deletes the script data compiled into the script scriptName,
1.176 + and frees up all the resources associated with it.
1.177 + </DL>
1.178 + <P>
1.179 + <DT>
1.180 + <I>AppleScript</I> <B><A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1
1.181 + ?scriptData2 ...?</I>
1.182 + <BR>
1.183 + <DD>
1.184 + This compiles and runs the script in scriptData (concatenating first), and
1.185 + returns the results of the script execution. It is the same as doing
1.186 + <I>compile</I> and then <I>run</I>, except that the compiled script is
1.187 + immediately discarded.
1.188 + <P>
1.189 + <DT>
1.190 + <I>AppleScript</I> <B><A NAME="info">info</A> </B><I>what</I>
1.191 + <DD>
1.192 + This gives info on the connection. The allowed values for "what" are:
1.193 + <P>
1.194 + <DL>
1.195 + <DT>
1.196 + <P>
1.197 + <B>contexts </B> <I>?pattern?</I>
1.198 + <DD>
1.199 + This gives the list of the script contexts that have been.
1.200 + If <I>pattern</I> is given, it only reports the contexts
1.201 + that match this pattern.
1.202 + <DT>
1.203 + <!-- <P>
1.204 + <B>language</B>
1.205 + <DD>
1.206 + Returns the language of this OSA component
1.207 + <DT>
1.208 + -->
1.209 + <P>
1.210 + <B>scripts</B> <I>?pattern?</I>
1.211 + <DD>
1.212 + This returns a list of the scripts that have been compiled in the
1.213 + current connection. If <I>pattern</I> is given, it only reports the
1.214 + script names that match this pattern.
1.215 + </DL>
1.216 + <P>
1.217 + <DT>
1.218 + <I>AppleScript</I> <B><A NAME="load">load</A></B> <I>?flag value? fileName</I>
1.219 + <DD>
1.220 + This loads compiled script data from a resource of type 'scpt' in the
1.221 + file fileName, and returns a token for the script data. As with the
1.222 + <I>compile</I> command, the script is not actually executed. Note that all
1.223 + scripts compiled with Apple's "Script Editor" are stored as script
1.224 + contexts. However, unlike with the "<I>compile -context</I>" command, the <I>load</I>
1.225 + command does not run these scripts automatically. If you want to set up
1.226 + the handlers contained in the loaded script, you must run it manually.
1.227 + <P>
1.228 + <I>load</I> takes the following flags:
1.229 + <P>
1.230 + <DL>
1.231 + <DT>
1.232 + <B>-rsrcname string</B>
1.233 + <DD>
1.234 + load a named resource of type 'scpt' using the rsrcname
1.235 + flag.
1.236 + <DT>
1.237 + <P>
1.238 + <B>-rsrcid integer</B>
1.239 + <DD>
1.240 + load a resource by number with the rsrcid flag.
1.241 + </DL>
1.242 + <DD>
1.243 + <P>
1.244 + If neither the <I>rsrcname</I> nor the <I>rsrcid</I> flag is provided, then the load
1.245 + command defaults to -rsrcid = 128. This is the resource in which
1.246 + Apple's Script Editor puts the script data when it writes out a
1.247 + compiled script.
1.248 + <P>
1.249 + <DT>
1.250 + <I>AppleScript</I> <B><A NAME="run">run</A></B> <I>?flag value?</I> <I>scriptName</I>
1.251 + <DD>
1.252 + This runs the script which was previously compiled into <I>scriptName</I>. If the script
1.253 + runs successfully, the command returns the return value for this command,
1.254 + coerced to a text string.
1.255 + If there is an error in
1.256 + the script execution, then it returns the error result from the
1.257 + scripting component. It accepts the following flag:
1.258 +
1.259 + <DL>
1.260 + <DT>
1.261 + <P>
1.262 + <B>-context contextName</B>
1.263 + <DD>
1.264 + <I>contextName</I> must be a context created by a previous call to <I>compile</I> with
1.265 + the -<I>context</I> flag set. This flag causes the code given in the
1.266 + <I>scriptData</I> to be run in this "context". It will see all the data and
1.267 + handlers that were set up previously.
1.268 + <!-- <DT>
1.269 + <B>-canswitch Boolean </B>
1.270 + <DD>
1.271 + If yes, then applications activated by the code
1.272 + in scriptData will be allowed to switch to the foreground. If no, then
1.273 + they will use the notification manager to indicate they need attention
1.274 + (this usually means they blink the Finder icon, and put a check in the
1.275 + application's entry in the Finder menu). -->
1.276 + </DL>
1.277 + <P>
1.278 + <DT>
1.279 + <I>AppleScript </I> <B> <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I>
1.280 + <DD>
1.281 + This stores a compiled script or script context into a resource of type 'scpt' in the
1.282 + file fileName.
1.283 + <P>
1.284 + store takes the following flags:
1.285 + <P>
1.286 + <DL>
1.287 + <DT>
1.288 + <B>-rsrcname string</B>
1.289 + <DD>
1.290 + store to a named resource of type 'scpt' using the rsrcname
1.291 + flag.
1.292 + <DT>
1.293 + <P>
1.294 + <B>-rsrcid integer</B>
1.295 + <DD>
1.296 + store to a numbered resource with the rsrcid flag.
1.297 + </DL>
1.298 + <P>
1.299 + <DD>
1.300 + If neither the rsrcname nor the rsrcid flag is provided, then the load
1.301 + command defaults to -rsrcid = 128. Apple's Script Editor can read in files written by
1.302 + tclOSAScript with this setting of the <I>-rsrcid</I> flag.
1.303 +</DL>
1.304 +</DL>
1.305 +<H2>Notes:</H2>
1.306 +
1.307 +The AppleScript command is a stopgap command to fill the place of exec
1.308 + on the Mac. It is not a supported command, and will likely change
1.309 + as we broaden it to allow communication with other OSA languages.
1.310 +<H2>See Also:</H2>
1.311 +
1.312 +
1.313 +</BODY>
1.314 +
1.315 +</HTML>