ref: 57d690c482c7e5f57608befe7cb04797b1bff153
dir: /sys/src/cmd/python/Doc/mac/libaetools.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}{[email protected]} 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}