PageRenderTime 47ms CodeModel.GetById 24ms RepoModel.GetById 0ms app.codeStats 0ms

/Doc/library/aetools.rst

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