Initial revision

author: rjohnson <rjohnson> 1998-03-26 14:45:59 (GMT)
committer: rjohnson <rjohnson> 1998-03-26 14:45:59 (GMT)
commit: 2b5738da524e944cda39e24c0a87b745a43bd8c3 (patch)
tree: 6e8c9473978f6dab66c601e911721a7bd9d70b1b /mac/AppleScript.html
parent: c6a259aeeca4814a97cf6694814c63e74e4e18fa (diff)
download: tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.zip
tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.tar.gz
tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.tar.bz2
1 files changed, 298 insertions, 0 deletions
diff --git a/mac/AppleScript.html b/mac/AppleScript.html
new file mode 100644
index 0000000..4a73fbb
--- /dev/null
+++ b/mac/AppleScript.html
@@ -0,0 +1,298 @@
+<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 delete </B><I>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>delete </B><I>scriptName</I>
+	<BR>
+	<DD>
+	This deletes the script data compiled into the script scriptName,
+	and frees up all the resources associated with it. 
+	<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>
author	rjohnson <rjohnson>	1998-03-26 14:45:59 (GMT)
committer	rjohnson <rjohnson>	1998-03-26 14:45:59 (GMT)
commit	2b5738da524e944cda39e24c0a87b745a43bd8c3 (patch)
tree	6e8c9473978f6dab66c601e911721a7bd9d70b1b /mac/AppleScript.html
parent	c6a259aeeca4814a97cf6694814c63e74e4e18fa (diff)
download	tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.zip tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.tar.gz tcl-2b5738da524e944cda39e24c0a87b745a43bd8c3.tar.bz2