Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bae5c96

Browse files
jackjansenjackjansen
committed
Moved all the scripting stuff to a separate section, added all the
missing bits (well, all the bits I could think of) and updated the rest.
1 parent 126f2b7 commit bae5c96

8 files changed

Lines changed: 397 additions & 40 deletions

File tree

‎Doc/Makefile.deps‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -345,10 +345,13 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
345345
MACFILES= $(HOWTOSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
346346
mac/mac.tex \
347347
mac/using.tex \
348+
mac/scripting.tex \
348349
mac/toolbox.tex \
349350
mac/undoc.tex \
350351
mac/libcolorpicker.tex \
351352
mac/libmac.tex \
353+
mac/libgensuitemodule.tex \
354+
mac/libaetools.tex \
352355
mac/libaepack.tex \
353356
mac/libaetypes.tex \
354357
mac/libmacfs.tex \

‎Doc/mac/libaepack.tex‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,24 +45,34 @@ \section{\module{aepack} ---
4545
encoded as a text descriptor.
4646
\end{funcdesc}
4747

48-
\begin{funcdesc}{unpack}{x}
48+
\begin{funcdesc}{unpack}{x\optional{, formodulename}}
4949
\var{x} must be an object of type \class{AEDesc}. This function
5050
returns a Python object representation of the data in the Apple
5151
Event descriptor \var{x}. Simple AppleEvent data types (integer,
5252
text, float) are returned as their obvious Python counterparts.
5353
Apple Event lists are returned as Python lists, and the list
5454
elements are recursively unpacked. Object references
5555
(ex. \code{line 3 of document 1}) are returned as instances of
56-
\class{aetypes.ObjectSpecifier}. AppleEvent descriptors with
56+
\class{aetypes.ObjectSpecifier}, unless \code{formodulename}
57+
is specified. AppleEvent descriptors with
5758
descriptor type typeFSS are returned as \class{FSSpec}
5859
objects. AppleEvent record descriptors are returned as Python
59-
dictionaries, with keys of type \class{?} and elements recursively
60+
dictionaries, with 4-character string keys and elements recursively
6061
unpacked.
62+
63+
The optional \code{formodulename} argument is used by the stub packages
64+
generated by \module{gensuitemodule}, and ensures that the OSA classes
65+
for object specifiers are looked up in the correct module. This ensures
66+
that if, say, the Finder returns an object specifier for a window
67+
you get an instance of \code{Finder.Window} and not a generic
68+
\code{aetypes.Window}. The former knows about all the properties
69+
and elements a window has in the Finder, while the latter knows
70+
no such things.
6171
\end{funcdesc}
6272

6373

6474
\begin{seealso}
65-
\seemodule{AE}{Built-in access to Apple Event Manager routines.}
75+
\seemodule{Carbon.AE}{Built-in access to Apple Event Manager routines.}
6676
\seemodule{aetypes}{Python definitions of codes for Apple Event
6777
descriptor types.}
6878
\seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{

‎Doc/mac/libaetools.tex‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
\section{\module{aetools} ---
2+
OSA client support}
3+
4+
\declaremodule{standard}{aetools}
5+
\platform{Mac}
6+
%\moduleauthor{Jack Jansen?}{email}
7+
\modulesynopsis{Basic support for sending Apple Events}
8+
\sectionauthor{Jack Jansen}{[email protected]}
9+
10+
11+
The \module{aetools} module contains the basic functionality
12+
on which Python AppleScript client support is built. It also
13+
imports and re-exports the core functionality of the
14+
\module{aetypes} and \module{aepack} modules. The stub packages
15+
generated by \module{gensuitemodule} import the relevant
16+
portions of \module{aetools}, so usually you do not need to
17+
import it yourself. The exception to this is when you
18+
cannot use a generated suite package and need lower-level
19+
access to scripting.
20+
21+
The \module{aetools} module itself uses the AppleEvent support
22+
provided by the \module{Carbon.AE} module. This has one drawback:
23+
you need access to the window manager, see section \ref{osx-gui-scripts}
24+
for details. This restriction may be lifted in future releases.
25+
26+
27+
The \module{aetools} module defines the following functions:
28+
29+
\begin{funcdesc}{packevent}{ae, parameters, attributes}
30+
Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
31+
object. \code{parameters} and \code{attributes} are
32+
dictionaries mapping 4-character OSA parameter keys to Python objects. The
33+
objects are packed using \code{aepack.pack()}.
34+
\end{funcdesc}
35+
36+
\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
37+
Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
38+
The function returns the parameter dictionary and the attribute dictionary.
39+
The \code{formodulename} argument is used by generated stub packages to
40+
control where AppleScript classes are looked up.
41+
\end{funcdesc}
42+
43+
\begin{funcdesc}{keysubst}{arguments, keydict}
44+
Converts a Python keyword argument dictionary \code{arguments} to
45+
the format required by \code{packevent} by replacing the keys,
46+
which are Python identifiers, by the four-character OSA keys according
47+
to the mapping specified in \code{keydict}. Used by the generated suite
48+
packages.
49+
\end{funcdesc}
50+
51+
\begin{funcdesc}{enumsubst}{arguments, key, edict}
52+
If the \code{arguments} dictionary contains an entry for \code{key}
53+
convert the value for that entry according to dictionary \code{edict}.
54+
This converts human-readable Python enumeration names to the OSA 4-character
55+
codes.
56+
Used by the generated suite
57+
packages.
58+
\end{funcdesc}
59+
60+
The \module{aetools} module defines the following class:
61+
62+
\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}
63+
64+
Base class for the proxy used to talk to an application. \code{signature}
65+
overrides the class attribute \code{_signature} (which is usually set by subclasses)
66+
and is the 4-char creator code defining the application to talk to.
67+
\code{start} can be set to true to enable running the application on
68+
class instantiation. \code{timeout} can be specified to change the
69+
default timeout used while waiting for an AppleEvent reply.
70+
\end{classdesc}
71+
72+
\begin{methoddesc}{_start}{}
73+
Test whether the application is running, and attempt to start it if not.
74+
\end{methoddesc}
75+
76+
\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
77+
Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
78+
the OSA designation \code{code, subcode} (which are the usual 4-character
79+
strings), pack the \code{parameters} and \code{attributes} into it, send it
80+
to the target application, wait for the reply, unpack the reply with
81+
\code{unpackevent} and return the reply appleevent, the unpacked return values
82+
as a dictionary and the return attributes.
83+
\end{methoddesc}

‎Doc/mac/libaetypes.tex‎

Lines changed: 125 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -8,32 +8,128 @@ \section{\module{aetypes} ---
88
\sectionauthor{Vincent Marchetti}{[email protected]}
99

1010

11-
The \module{aetypes} defines classes used to represent Apple Event
12-
object specifiers. An object specifier is essentially an address of an
13-
object implemented in a Apple Event server. An Apple Event specifier
14-
is used as the direct object for an Apple Event or as the argument of
15-
an optional parameter. In AppleScript an object specifier is
16-
represented by a phrase such as:
17-
\code{character 23 of document "Semprini"}. The classes defined in
18-
this module allow this specifier to be represented by a Python object
19-
which is initialized as follows:
20-
\code{res = Document(1).Character(23)}
21-
22-
23-
The \module{AEObjects} module defines the following class:
24-
25-
\begin{classdesc}{ObjectSpecifier}{want, form, seld, from}
26-
This is the base class for representing object specifiers and is
27-
generally not constructed directly by the user. Its important
28-
functionality is to define an \function{__aepack__()} function,
29-
which returns the Apple Event descriptor containing the object
30-
specifier. Its data members, set directly from the constructor
31-
arguments, are:
32-
\end{classdesc}
33-
34-
\begin{memberdesc}{want}
35-
A four character string representing the class code of the
36-
object. These class codes are specified in Apple Event Suites; for
37-
example the standard code for a character object is the 4 bytes
38-
\samp{char}.
39-
\end{memberdesc}
11+
The \module{aetypes} defines classes used to represent Apple Event data
12+
descriptors and Apple Event object specifiers.
13+
14+
Apple Event data is is contained in descriptors, and these descriptors
15+
are typed. For many descriptors the Python representation is simply the
16+
corresponding Python type: \code{typeText} in OSA is a Python string,
17+
\code{typeFloat} is a float, etc. For OSA types that have no direct
18+
Python counterpart this module declares classes. Packing and unpacking
19+
instances of these classes is handled automatically by \module{aepack}.
20+
21+
An object specifier is essentially an address of an object implemented
22+
in a Apple Event server. An Apple Event specifier is used as the direct
23+
object for an Apple Event or as the argument of an optional parameter.
24+
The \module{aetypes} module contains the base classes for OSA classes
25+
and properties, which are used by the packages generated by
26+
\module{gensuitemodule} to populate the classes and properties in a
27+
given suite.
28+
29+
For reasons of backward compatibility, and for cases where you need to
30+
script an application for which you have not generated the stub package
31+
this module also contains object specifiers for a number of common OSA
32+
classes such as \code{Document}, \code{Window}, \code{Character}, etc.
33+
34+
35+
36+
The \module{AEObjects} module defines the following classes to represent
37+
Apple Event descriptor data:
38+
39+
\begin{classdesc}{Unknown}{type, data}
40+
The representation of OSA descriptor data for which the \module{aepack}
41+
and \module{aetypes} modules have no support, i.e. anything that is not
42+
represented by the other classes here and that is not equivalent to a
43+
simple Python value.
44+
\end{classdesc}
45+
46+
\begin{classdesc}{Enum}{enum}
47+
An enumeration value with the given 4-character string value.
48+
\end{classdesc}
49+
50+
\begin{classdesc}{InsertionLoc}{of, pos}
51+
Position \code{pos} in object \code{of}.
52+
\end{classdesc}
53+
54+
\begin{classdesc}{Boolean}{bool}
55+
A boolean.
56+
\end{classdesc}
57+
58+
\begin{classdesc}{StyledText}{style, text}
59+
Text with style information (font, face, etc) included.
60+
\end{classdesc}
61+
62+
\begin{classdesc}{AEText}{script, style, text}
63+
Text with script system and style information included.
64+
\end{classdesc}
65+
66+
\begin{classdesc}{IntlText}{script, language, text}
67+
Text with script system and language information included.
68+
\end{classdesc}
69+
70+
\begin{classdesc}{IntlWritingCode}{script, language}
71+
Script system and language information.
72+
\end{classdesc}
73+
74+
\begin{classdesc}{QDPoint}{v, h}
75+
A quickdraw point.
76+
\end{classdesc}
77+
78+
\begin{classdesc}{QDRectangle}{v0, h0, v1, h1}
79+
A quickdraw rectangle.
80+
\end{classdesc}
81+
82+
\begin{classdesc}{RGBColor}{r, g, b}
83+
A color.
84+
\end{classdesc}
85+
86+
\begin{classdesc}{Type}{type}
87+
An OSA type value with the given 4-character name.
88+
\end{classdesc}
89+
90+
\begin{classdesc}{Keyword}{name}
91+
An OSA keyword with the given 4-character name.
92+
\end{classdesc}
93+
94+
\begin{classdesc}{Range}{start, stop}
95+
A range.
96+
\end{classdesc}
97+
98+
\begin{classdesc}{Ordinal}{abso}
99+
Non-numeric absolute positions, such as \code{"firs"}, first, or \code{"midd"},
100+
middle.
101+
\end{classdesc}
102+
103+
\begin{classdesc}{Logical}{logc, term}
104+
The logical expression of applying operator \code{logc} to
105+
\code{term}.
106+
\end{classdesc}
107+
108+
\begin{classdesc}{Comparison}{obj1, relo, obj2}
109+
The comparison \code{relo} of \code{obj1} to \code{obj2}.
110+
\end{classdesc}
111+
112+
The following classes are used as base classes by the generated stub
113+
packages to represent AppleScript classes and properties in Python:
114+
115+
\begin{classdesc}{ComponentItem}{which\optional{, fr}}
116+
Abstract baseclass for an OSA class. The subclass should set the class
117+
attribute \code{want} to the 4-character OSA class code. Instances of
118+
subclasses of this class are equivalent to AppleScript Object
119+
Specifiers. Upon instantiation you should pass a selector in
120+
\code{which}, and optionally a parent object in \code{fr}.
121+
\end{classdesc}
122+
123+
\begin{classdesc}{NProperty}{fr}
124+
Abstract basclass for an OSA property. The subclass should set the class
125+
attributes \code{want} and \code{which} to designate which property we
126+
are talking about. Instances of subclasses of this class are Object
127+
Specifiers.
128+
\end{classdesc}
129+
130+
\begin{classdesc}{ObjectSpecifier}{want, form, seld\optional{, fr}}
131+
Base class of \code{ComponentItem} and \code{NProperty}, a general
132+
OSA Object Specifier. See the Apple Open Scripting Architecture
133+
documentation for the parameters. Note that this class is not abstract.
134+
\end{classdesc}
135+

‎Doc/mac/libgensuitemodule.tex‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
\section{\module{gensuitemodule} ---
2+
Generate OSA stub packages}
3+
4+
\declaremodule{standard}{gensuitemodule}
5+
\platform{Mac}
6+
%\moduleauthor{Jack Jansen?}{email}
7+
\modulesynopsis{Create a stub package from an OSA dictionary}
8+
\sectionauthor{Jack Jansen}{[email protected]}
9+
10+
The \module{gensuitemodule} module creates a Python package implementing
11+
stub code for the AppleScript suites that are implemented by a specific
12+
application, according to its AppleScript dictionary.
13+
14+
It is usually invoked by the user through the \program{PythonIDE}, but
15+
it can also be run as a script from the command line (pass \code{--help}
16+
for help on the options) or imported from Python code. For an example of
17+
its use see \file{Mac/scripts/genallsuites.py} in a source distribution,
18+
which generates the stub packages that are included in the standard
19+
library.
20+
21+
It defines the following public functions:
22+
23+
\begin{funcdesc}{is_scriptable}{application}
24+
Returns true if \code{application}, which should be passed as a pathname,
25+
appears to be scriptable. Take the return value with a grain of salt:
26+
\program{Internet Explorer} appears not to be scriptable but definitely is.
27+
\end{funcdesc}
28+
29+
\begin{funcdesc}{processfile}{application\optional{, output, basepkgname,
30+
edit_modnames, creatorsignature, dump, verbose}}
31+
Create a stub package for \code{application}, which should be passed as
32+
a full pathname. For a \file{.app} bundle this is the pathname to the
33+
bundle, not to the executable inside the bundle; for an unbundled CFM
34+
application you pass the filename of the application binary.
35+
36+
This function asks the application for its OSA terminology resources,
37+
decodes these resources and uses the resultant data to create the Python
38+
code for the package implementing the client stubs.
39+
40+
\code{output} is the pathname where the resulting package is stored, if
41+
not specified a standard "save file as" dialog is presented to
42+
the user. \code{basepkgname} is the base package on which this package
43+
will build, and defaults to \module{StdSuites}. Only when generating
44+
\module{StdSuites} itself do you need to specify this.
45+
\code{edit_modnames} is a dictionary that can be used to change
46+
modulenames that are too ugly after name mangling.
47+
\code{creator_signature} can be used to override the 4-char creator
48+
code, which is normally obtained from the \file{PkgInfo} file in the
49+
package or from the CFM file creator signature. When \code{dump} is
50+
given it should refer to a file object, and \code{processfile} will stop
51+
after decoding the resources and dump the Python representation of the
52+
terminology resources to this file. \code{verbose} should also be a file
53+
object, and specifying it will cause \code{processfile} to tell you what
54+
it is doing.
55+
\end{funcdesc}
56+
57+
\begin{funcdesc}{processfile_fromresource}{application\optional{, output,
58+
basepkgname, edit_modnames, creatorsignature, dump, verbose}}
59+
This function does the same as \code{processfile}, except that it uses a
60+
different method to get the terminology resources. It opens \code{application}
61+
as a resource file and reads all \code{"aete"} and \code{"aeut"} resources
62+
from this file.
63+
\end{funcdesc}
64+

‎Doc/mac/mac.tex‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,8 @@ \chapter{MacPython Modules \label{macpython-modules}}
5757
\input{libmacostools}
5858
\input{libmacui}
5959
\input{libframework}
60-
\input{libminiae}
61-
\input{libaepack}
62-
\input{libaetypes}
60+
61+
\input{scripting}
6362

6463
\input{toolbox} % MacOS Toolbox Modules
6564
\input{libcolorpicker}

0 commit comments

Comments
 (0)