PageRenderTime 284ms CodeModel.GetById 121ms app.highlight 5ms RepoModel.GetById 96ms 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
 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
12The :mod:`aetools` module contains the basic functionality on which Python
13AppleScript client support is built. It also imports and re-exports the core
14functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
15generated by :mod:`gensuitemodule` import the relevant portions of
16:mod:`aetools`, so usually you do not need to import it yourself. The exception
17to this is when you cannot use a generated suite package and need lower-level
18access to scripting.
19
20The :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
22manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
23lifted in future releases.
24
25.. note::
26
27   This module has been removed in Python 3.x.
28
29
30The :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
64The :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