l4/pkg/python/contrib/Doc/library/aetools.rst

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