diff options
Diffstat (limited to 'mac/AppleScript.html')
| -rw-r--r-- | mac/AppleScript.html | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/mac/AppleScript.html b/mac/AppleScript.html new file mode 100644 index 0000000..32b2e9f --- /dev/null +++ b/mac/AppleScript.html @@ -0,0 +1,312 @@ +<HTML> + +<HEAD> + +<TITLE>tclOSAScript -- OSA</TITLE> + +</HEAD> + +<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF0000" ALINK="#00FF00"> + +<H2 ALIGN="CENTER">TclAppleScript Extension Command</H2> + +<H3>NAME</H3> +<DL> +<DT> +AppleScript - Communicate with the AppleScript OSA component to run + AppleScripts from Tcl. +</DL> +<H3>SYNOPSIS</H3> +<DL><DT> +<B>AppleScript <A NAME="compile">compile</A> </B><I>?-flag value?</I> <I>scriptData1 + ?ScriptData2 ...?</I><I>componentName</I> +<BR> +<B>AppleScript <A NAME="decompile">decompile</A></B> <I>scriptName</I> +<BR> +<B>AppleScript <A NAME="delete">delete</A> </B><I>what scriptName</I> +<BR> +<B>AppleScript <A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1 + ?scriptData2 ...?</I> +<BR> +<B>AppleScript <A NAME="info">info</A> </B><I>what</I> +<BR> +<B>AppleScript <A NAME="load">load</A></B> <I>?flag value? fileName</I> +<BR> +<B>AppleScript <A NAME="run">run</A></B> <I>?flag value?</I> + <I>scriptName</I> +<BR> +<B>AppleScript <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I> +<BR> +</DL> + +<H3>DESCRIPTION</H3> +<DL> +<DT> + + +This command is used to communicate with the AppleScript OSA component. +You can <A HREF="#compile"><B>compile</B></A> scripts, <A +HREF="#run"><B>run</B></A> compiled scripts, <A +HREF="#execute"><B>execute</B></A> script data (i.e. compile and run at a +blow). You can get script data from a compiled script (<A +HREF="#decompile"><B>decompile</B></A> it), and you can <A +HREF="#load"><B>load</B></A> a compiled script from the scpt resource of a +file, or <A HREF="store"><B>store</B></A> one to a scpt resource. You can +also get <A HREF="#info"><B>info</B></A> on the currently available scripts +and contexts. It has the general form + +<DL> +<DT> +<P> +<I>AppleScript option ?arg arg ...?</I> +<P> +</DL> +The possible sub-commands are: +<P> +<DL> + <DT> + <I>AppleScript</I> <A NAME="compile"><B>compile</A> </B><I>?-flag value?</I> <I>scriptData1 + ?ScriptData2 ...?</I> + <BR> + + <DD> + The scriptData + elements are concatenated (with a space between each), and + sent to AppleScript + for compilation. There is no limitation on the size of + the scriptData, beyond the available memory of the Wish interpreter. + <P> + If the compilation is successful, then the command will return a token + that you can pass to the <A HREF="#run">"run"</A> subcommand. If the + compilation fails, then the return value will be the error message from + AppleScript, and the pertinent line of code, with an "_" to indicate + the place where it thinks the error occured. + <P> + The + compilation is controlled by flag value pairs. The available flags + are: + <P> + <DL> + <DT> + <A NAME="first compile switch"><B>-augment Boolean</B></A> + <DD> + To be used in concert with the <A HREF="#-context">-context</A> flag. + If augment is yes, + then the scriptData augments the handlers and data already in the + script context. If augment is no, then the scriptData replaces the + data and handlers already in the context. The default is yes. + <P> + <!-- I'm leaving this flag out for now, since I can't seem to get the + AE manager to obey it. Even when I hard code the value, applications + still switch to the foreground. Oh, well... + + <DT> + <B>-canswitch Boolean </B> + <DD> + If yes, then applications activated by the code in scriptData will + be allowed to switch to the foreground. If no, then they will use + the notification manager to indicate they need attention (this + usually means they blink the Finder icon, and put a check in the + application's entry in the Finder menu). + --> + + <DT> + <B><A NAME="-context">-context</A> Boolean</B> + <DD> + This flag causes the code given in the scriptData to be compiled + into a "context". In AppleScript, this is the equivalent of creating an Tcl + Namespace. The command in this case returns the name of the context as + the its result, rather than a compiled script name. + <P> + You can store data and procedures (aka + handlers) in a script context. Then later, you can + run other scripts in this context, and they will see all the data and + handlers that were set up with this command. You do this by passing the + name of this context to the -context flag of the run or execute subcommands. + <P> + Unlike the straight compile command, the code compiled into a + script context is run immediatly, when it is compiled, to set up the context. + <DT> + <P> + <B>-name string</B> + <DD> + Use <I>string</I> as the name of the script or script context. If there is + already a script + of this name, it will be discarded. The same is true with script + contexts, unless the <I>-augment</I> flag is true. If no name is provided, then a + unique name will be created for you. + <DT> + <P> + <B>-parent contextName </B> + <DD> + This flag is also to be used in conjunction with the <A HREF="#-context">-context</A> flag. + <I>contextName</I> must be the name of a compiled script context. Then + the new script context will inherit the data and handlers from the + parent context. + </DL> + <P> + <DT> + <I>AppleScript</I> <B><A NAME="decompile">decompile</A></B> <I>scriptName</I> + <BR> + <DD> + This decompiles the script data compiled into the script scriptName, + and returns the source code. + <P> + <DT> + <I>AppleScript</I> <B><A NAME="delete">delete</A> </B><I>what scriptName</I> + <BR> + <DD> + This deletes contexts or script data. The allowed values for "what" are: + <P> + <DL> + <DT> + <P> + <B>context</B> + <DD> + This deletes the context scriptName, + and frees up all the resources associated with it. + <DT> + <P> + <B>script</B> + <DD> + This deletes the script data compiled into the script scriptName, + and frees up all the resources associated with it. + </DL> + <P> + <DT> + <I>AppleScript</I> <B><A NAME="execute">execute</A> </B><I>?flags value?</I> <I>scriptData1 + ?scriptData2 ...?</I> + <BR> + <DD> + This compiles and runs the script in scriptData (concatenating first), and + returns the results of the script execution. It is the same as doing + <I>compile</I> and then <I>run</I>, except that the compiled script is + immediately discarded. + <P> + <DT> + <I>AppleScript</I> <B><A NAME="info">info</A> </B><I>what</I> + <DD> + This gives info on the connection. The allowed values for "what" are: + <P> + <DL> + <DT> + <P> + <B>contexts </B> <I>?pattern?</I> + <DD> + This gives the list of the script contexts that have been. + If <I>pattern</I> is given, it only reports the contexts + that match this pattern. + <DT> + <!-- <P> + <B>language</B> + <DD> + Returns the language of this OSA component + <DT> + --> + <P> + <B>scripts</B> <I>?pattern?</I> + <DD> + This returns a list of the scripts that have been compiled in the + current connection. If <I>pattern</I> is given, it only reports the + script names that match this pattern. + </DL> + <P> + <DT> + <I>AppleScript</I> <B><A NAME="load">load</A></B> <I>?flag value? fileName</I> + <DD> + This loads compiled script data from a resource of type 'scpt' in the + file fileName, and returns a token for the script data. As with the + <I>compile</I> command, the script is not actually executed. Note that all + scripts compiled with Apple's "Script Editor" are stored as script + contexts. However, unlike with the "<I>compile -context</I>" command, the <I>load</I> + command does not run these scripts automatically. If you want to set up + the handlers contained in the loaded script, you must run it manually. + <P> + <I>load</I> takes the following flags: + <P> + <DL> + <DT> + <B>-rsrcname string</B> + <DD> + load a named resource of type 'scpt' using the rsrcname + flag. + <DT> + <P> + <B>-rsrcid integer</B> + <DD> + load a resource by number with the rsrcid flag. + </DL> + <DD> + <P> + If neither the <I>rsrcname</I> nor the <I>rsrcid</I> flag is provided, then the load + command defaults to -rsrcid = 128. This is the resource in which + Apple's Script Editor puts the script data when it writes out a + compiled script. + <P> + <DT> + <I>AppleScript</I> <B><A NAME="run">run</A></B> <I>?flag value?</I> <I>scriptName</I> + <DD> + This runs the script which was previously compiled into <I>scriptName</I>. If the script + runs successfully, the command returns the return value for this command, + coerced to a text string. + If there is an error in + the script execution, then it returns the error result from the + scripting component. It accepts the following flag: + + <DL> + <DT> + <P> + <B>-context contextName</B> + <DD> + <I>contextName</I> must be a context created by a previous call to <I>compile</I> with + the -<I>context</I> flag set. This flag causes the code given in the + <I>scriptData</I> to be run in this "context". It will see all the data and + handlers that were set up previously. + <!-- <DT> + <B>-canswitch Boolean </B> + <DD> + If yes, then applications activated by the code + in scriptData will be allowed to switch to the foreground. If no, then + they will use the notification manager to indicate they need attention + (this usually means they blink the Finder icon, and put a check in the + application's entry in the Finder menu). --> + </DL> + <P> + <DT> + <I>AppleScript </I> <B> <A NAME="store">store</A></B> <I>?flag value? scriptName fileName</I> + <DD> + This stores a compiled script or script context into a resource of type 'scpt' in the + file fileName. + <P> + store takes the following flags: + <P> + <DL> + <DT> + <B>-rsrcname string</B> + <DD> + store to a named resource of type 'scpt' using the rsrcname + flag. + <DT> + <P> + <B>-rsrcid integer</B> + <DD> + store to a numbered resource with the rsrcid flag. + </DL> + <P> + <DD> + If neither the rsrcname nor the rsrcid flag is provided, then the load + command defaults to -rsrcid = 128. Apple's Script Editor can read in files written by + tclOSAScript with this setting of the <I>-rsrcid</I> flag. +</DL> +</DL> +<H2>Notes:</H2> + +The AppleScript command is a stopgap command to fill the place of exec + on the Mac. It is not a supported command, and will likely change + as we broaden it to allow communication with other OSA languages. +<H2>See Also:</H2> + + +</BODY> + +</HTML> |