\section{\module{aetools} ---
         OSA クライアントのサポート}
% OSA client support

\declaremodule{standard}{aetools}
  \platform{Mac}
%\moduleauthor{Jack Jansen?}{email}
\modulesynopsis{Apple Eventを送るための基本的なサポート}
% Basic support for sending Apple Events
\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}


%% The \module{aetools} module contains the basic functionality
%% on which Python AppleScript client support is built. It also
%% imports and re-exports the core functionality of the
%% \module{aetypes} and \module{aepack} modules. The stub packages
%% generated by \module{gensuitemodule} import the relevant
%% portions of \module{aetools}, 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.

\module{aetools} モジュールは Python で AppleScript クライアントとして
の機能をサポートするアプリケーションを構築するための基本的な機能を含ん
でいます。さらに、このモジュールは、 \module{aetypes} および 
\module{aepack} モジュールの中核機能をインポートし再 エクスポートします。
\module{gensuitemodule} によって生成されたスタブパッケージは 
\module{aetools} のかなり適切な部分をインポートするので、通常はそれを
明示的にインポートする必要はありません。生成されたパッケージ群を使用す
ることができない場合と、スクリプト対応のためにより低いレベルのアクセス
を必要としている場合、例外が発生します。

%% The \module{aetools} module itself uses the AppleEvent support
%% provided by the \module{Carbon.AE} module. This has one drawback:
%% you need access to the window manager, see section \ref{osx-gui-scripts}
%% for details. This restriction may be lifted in future releases.

\module{aetools} モジュールはそれ自身、\module{Carbon.AE} モジュールに
よって提供される AppleEvent サポートを利用します。このモジュールにはウィ
ンドウマネージャへのアクセスを必要とするという1つの欠点があります。詳
細は第  \ref{osx-gui-scripts} 章を見てください。この制限は将来のリリー
スで撤廃されるかもしれません。

%% The \module{aetools} module defines the following functions:

\module{aetools} モジュールは下記の関数を定義しています。

\begin{funcdesc}{packevent}{ae, parameters, attributes}
%% Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
%% object. \code{parameters} and \code{attributes} are 
%% dictionaries mapping 4-character OSA parameter keys to Python objects. The
%% objects are packed using \code{aepack.pack()}.

あらかじめ作成された \code{Carbon.AE.AEDesc} オブジェクト中のパラメー
ターおよび属性を保存します。\code{parameters} と \code{attributes} は
Python オブジェクトの4文字の OSA パラメータのキーを写像した辞書です。
このオブジェクトをパックするには \code{aepack.pack()} を使います。
\end{funcdesc}

\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
%% Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
%% The function returns the parameter dictionary and the attribute dictionary.
%% The \code{formodulename} argument is used by generated stub packages to
%% control where AppleScript classes are looked up.

再帰的に、\code{Carbon.AE.AEDesc} イベントをPython オブジェクトへアン
パックします。関数は引数の辞書および属性の辞書を返します。
\code{formodulename} 引数は AppleScript クラスをどこに捜しに行くか制御
するために、生成されたスタブパッケージにより使用されます。
\end{funcdesc}

\begin{funcdesc}{keysubst}{arguments, keydict}
%% Converts a Python keyword argument dictionary \code{arguments} to
%% the format required by \code{packevent} by replacing the keys,
%% which are Python identifiers, by the four-character OSA keys according
%% to the mapping specified in \code{keydict}. Used by the generated suite
%% packages.

Python キーワード引数辞書 \code{arguments} を、写像による4文字の OSA 
キーとして \code{keydict} の中で指定されたPython 識別子であるキーの交
換により \code{packevent} によって要求されるフォーマットへ変換します。
生成されたパッケージ群によって使用されます。
\end{funcdesc}

\begin{funcdesc}{enumsubst}{arguments, key, edict}
%% If the \code{arguments} dictionary contains an entry for \code{key}
%% convert the value for that entry according to dictionary \code{edict}.
%% This converts human-readable Python enumeration names to the OSA 4-character
%% codes.
%% Used by the generated suite
%% packages.

\code{arguments} 辞書が \code{key} へのエントリーを含んでいる場合、辞
書 \code{edict} のエントリーに見合う値に変換します。これは人間に判読可
能なように Python 列挙名を OSA 4文字のコードに変換します。生成されたパッ
ケージ群によって使用されます。
\end{funcdesc}

%% The \module{aetools} module defines the following class:

\module{aetools} モジュールは次のクラスを定義しています。

\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}

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

アプリケーションとの対話に利用する代理の基底クラスです。
\code{signature} はクラス属性 \code{_signature} (サブクラスによって通
常設定される)を上書きした、対話するアプリケーションを定義する4文字クリ
エートコードです。\code{start} にはクラスインスタンス上でアプリケーショ
ンを実行することを可能にするために、真を設定する事ができます。
\code{timeout} を明示的に設定する事で、 AppleEvent の返答を待つデフォ
ルトのタイムアウト時間を変更する事ができます。
\end{classdesc}

\begin{methoddesc}{_start}{}
%% Test whether the application is running, and attempt to start it if not.

アプリケーションが起動していてるか確認し、起動していなければ起動しよう
とします。
\end{methoddesc}

\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
%% Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
%% the OSA designation \code{code, subcode} (which are the usual 4-character
%% strings), pack the \code{parameters} and \code{attributes} into it, send it
%% to the target application, wait for the reply, unpack the reply with
%% \code{unpackevent} and return the reply appleevent, the unpacked return values
%% as a dictionary and the return attributes.

OSA指示子  \code{code, subcode} (いずれも通常4文字の文字列です)を持った
変数のために、\code{parameters} をパックし、\code{attributes}に戻し、
目標アプリケーションにそれを送って、返答を待ち、\code{unpackevent} を
含んだ返答をアンパックし、AppleEvent の返答を返し、辞書としてアンパッ
クした値と属性を返して、AppleEvent \code{Carbon.AE.AEDesc} を作成しま
す。
\end{methoddesc}
