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>