|
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 .. warning:: |
|
26 |
|
27 This module is removed in 3.0. |
|
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 |