[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / mac / module-aetools.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="mac.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="mac.html" title='Macintosh Library Modules' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-aepack.html" />
<link rel="prev" href="module-gensuitemodule.html" />
<link rel="parent" href="scripting.html" />
<link rel="next" href="module-aepack.html" />
<meta name='aesop' content='information' />
<title>3.2 aetools -- OSA client support</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.1 gensuitemodule  "
  href="module-gensuitemodule.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3. MacPython OSA Modules"
  href="scripting.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.3 aepack  "
  href="module-aepack.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Macintosh Library Modules</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-gensuitemodule.html">3.1 gensuitemodule  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="scripting.html">3. MacPython OSA Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-aepack.html">3.3 aepack  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION005200000000000000000">
3.2 <tt class="module">aetools</tt> --
         OSA client support</A>
</H1>

<P>
<A NAME="module-aetools"></A>  
<p class="availability">Availability: <span
 class="platform">Macintosh</span>.</p>

<P>
The <tt class="module">aetools</tt> module contains the basic functionality
on which Python AppleScript client support is built. It also
imports and re-exports the core functionality of the
<tt class="module">aetypes</tt> and <tt class="module">aepack</tt> modules. The stub packages
generated by <tt class="module">gensuitemodule</tt> import the relevant
portions of <tt class="module">aetools</tt>, so usually you do not need to
import it yourself. The exception to this is when you
cannot use a generated suite package and need lower-level
access to scripting.

<P>
The <tt class="module">aetools</tt> module itself uses the AppleEvent support
provided by the <tt class="module">Carbon.AE</tt> module. This has one drawback:
you need access to the window manager, see section <A href="osx-gui-scripts.html#osx-gui-scripts">1.1.2</A>
for details. This restriction may be lifted in future releases.

<P>
The <tt class="module">aetools</tt> module defines the following functions:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-142' xml:id='l2h-142' class="function">packevent</tt></b>(</nobr></td>
  <td><var>ae, parameters, attributes</var>)</td></tr></table></dt>
<dd>
Stores parameters and attributes in a pre-created <code>Carbon.AE.AEDesc</code>
object. <code>parameters</code> and <code>attributes</code> are 
dictionaries mapping 4-character OSA parameter keys to Python objects. The
objects are packed using <code>aepack.pack()</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-143' xml:id='l2h-143' class="function">unpackevent</tt></b>(</nobr></td>
  <td><var>ae</var><big>[</big><var>, formodulename</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Recursively unpacks a <code>Carbon.AE.AEDesc</code> event to Python objects.
The function returns the parameter dictionary and the attribute dictionary.
The <code>formodulename</code> argument is used by generated stub packages to
control where AppleScript classes are looked up.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-144' xml:id='l2h-144' class="function">keysubst</tt></b>(</nobr></td>
  <td><var>arguments, keydict</var>)</td></tr></table></dt>
<dd>
Converts a Python keyword argument dictionary <code>arguments</code> to
the format required by <code>packevent</code> by replacing the keys,
which are Python identifiers, by the four-character OSA keys according
to the mapping specified in <code>keydict</code>. Used by the generated suite
packages.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-145' xml:id='l2h-145' class="function">enumsubst</tt></b>(</nobr></td>
  <td><var>arguments, key, edict</var>)</td></tr></table></dt>
<dd>
If the <code>arguments</code> dictionary contains an entry for <code>key</code>
convert the value for that entry according to dictionary <code>edict</code>.
This converts human-readable Python enumeration names to the OSA 4-character
codes.
Used by the generated suite
packages.
</dl>

