summaryrefslogtreecommitdiffstats
path: root/mac/AppleScript.html
diff options
context:
space:
mode:
Diffstat (limited to 'mac/AppleScript.html')
-rw-r--r--mac/AppleScript.html312
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>