Jack Jansen | bae5c96 | 2003-04-11 15:35:28 +0000 | [diff] [blame^] | 1 | \section{\module{aetools} --- |
| 2 | OSA client support} |
| 3 | |
| 4 | \declaremodule{standard}{aetools} |
| 5 | \platform{Mac} |
| 6 | %\moduleauthor{Jack Jansen?}{email} |
| 7 | \modulesynopsis{Basic support for sending Apple Events} |
| 8 | \sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl} |
| 9 | |
| 10 | |
| 11 | The \module{aetools} module contains the basic functionality |
| 12 | on which Python AppleScript client support is built. It also |
| 13 | imports and re-exports the core functionality of the |
| 14 | \module{aetypes} and \module{aepack} modules. The stub packages |
| 15 | generated by \module{gensuitemodule} import the relevant |
| 16 | portions of \module{aetools}, so usually you do not need to |
| 17 | import it yourself. The exception to this is when you |
| 18 | cannot use a generated suite package and need lower-level |
| 19 | access to scripting. |
| 20 | |
| 21 | The \module{aetools} module itself uses the AppleEvent support |
| 22 | provided by the \module{Carbon.AE} module. This has one drawback: |
| 23 | you need access to the window manager, see section \ref{osx-gui-scripts} |
| 24 | for details. This restriction may be lifted in future releases. |
| 25 | |
| 26 | |
| 27 | The \module{aetools} module defines the following functions: |
| 28 | |
| 29 | \begin{funcdesc}{packevent}{ae, parameters, attributes} |
| 30 | Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc} |
| 31 | object. \code{parameters} and \code{attributes} are |
| 32 | dictionaries mapping 4-character OSA parameter keys to Python objects. The |
| 33 | objects are packed using \code{aepack.pack()}. |
| 34 | \end{funcdesc} |
| 35 | |
| 36 | \begin{funcdesc}{unpackevent}{ae\optional{, formodulename}} |
| 37 | Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects. |
| 38 | The function returns the parameter dictionary and the attribute dictionary. |
| 39 | The \code{formodulename} argument is used by generated stub packages to |
| 40 | control where AppleScript classes are looked up. |
| 41 | \end{funcdesc} |
| 42 | |
| 43 | \begin{funcdesc}{keysubst}{arguments, keydict} |
| 44 | Converts a Python keyword argument dictionary \code{arguments} to |
| 45 | the format required by \code{packevent} by replacing the keys, |
| 46 | which are Python identifiers, by the four-character OSA keys according |
| 47 | to the mapping specified in \code{keydict}. Used by the generated suite |
| 48 | packages. |
| 49 | \end{funcdesc} |
| 50 | |
| 51 | \begin{funcdesc}{enumsubst}{arguments, key, edict} |
| 52 | If the \code{arguments} dictionary contains an entry for \code{key} |
| 53 | convert the value for that entry according to dictionary \code{edict}. |
| 54 | This converts human-readable Python enumeration names to the OSA 4-character |
| 55 | codes. |
| 56 | Used by the generated suite |
| 57 | packages. |
| 58 | \end{funcdesc} |
| 59 | |
| 60 | The \module{aetools} module defines the following class: |
| 61 | |
| 62 | \begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}} |
| 63 | |
| 64 | Base class for the proxy used to talk to an application. \code{signature} |
| 65 | overrides the class attribute \code{_signature} (which is usually set by subclasses) |
| 66 | and is the 4-char creator code defining the application to talk to. |
| 67 | \code{start} can be set to true to enable running the application on |
| 68 | class instantiation. \code{timeout} can be specified to change the |
| 69 | default timeout used while waiting for an AppleEvent reply. |
| 70 | \end{classdesc} |
| 71 | |
| 72 | \begin{methoddesc}{_start}{} |
| 73 | Test whether the application is running, and attempt to start it if not. |
| 74 | \end{methoddesc} |
| 75 | |
| 76 | \begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}} |
| 77 | Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with |
| 78 | the OSA designation \code{code, subcode} (which are the usual 4-character |
| 79 | strings), pack the \code{parameters} and \code{attributes} into it, send it |
| 80 | to the target application, wait for the reply, unpack the reply with |
| 81 | \code{unpackevent} and return the reply appleevent, the unpacked return values |
| 82 | as a dictionary and the return attributes. |
| 83 | \end{methoddesc} |