<P>
The <tt class="module">aetools</tt> module defines the following class:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-146' xml:id='l2h-146' class="class">TalkTo</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>signature=None, start=0, timeout=0</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<P>
Base class for the proxy used to talk to an application. <code>signature</code>
overrides the class attribute <code>_signature</code> (which is usually set by subclasses)
and is the 4-char creator code defining the application to talk to.
<code>start</code> can be set to true to enable running the application on
class instantiation. <code>timeout</code> can be specified to change the
default timeout used while waiting for an AppleEvent reply.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-147' xml:id='l2h-147' class="method">_start</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Test whether the application is running, and attempt to start it if not.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-148' xml:id='l2h-148' class="method">send</tt></b>(</nobr></td>
  <td><var>code, subcode</var><big>[</big><var>, parameters, attributes</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Create the AppleEvent <code>Carbon.AE.AEDesc</code> for the verb with
the OSA designation <code>code, subcode</code> (which are the usual 4-character
strings), pack the <code>parameters</code> and <code>attributes</code> into it, send it
to the target application, wait for the reply, unpack the reply with
<code>unpackevent</code> and return the reply appleevent, the unpacked return values
as a dictionary and the return attributes.
</dl>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="3.1 gensuitemodule  "
  href="module-gensuitemodule.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="3. MacPython OSA Modules"
  href="scripting.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.3 aepack  "
  href="module-aepack.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Macintosh Library Modules</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-gensuitemodule.html">3.1 gensuitemodule  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="scripting.html">3. MacPython OSA Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-aepack.html">3.3 aepack  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="mac.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="mac.html" title='Macintosh Library Modules' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="module-aepack.html" />
	13	<link rel="prev" href="module-gensuitemodule.html" />
	14	<link rel="parent" href="scripting.html" />
	15	<link rel="next" href="module-aepack.html" />
	16	<meta name='aesop' content='information' />
	17	<title>3.2 aetools -- OSA client support</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="3.1 gensuitemodule "
	25	href="module-gensuitemodule.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="3. MacPython OSA Modules"
	28	href="scripting.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="3.3 aepack "
	31	href="module-aepack.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Macintosh Library Modules</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-gensuitemodule.html">3.1 gensuitemodule </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="scripting.html">3. MacPython OSA Modules</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-aepack.html">3.3 aepack </A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION005200000000000000000">
	56	3.2 <tt class="module">aetools</tt> --
	57	OSA client support</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-aetools"></A>
	62	<p class="availability">Availability: <span
	63	class="platform">Macintosh</span>.</p>
	64
65	<P>
66	The <tt class="module">aetools</tt> module contains the basic functionality
67	on which Python AppleScript client support is built. It also
68	imports and re-exports the core functionality of the
69	<tt class="module">aetypes</tt> and <tt class="module">aepack</tt> modules. The stub packages
70	generated by <tt class="module">gensuitemodule</tt> import the relevant
71	portions of <tt class="module">aetools</tt>, so usually you do not need to
72	import it yourself. The exception to this is when you
73	cannot use a generated suite package and need lower-level
74	access to scripting.
75
76	<P>
77	The <tt class="module">aetools</tt> module itself uses the AppleEvent support
78	provided by the <tt class="module">Carbon.AE</tt> module. This has one drawback:
79	you need access to the window manager, see section <A href="osx-gui-scripts.html#osx-gui-scripts">1.1.2</A>
80	for details. This restriction may be lifted in future releases.
81
82	<P>
83	The <tt class="module">aetools</tt> module defines the following functions:
84
85	<P>
86	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
87	<td><nobr><b><tt id='l2h-142' xml:id='l2h-142' class="function">packevent</tt></b>(</nobr></td>
88	<td><var>ae, parameters, attributes</var>)</td></tr></table></dt>
89	<dd>
90	Stores parameters and attributes in a pre-created <code>Carbon.AE.AEDesc</code>
91	object. <code>parameters</code> and <code>attributes</code> are
92	dictionaries mapping 4-character OSA parameter keys to Python objects. The
93	objects are packed using <code>aepack.pack()</code>.
94	</dl>
95
96	<P>
97	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
98	<td><nobr><b><tt id='l2h-143' xml:id='l2h-143' class="function">unpackevent</tt></b>(</nobr></td>
99	<td><var>ae</var><big>[</big><var>, formodulename</var><big>]</big><var></var>)</td></tr></table></dt>
100	<dd>
101	Recursively unpacks a <code>Carbon.AE.AEDesc</code> event to Python objects.
102	The function returns the parameter dictionary and the attribute dictionary.
103	The <code>formodulename</code> argument is used by generated stub packages to
104	control where AppleScript classes are looked up.
105	</dl>
106
107	<P>
108	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
109	<td><nobr><b><tt id='l2h-144' xml:id='l2h-144' class="function">keysubst</tt></b>(</nobr></td>
110	<td><var>arguments, keydict</var>)</td></tr></table></dt>
111	<dd>
112	Converts a Python keyword argument dictionary <code>arguments</code> to
113	the format required by <code>packevent</code> by replacing the keys,
114	which are Python identifiers, by the four-character OSA keys according
115	to the mapping specified in <code>keydict</code>. Used by the generated suite
116	packages.
117	</dl>
118
119	<P>
120	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
121	<td><nobr><b><tt id='l2h-145' xml:id='l2h-145' class="function">enumsubst</tt></b>(</nobr></td>
122	<td><var>arguments, key, edict</var>)</td></tr></table></dt>
123	<dd>
124	If the <code>arguments</code> dictionary contains an entry for <code>key</code>
125	convert the value for that entry according to dictionary <code>edict</code>.
126	This converts human-readable Python enumeration names to the OSA 4-character
127	codes.
128	Used by the generated suite
129	packages.
130	</dl>
131
132	<P>
133	The <tt class="module">aetools</tt> module defines the following class:
134
135	<P>
136	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
137	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-146' xml:id='l2h-146' class="class">TalkTo</tt></b>(</nobr></td>
138	<td><var></var><big>[</big><var>signature=None, start=0, timeout=0</var><big>]</big><var></var>)</td></tr></table></dt>
139	<dd>
140
141	<P>
142	Base class for the proxy used to talk to an application. <code>signature</code>
143	overrides the class attribute <code>_signature</code> (which is usually set by subclasses)
144	and is the 4-char creator code defining the application to talk to.
145	<code>start</code> can be set to true to enable running the application on
146	class instantiation. <code>timeout</code> can be specified to change the
147	default timeout used while waiting for an AppleEvent reply.
148	</dl>
149
150	<P>
151	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
152	<td><nobr><b><tt id='l2h-147' xml:id='l2h-147' class="method">_start</tt></b>(</nobr></td>
153	<td><var></var>)</td></tr></table></dt>
154	<dd>
155	Test whether the application is running, and attempt to start it if not.
156	</dl>
157
158	<P>
159	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160	<td><nobr><b><tt id='l2h-148' xml:id='l2h-148' class="method">send</tt></b>(</nobr></td>
161	<td><var>code, subcode</var><big>[</big><var>, parameters, attributes</var><big>]</big><var></var>)</td></tr></table></dt>
162	<dd>
163	Create the AppleEvent <code>Carbon.AE.AEDesc</code> for the verb with
164	the OSA designation <code>code, subcode</code> (which are the usual 4-character
165	strings), pack the <code>parameters</code> and <code>attributes</code> into it, send it
166	to the target application, wait for the reply, unpack the reply with
167	<code>unpackevent</code> and return the reply appleevent, the unpacked return values
168	as a dictionary and the return attributes.
169	</dl>
170
171	<DIV CLASS="navigation">
172	<div class='online-navigation'>
173	<p></p><hr />
174	<table align="center" width="100%" cellpadding="0" cellspacing="2">
175	<tr>
176	<td class='online-navigation'><a rel="prev" title="3.1 gensuitemodule "
177	href="module-gensuitemodule.html"><img src='../icons/previous.png'
178	border='0' height='32' alt='Previous Page' width='32' /></A></td>
179	<td class='online-navigation'><a rel="parent" title="3. MacPython OSA Modules"
180	href="scripting.html"><img src='../icons/up.png'
181	border='0' height='32' alt='Up One Level' width='32' /></A></td>
182	<td class='online-navigation'><a rel="next" title="3.3 aepack "
183	href="module-aepack.html"><img src='../icons/next.png'
184	border='0' height='32' alt='Next Page' width='32' /></A></td>
185	<td align="center" width="100%">Macintosh Library Modules</td>
186	<td class='online-navigation'><a rel="contents" title="Table of Contents"
187	href="contents.html"><img src='../icons/contents.png'
188	border='0' height='32' alt='Contents' width='32' /></A></td>
189	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
190	border='0' height='32' alt='Module Index' width='32' /></a></td>
191	<td class='online-navigation'><a rel="index" title="Index"
192	href="genindex.html"><img src='../icons/index.png'
193	border='0' height='32' alt='Index' width='32' /></A></td>
194	</tr></table>
195	<div class='online-navigation'>
196	<b class="navlabel">Previous:</b>
197	<a class="sectref" rel="prev" href="module-gensuitemodule.html">3.1 gensuitemodule </A>
198	<b class="navlabel">Up:</b>
199	<a class="sectref" rel="parent" href="scripting.html">3. MacPython OSA Modules</A>
200	<b class="navlabel">Next:</b>
201	<a class="sectref" rel="next" href="module-aepack.html">3.3 aepack </A>
202	</div>
203	</div>
204	<hr />
205	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
206	</DIV>
207	<!--End of Navigation Panel-->
208	<ADDRESS>
209	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
210	</ADDRESS>
211	</BODY>
212	</HTML>