84 lines
3.5 KiB
TeX
84 lines
3.5 KiB
TeX
|
\section{\module{aetools} ---
|
||
|
|
OSA client support}
|
||
|
|
|
||
|
|
\declaremodule{standard}{aetools}
|
||
|
|
\platform{Mac}
|
||
|
|
%\moduleauthor{Jack Jansen?}{email}
|
||
|
|
\modulesynopsis{Basic support for sending Apple Events}
|
||
|
|
\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}
|
||
|
|
|
||
|
|
|
||
|
|
The \module{aetools} module contains the basic functionality
|
||
|
|
on which Python AppleScript client support is built. It also
|
||
|
|
imports and re-exports the core functionality of the
|
||
|
|
\module{aetypes} and \module{aepack} modules. The stub packages
|
||
|
|
generated by \module{gensuitemodule} import the relevant
|
||
|
|
portions of \module{aetools}, so usually you do not need to
|
||
|
|
import it yourself. The exception to this is when you
|
||
|
|
cannot use a generated suite package and need lower-level
|
||
|
|
access to scripting.
|
||
|
|
|
||
|
|
The \module{aetools} module itself uses the AppleEvent support
|
||
|
|
provided by the \module{Carbon.AE} module. This has one drawback:
|
||
|
|
you need access to the window manager, see section \ref{osx-gui-scripts}
|
||
|
|
for details. This restriction may be lifted in future releases.
|
||
|
|
|
||
|
|
|
||
|
|
The \module{aetools} module defines the following functions:
|
||
|
|
|
||
|
|
\begin{funcdesc}{packevent}{ae, parameters, attributes}
|
||
|
|
Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
|
||
|
|
object. \code{parameters} and \code{attributes} are
|
||
|
|
dictionaries mapping 4-character OSA parameter keys to Python objects. The
|
||
|
|
objects are packed using \code{aepack.pack()}.
|
||
|
|
\end{funcdesc}
|
||
|
|
|
||
|
|
\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
|
||
|
|
Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
|
||
|
|
The function returns the parameter dictionary and the attribute dictionary.
|
||
|
|
The \code{formodulename} argument is used by generated stub packages to
|
||
|
|
control where AppleScript classes are looked up.
|
||
|
|
\end{funcdesc}
|
||
|
|
|
||
|
|
\begin{funcdesc}{keysubst}{arguments, keydict}
|
||
|
|
Converts a Python keyword argument dictionary \code{arguments} to
|
||
|
|
the format required by \code{packevent} by replacing the keys,
|
||
|
|
which are Python identifiers, by the four-character OSA keys according
|
||
|
|
to the mapping specified in \code{keydict}. Used by the generated suite
|
||
|
|
packages.
|
||
|
|
\end{funcdesc}
|
||
|
|
|
||
|
|
\begin{funcdesc}{enumsubst}{arguments, key, edict}
|
||
|
|
If the \code{arguments} dictionary contains an entry for \code{key}
|
||
|
|
convert the value for that entry according to dictionary \code{edict}.
|
||
|
|
This converts human-readable Python enumeration names to the OSA 4-character
|
||
|
|
codes.
|
||
|
|
Used by the generated suite
|
||
|
|
packages.
|
||
|
|
\end{funcdesc}
|
||
|
|
|
||
|
|
The \module{aetools} module defines the following class:
|
||
|
|
|
||
|
|
\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}
|
||
|
|
|
||
|
|
Base class for the proxy used to talk to an application. \code{signature}
|
||
|
|
overrides the class attribute \code{_signature} (which is usually set by subclasses)
|
||
|
|
and is the 4-char creator code defining the application to talk to.
|
||
|
|
\code{start} can be set to true to enable running the application on
|
||
|
|
class instantiation. \code{timeout} can be specified to change the
|
||
|
|
default timeout used while waiting for an AppleEvent reply.
|
||
|
|
\end{classdesc}
|
||
|
|
|
||
|
|
\begin{methoddesc}{_start}{}
|
||
|
|
Test whether the application is running, and attempt to start it if not.
|
||
|
|
\end{methoddesc}
|
||
|
|
|
||
|
|
\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
|
||
|
|
Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
|
||
|
|
the OSA designation \code{code, subcode} (which are the usual 4-character
|
||
|
|
strings), pack the \code{parameters} and \code{attributes} into it, send it
|
||
|
|
to the target application, wait for the reply, unpack the reply with
|
||
|
|
\code{unpackevent} and return the reply appleevent, the unpacked return values
|
||
|
|
as a dictionary and the return attributes.
|
||
|
|
\end{methoddesc}
|