Doc/mac/libaetools.tex

   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}