rb-scpt 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/CHANGES +497 -0
- data/doc/aem-manual/01_introduction.html +60 -0
- data/doc/aem-manual/02_apioverview.html +107 -0
- data/doc/aem-manual/03_packingandunpackingdata.html +135 -0
- data/doc/aem-manual/04_references.html +409 -0
- data/doc/aem-manual/05_targetingapplications.html +164 -0
- data/doc/aem-manual/06_buildingandsendingevents.html +229 -0
- data/doc/aem-manual/07_findapp.html +63 -0
- data/doc/aem-manual/08_examples.html +94 -0
- data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
- data/doc/aem-manual/index.html +56 -0
- data/doc/appscript-manual/01_introduction.html +94 -0
- data/doc/appscript-manual/02_aboutappscripting.html +247 -0
- data/doc/appscript-manual/03_quicktutorial.html +167 -0
- data/doc/appscript-manual/04_gettinghelp.html +188 -0
- data/doc/appscript-manual/05_keywordconversion.html +106 -0
- data/doc/appscript-manual/06_classesandenums.html +192 -0
- data/doc/appscript-manual/07_applicationobjects.html +211 -0
- data/doc/appscript-manual/08_realvsgenericreferences.html +96 -0
- data/doc/appscript-manual/09_referenceforms.html +241 -0
- data/doc/appscript-manual/10_referenceexamples.html +154 -0
- data/doc/appscript-manual/11_applicationcommands.html +245 -0
- data/doc/appscript-manual/12_commandexamples.html +138 -0
- data/doc/appscript-manual/13_performanceissues.html +142 -0
- data/doc/appscript-manual/14_notes.html +80 -0
- data/doc/appscript-manual/application_architecture.gif +0 -0
- data/doc/appscript-manual/application_architecture2.gif +0 -0
- data/doc/appscript-manual/finder_to_textedit_event.gif +0 -0
- data/doc/appscript-manual/index.html +62 -0
- data/doc/appscript-manual/relationships_example.gif +0 -0
- data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
- data/doc/full.css +106 -0
- data/doc/index.html +45 -0
- data/doc/mactypes-manual/01_introduction.html +54 -0
- data/doc/mactypes-manual/02_aliasclass.html +124 -0
- data/doc/mactypes-manual/03_fileurlclass.html +126 -0
- data/doc/mactypes-manual/04_unitsclass.html +100 -0
- data/doc/mactypes-manual/index.html +53 -0
- data/doc/osax-manual/01_introduction.html +67 -0
- data/doc/osax-manual/02_interface.html +147 -0
- data/doc/osax-manual/03_examples.html +73 -0
- data/doc/osax-manual/04_notes.html +61 -0
- data/doc/osax-manual/index.html +53 -0
- data/doc/rb-appscript-logo.png +0 -0
- data/extconf.rb +65 -0
- data/rb-scpt.gemspec +14 -0
- data/sample/AB_export_vcard.rb +31 -0
- data/sample/AB_list_people_with_emails.rb +13 -0
- data/sample/Add_iCal_event.rb +21 -0
- data/sample/Create_daily_iCal_todos.rb +75 -0
- data/sample/Export_Address_Book_phone_numbers.rb +59 -0
- data/sample/Hello_world.rb +21 -0
- data/sample/List_iTunes_playlist_names.rb +11 -0
- data/sample/Make_Mail_message.rb +33 -0
- data/sample/Open_file_in_TextEdit.rb +13 -0
- data/sample/Organize_Mail_messages.rb +61 -0
- data/sample/Print_folder_tree.rb +16 -0
- data/sample/Select_all_HTML_files.rb +14 -0
- data/sample/Set_iChat_status.rb +24 -0
- data/sample/Simple_Finder_GUI_Scripting.rb +18 -0
- data/sample/Stagger_Finder_windows.rb +25 -0
- data/sample/TextEdit_demo.rb +130 -0
- data/sample/iTunes_top40_to_html.rb +71 -0
- data/src/SendThreadSafe.c +380 -0
- data/src/SendThreadSafe.h +139 -0
- data/src/lib/_aem/aemreference.rb +1022 -0
- data/src/lib/_aem/codecs.rb +662 -0
- data/src/lib/_aem/connect.rb +205 -0
- data/src/lib/_aem/encodingsupport.rb +77 -0
- data/src/lib/_aem/findapp.rb +85 -0
- data/src/lib/_aem/mactypes.rb +251 -0
- data/src/lib/_aem/send.rb +279 -0
- data/src/lib/_aem/typewrappers.rb +59 -0
- data/src/lib/_appscript/defaultterminology.rb +277 -0
- data/src/lib/_appscript/referencerenderer.rb +245 -0
- data/src/lib/_appscript/reservedkeywords.rb +116 -0
- data/src/lib/_appscript/safeobject.rb +249 -0
- data/src/lib/_appscript/terminology.rb +471 -0
- data/src/lib/aem.rb +253 -0
- data/src/lib/appscript.rb +1075 -0
- data/src/lib/kae.rb +1489 -0
- data/src/lib/osax.rb +659 -0
- data/src/rbae.c +979 -0
- data/test/README +3 -0
- data/test/test_aemreference.rb +118 -0
- data/test/test_appscriptcommands.rb +152 -0
- data/test/test_appscriptreference.rb +106 -0
- data/test/test_codecs.rb +186 -0
- data/test/test_findapp.rb +26 -0
- data/test/test_mactypes.rb +79 -0
- data/test/test_osax.rb +54 -0
- data/test/testall.sh +10 -0
- metadata +145 -0
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
|
|
5
|
+
<title>rb-aem manual | 1. Introduction</title>
|
|
6
|
+
|
|
7
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
8
|
+
<style type="text/css" media="all"><!--@import url(../full.css);--></style>
|
|
9
|
+
|
|
10
|
+
</head>
|
|
11
|
+
<body>
|
|
12
|
+
|
|
13
|
+
<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="index.html">Previous</a> •
|
|
18
|
+
<a href="index.html">Up</a> •
|
|
19
|
+
<a href="02_apioverview.html">Next</a>
|
|
20
|
+
|
|
21
|
+
<span>
|
|
22
|
+
<a href="../appscript-manual/index.html">appscript</a> /
|
|
23
|
+
<a href="../mactypes-manual/index.html">mactypes</a> /
|
|
24
|
+
<a href="../osax-manual/index.html">osax</a> /
|
|
25
|
+
<strong><a href="../aem-manual/index.html">aem</a></strong>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>1. Introduction</h2>
|
|
33
|
+
|
|
34
|
+
<h3>What is aem?</h3>
|
|
35
|
+
|
|
36
|
+
<p>The aem package provides a mid-level object-oriented wrapper around the low-level ae extension. It provides the following services:</p>
|
|
37
|
+
|
|
38
|
+
<ul>
|
|
39
|
+
<li>an object-oriented API for constructing Apple Event Object Model queries ("references")</li>
|
|
40
|
+
<li>data conversion between common Ruby and Apple event types</li>
|
|
41
|
+
<li>AEAddressDesc creation</li>
|
|
42
|
+
<li>Apple event construction and dispatch.</li>
|
|
43
|
+
</ul>
|
|
44
|
+
|
|
45
|
+
<p>The aem package provides a direct foundation for the high-level appscript package. It can also be used directly by developers and end-users for controlling scriptable applications in situations where appscript is unavailable or unsuitable.</p>
|
|
46
|
+
|
|
47
|
+
<p class="hilitebox">Note that this documentation is an API reference, not a full user guide. Some familiarity with Apple events and the Apple Event Manager is required in order to understand and use aem.</p>
|
|
48
|
+
|
|
49
|
+
</div>
|
|
50
|
+
|
|
51
|
+
<!-- bottom navigation -->
|
|
52
|
+
|
|
53
|
+
<div class="footer">
|
|
54
|
+
<a href="index.html">Previous</a> •
|
|
55
|
+
<a href="index.html">Up</a> •
|
|
56
|
+
<a href="02_apioverview.html">Next</a>
|
|
57
|
+
</div>
|
|
58
|
+
|
|
59
|
+
</body>
|
|
60
|
+
</html>
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
|
|
5
|
+
<title>rb-aem manual | 2. API overview</title>
|
|
6
|
+
|
|
7
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
8
|
+
<style type="text/css" media="all"><!--@import url(../full.css);--></style>
|
|
9
|
+
|
|
10
|
+
</head>
|
|
11
|
+
<body>
|
|
12
|
+
|
|
13
|
+
<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="01_introduction.html">Previous</a> •
|
|
18
|
+
<a href="index.html">Up</a> •
|
|
19
|
+
<a href="03_packingandunpackingdata.html">Next</a>
|
|
20
|
+
|
|
21
|
+
<span>
|
|
22
|
+
<a href="../appscript-manual/index.html">appscript</a> /
|
|
23
|
+
<a href="../mactypes-manual/index.html">mactypes</a> /
|
|
24
|
+
<a href="../osax-manual/index.html">osax</a> /
|
|
25
|
+
<strong><a href="../aem-manual/index.html">aem</a></strong>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>2. API overview</h2>
|
|
33
|
+
|
|
34
|
+
<h3>Classes</h3>
|
|
35
|
+
|
|
36
|
+
<p>The main AEM classes are as follows:</p>
|
|
37
|
+
|
|
38
|
+
<dl>
|
|
39
|
+
<dt>Application</dt>
|
|
40
|
+
<dd>Represents a scriptable application, and provides an <code>#event</code> method for constructing Apple events.</dd>
|
|
41
|
+
|
|
42
|
+
<dt>Event</dt>
|
|
43
|
+
<dd>Represents a ready-to-send Apple event, and provides a <code>#send</code> method for sending it. Returned by the <code>Application</code> class's <code>#event</code> method.</dd>
|
|
44
|
+
|
|
45
|
+
<dt>EventError</dt>
|
|
46
|
+
<dd>Exception raised to indicate an application or Apple Event Manager error.</dd>
|
|
47
|
+
|
|
48
|
+
<dt>Codecs</dt>
|
|
49
|
+
<dd>Provides <code>#pack</code> and <code>#unpack</code> methods for converting Ruby values to AE types, and vice-versa. Clients usually don't need to access this class directly.</dd>
|
|
50
|
+
|
|
51
|
+
<dt>AEType, AEEnum</dt>
|
|
52
|
+
<dd>Represent Apple event type and enumerator values.</dd>
|
|
53
|
+
|
|
54
|
+
</dl>
|
|
55
|
+
|
|
56
|
+
<p>In addition, there are a number of classes used to represent application references, although the user does not instantiate these directly.</p>
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
<h3>Methods</h3>
|
|
60
|
+
|
|
61
|
+
<p>The AEM module exports three top-level methods for use in constructing application references:</p>
|
|
62
|
+
|
|
63
|
+
<dl>
|
|
64
|
+
<dt>app</dt>
|
|
65
|
+
<dd>Returns the base object used to construct absolute references.</dd>
|
|
66
|
+
|
|
67
|
+
<dt>con</dt>
|
|
68
|
+
<dd>Returns the base object used to construct relative reference to container object (used in by-range specifiers).</dd>
|
|
69
|
+
|
|
70
|
+
<dt>its</dt>
|
|
71
|
+
<dd>Returns the base object used to construct relative reference to object being tested (used in by-filter specifiers).</dd>
|
|
72
|
+
</dl>
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
<p>References are constructed from these base objects using chained method calls.</p>
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
<h3>Modules</h3>
|
|
79
|
+
|
|
80
|
+
<p>The following support modules are also provided:</p>
|
|
81
|
+
|
|
82
|
+
<dl>
|
|
83
|
+
<dt>FindApp</dt>
|
|
84
|
+
<dd>Provides functions for locating applications by name, bundle id or creator code.</dd>
|
|
85
|
+
|
|
86
|
+
<dt>AE</dt>
|
|
87
|
+
<dd>Low-level extension that defines an <code>AEDesc</code> class representing Carbon Apple event descriptors (AEDescs). Also provides a number of support methods used by AEM, appscript and related packages.</dd>
|
|
88
|
+
|
|
89
|
+
<dt>KAE</dt>
|
|
90
|
+
<dd>Exports constants defined by Apple Event Manager and Open Scripting APIs.</dd>
|
|
91
|
+
|
|
92
|
+
</dl>
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
</div>
|
|
97
|
+
|
|
98
|
+
<!-- bottom navigation -->
|
|
99
|
+
|
|
100
|
+
<div class="footer">
|
|
101
|
+
<a href="01_introduction.html">Previous</a> •
|
|
102
|
+
<a href="index.html">Up</a> •
|
|
103
|
+
<a href="03_packingandunpackingdata.html">Next</a>
|
|
104
|
+
</div>
|
|
105
|
+
|
|
106
|
+
</body>
|
|
107
|
+
</html>
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
|
|
5
|
+
<title>rb-aem manual | 3. Packing and unpacking data</title>
|
|
6
|
+
|
|
7
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
8
|
+
<style type="text/css" media="all"><!--@import url(../full.css);--></style>
|
|
9
|
+
|
|
10
|
+
</head>
|
|
11
|
+
<body>
|
|
12
|
+
|
|
13
|
+
<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="02_apioverview.html">Previous</a> •
|
|
18
|
+
<a href="index.html">Up</a> •
|
|
19
|
+
<a href="04_references.html">Next</a>
|
|
20
|
+
|
|
21
|
+
<span>
|
|
22
|
+
<a href="../appscript-manual/index.html">appscript</a> /
|
|
23
|
+
<a href="../mactypes-manual/index.html">mactypes</a> /
|
|
24
|
+
<a href="../osax-manual/index.html">osax</a> /
|
|
25
|
+
<strong><a href="../aem-manual/index.html">aem</a></strong>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>3. Packing and unpacking data</h2>
|
|
33
|
+
|
|
34
|
+
<h3>Codecs</h3>
|
|
35
|
+
|
|
36
|
+
<p>The <code>AEM::Codecs</code> class provides methods for converting Ruby data to <code>AE::AEDesc</code> objects, and vice-versa.</p>
|
|
37
|
+
|
|
38
|
+
<pre><code>Codecs
|
|
39
|
+
|
|
40
|
+
Constructor:
|
|
41
|
+
new
|
|
42
|
+
|
|
43
|
+
Methods:
|
|
44
|
+
|
|
45
|
+
# pack/unpack data
|
|
46
|
+
|
|
47
|
+
pack(data) -- convert Ruby data to an AEDesc; will raise
|
|
48
|
+
a TypeError if data's type/class is unsupported
|
|
49
|
+
data : anything
|
|
50
|
+
Result : AEDesc
|
|
51
|
+
|
|
52
|
+
unpack(desc) -- convert an AEDesc to Ruby data; will return
|
|
53
|
+
the AEDesc unchanged if it's an unsupported type
|
|
54
|
+
desc : AEDesc
|
|
55
|
+
Result : anything
|
|
56
|
+
|
|
57
|
+
# compatibility options
|
|
58
|
+
|
|
59
|
+
add_unit_types(types) -- register custom unit type
|
|
60
|
+
definitions
|
|
61
|
+
types : list -- a list of lists, where each sublist
|
|
62
|
+
is of form [name, code, pack_proc, unpack_proc]
|
|
63
|
+
or [name, code]; if the packer and unpacker
|
|
64
|
+
procs are omitted, the AEDesc data is packed/
|
|
65
|
+
unpacked as a double-precision float
|
|
66
|
+
|
|
67
|
+
dont_cache_unpacked_specifiers -- by default, object
|
|
68
|
+
specifier descriptors returned by an application
|
|
69
|
+
are reused for efficiency; invoke this method to
|
|
70
|
+
use AppleScript-style behavior instead (i.e. fully
|
|
71
|
+
unpacking and repacking object specifiers each time)
|
|
72
|
+
for better compatibility with problem applications
|
|
73
|
+
|
|
74
|
+
pack_strings_as_type(code) -- by default, strings are
|
|
75
|
+
packed as typeUnicodeText descriptors; some older
|
|
76
|
+
non-Unicode-aware applications may require text
|
|
77
|
+
to be supplied as typeChar/typeIntlText descriptors
|
|
78
|
+
code : String -- four-char code, e.g. KAE::TypeChar
|
|
79
|
+
(see KAE module for available text types)
|
|
80
|
+
|
|
81
|
+
use_ascii_8bit -- by default, text descriptors are unpacked
|
|
82
|
+
as Strings with UTF-8 Encoding on Ruby 1.9+; invoke
|
|
83
|
+
this method to mimic Ruby 1.8-style behavior where
|
|
84
|
+
Strings contain UTF-8 encoded data and ASCII-8BIT
|
|
85
|
+
Encoding
|
|
86
|
+
|
|
87
|
+
use_datetime -- by default, dates are unpacked as Time
|
|
88
|
+
instances; invoke this method to unpack dates as
|
|
89
|
+
DateTime instances instead</code></pre>
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
<h3>AE types</h3>
|
|
95
|
+
|
|
96
|
+
<p>The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Ruby. Accordingly, aem defines several classes to represent these types on the Ruby side. All share a common abstract base class, <code>AETypeBase</code>:</p>
|
|
97
|
+
|
|
98
|
+
<pre><code>AETypeBase -- Abstract base class
|
|
99
|
+
|
|
100
|
+
Constructor:
|
|
101
|
+
new(code)
|
|
102
|
+
code : str -- a four-character Apple event code
|
|
103
|
+
|
|
104
|
+
Methods:
|
|
105
|
+
code
|
|
106
|
+
Result : str -- Apple event code</code></pre>
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
<p>The four concrete classes are:</p>
|
|
110
|
+
|
|
111
|
+
<pre><code>AEType < AETypeBase -- represents an AE object of typeType
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
AEEnum < AETypeBase -- represents an AE object of typeEnumeration
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
AEProp < AETypeBase -- represents an AE object of typeProperty
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
AEKey < AETypeBase -- represents an AE object of typeKeyword</code></pre>
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
</div>
|
|
125
|
+
|
|
126
|
+
<!-- bottom navigation -->
|
|
127
|
+
|
|
128
|
+
<div class="footer">
|
|
129
|
+
<a href="02_apioverview.html">Previous</a> •
|
|
130
|
+
<a href="index.html">Up</a> •
|
|
131
|
+
<a href="04_references.html">Next</a>
|
|
132
|
+
</div>
|
|
133
|
+
|
|
134
|
+
</body>
|
|
135
|
+
</html>
|
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
2
|
+
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
|
|
5
|
+
<title>rb-aem manual | 4. References</title>
|
|
6
|
+
|
|
7
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
8
|
+
<style type="text/css" media="all"><!--@import url(../full.css);--></style>
|
|
9
|
+
|
|
10
|
+
</head>
|
|
11
|
+
<body>
|
|
12
|
+
|
|
13
|
+
<h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="03_packingandunpackingdata.html">Previous</a> •
|
|
18
|
+
<a href="index.html">Up</a> •
|
|
19
|
+
<a href="05_targetingapplications.html">Next</a>
|
|
20
|
+
|
|
21
|
+
<span>
|
|
22
|
+
<a href="../appscript-manual/index.html">appscript</a> /
|
|
23
|
+
<a href="../mactypes-manual/index.html">mactypes</a> /
|
|
24
|
+
<a href="../osax-manual/index.html">osax</a> /
|
|
25
|
+
<strong><a href="../aem-manual/index.html">aem</a></strong>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>4. References</h2>
|
|
33
|
+
|
|
34
|
+
<h3>About references</h3>
|
|
35
|
+
|
|
36
|
+
<p>An Apple Event Object Model query (a.k.a. "reference") essentially consists of a linked list made up of one or more Apple event descriptors (AEDescs) of, for the most part, <code>typeObjectSpecifier</code>. Object specifiers are used to identify properties and elements in the application's AEOM. Each object specifer contains four fields:</p>
|
|
37
|
+
|
|
38
|
+
<dl>
|
|
39
|
+
<dt>want</dt>
|
|
40
|
+
<dd>four-char-code indicating desired element(s)'s class code (e.g. 'docu' = document), or 'prop' if it's a property specifier</dd>
|
|
41
|
+
|
|
42
|
+
<dt>from</dt>
|
|
43
|
+
<dd>an object specifer identifying container object(s)</dd>
|
|
44
|
+
|
|
45
|
+
<dt>form</dt>
|
|
46
|
+
<dd>four-char-code indicating how the element(s) should be selected (by index ['indx'], name ['name'], etc.), or 'prop' if it's a property specifier</dd>
|
|
47
|
+
|
|
48
|
+
<dt>seld</dt>
|
|
49
|
+
<dd>selector data (e.g. in a by-name specifier, this would be a string)</dd>
|
|
50
|
+
</dl>
|
|
51
|
+
|
|
52
|
+
<p>The Apple Event Manager (and, in turn, the <code>AE</code> extension) provides several ways to construct object specifiers and assemble them into a complete reference, but these are all rather verbose and low-level. AEM hides all these details behind an object-oriented wrapper that uses chained property and method calls to gather the data needed to create object specifiers and assemble them into linked lists.</p>
|
|
53
|
+
|
|
54
|
+
<p>For example, consider the reference <code>text of document 1</code>. The code for constructing this reference using the low-level <code>AE</code> bridge would be:</p>
|
|
55
|
+
|
|
56
|
+
<pre><code>rootref = AE::AEDesc.new("null", "")
|
|
57
|
+
|
|
58
|
+
docref = AE::AEDesc.new_list(true).coerce("obj ")
|
|
59
|
+
docref.put_param("want", AE::AEDesc.new("type", "docu"))
|
|
60
|
+
docref.put_param("from", rootref)
|
|
61
|
+
docref.put_param("form", AE::AEDesc.new("enum", "indx"))
|
|
62
|
+
docref.put_param("seld", AE::AEDesc.new("long", "\x00\x00\x00\x01"))
|
|
63
|
+
|
|
64
|
+
textref = AE::AEDesc.new_list(true).coerce("obj ")
|
|
65
|
+
textref.put_param("want", AE::AEDesc.new("type", "prop"))
|
|
66
|
+
textref.put_param("from", docref)
|
|
67
|
+
textref.put_param("form", AE::AEDesc.new("enum", "prop"))
|
|
68
|
+
textref.put_param("seld", AE::AEDesc.new("type", "ctxt"))
|
|
69
|
+
|
|
70
|
+
p textref
|
|
71
|
+
#<AE::AEDesc type="obj " size=152></code></pre>
|
|
72
|
+
|
|
73
|
+
<p>This code works by creating an AEDesc of <code>typeObjectSpecifier</code> to represent each specifier and populating its fields one at a time. Each AEDesc is nested within the next to form a linked list of object specifier records; the last (innermost) descriptor in the finished list indicates the reference's root object in the AEOM (in this case, the <code>application</code> object, which is represented by a null descriptor).</p>
|
|
74
|
+
|
|
75
|
+
<p>Now, compare the above with the AEM equivalent:</p>
|
|
76
|
+
|
|
77
|
+
<pre><code>app.elements('docu').by_index(1).property('ctxt')</code></pre>
|
|
78
|
+
|
|
79
|
+
<p>As you can see, AEM still uses low-level four-character codes to identify the <code>text</code> property and <code>document</code> class, but is otherwise a high-level object-oriented API. Once again, each reference begins with a root object, in this case <code>AEM.app</code>. New AEM specifiers are constructed by method calls; each call returning a new specifier object whose own methods can be called, and so on. This allows clients to build up a chain of AEM specifier objects that aem can later pack into AEDescs for sending to applications.</p>
|
|
80
|
+
|
|
81
|
+
<p>One more thing to notice: in AEM, specifying a class of elements and indicating which of those elements should be selected are performed by separate method calls, although the information provided will eventually be packed into a single AEDesc of <code>typeObjectSpecifier</code>. This two-step approach makes it easier to integrate aem with the higher-level appscript bridge, which also uses two calls to construct element specifiers (one to specify the element class, e.g. <code>documents</code>, and another to specify the selection, e.g. <code>[1]</code>).</p>
|
|
82
|
+
|
|
83
|
+
<p>Note that <code>app.elements('docu')</code> is itself a valid reference, identifying <em>all</em> the document elements of the application class. You do not have to call an explicit <code>#all</code> selector (indeed, none is provided) as AEM automatically handles the details for you. AEM even allows for some convenient shorthand, e.g. writing:</p>
|
|
84
|
+
|
|
85
|
+
<pre><code>app.elements('docu')by_filter(...).first</code></pre>
|
|
86
|
+
|
|
87
|
+
<p>is equivalent to writing:</p>
|
|
88
|
+
|
|
89
|
+
<pre><code>app.elements('docu')by_filter(...).elements('docu').first</code></pre>
|
|
90
|
+
|
|
91
|
+
<p>This allows clients to specify the first document that matches the given condition without having to specify the element class a second time. In AppleScript, the equivalent to this is:</p>
|
|
92
|
+
|
|
93
|
+
<pre><code>first document whose ...</code></pre>
|
|
94
|
+
|
|
95
|
+
<p>which is short for:</p>
|
|
96
|
+
|
|
97
|
+
<pre><code>first document of (documents whose ...)</code></pre>
|
|
98
|
+
|
|
99
|
+
<p>(Again, this additional behaviour primarily exists to serve the syntactically sugared appscript layer.)</p>
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
<h3>Reference forms</h3>
|
|
104
|
+
|
|
105
|
+
<p>AEM defines a number of classes representing each of the AEOM reference forms. There are eight AEOM reference forms:</p>
|
|
106
|
+
|
|
107
|
+
<ul>
|
|
108
|
+
<li>insertion location</li>
|
|
109
|
+
<li>property</li>
|
|
110
|
+
<li>element by absolute position (index or ordinal)</li>
|
|
111
|
+
<li>element by name</li>
|
|
112
|
+
<li>element by id</li>
|
|
113
|
+
<li>element by relative position</li>
|
|
114
|
+
<li>elements by range</li>
|
|
115
|
+
<li>elements by test</li>
|
|
116
|
+
</ul>
|
|
117
|
+
|
|
118
|
+
<p>(Actually, there's nine forms if you count the 'user property' reference form, although this is only used by OSA (e.g. AppleScript Editor) applets to identify script properties. AEM supports this extra form more for sake of completeness than usefulness.)</p>
|
|
119
|
+
|
|
120
|
+
<p>Each of these reference forms is represented by a different AEM specifier class, apart from the absolute position form which is represented by three different classes according to the kind of selector used: a numerical index (e.g. <code>1</code>, <code>-3</code>), a named ordinal identifying a single element (<code>first</code>, <code>middle</code>, <code>last</code>, <code>any</code>), or a named ordinal identifying all elements (<code>all</code>).</p>
|
|
121
|
+
|
|
122
|
+
<p>The following diagram shows the AEM reference class hierarchy (slightly simplified for legibility); concrete classes are shown in bold:</p>
|
|
123
|
+
|
|
124
|
+
<p><img src="aemreferenceinheritance.gif" alt="AEM reference class hierarchy" title="AEM reference class hierarchy" /></p>
|
|
125
|
+
|
|
126
|
+
<p>Note that the user shouldn't instantiate these classes directly; instead, AEM will instantiate them as appropriate when the client calls the methods of other AEM reference objects, starting with the <code>app</code>, <code>con</code> and <code>its</code> objects that form the root of all AEM references.</p>
|
|
127
|
+
|
|
128
|
+
<p>In fact, it really isn't necessary to remember the reference class hierarchy at all, only to know which concrete classes implement which methods. All user-accessible properties and methods are defined by just four superclasses:</p>
|
|
129
|
+
|
|
130
|
+
<dl>
|
|
131
|
+
<dt><code>Query</code></dt>
|
|
132
|
+
<dd>Defines comparison and hashing methods.</dd>
|
|
133
|
+
|
|
134
|
+
<dt><code>PositionSpecifier</code></dt>
|
|
135
|
+
<dd>Defines methods for identifying properties and all elements, insertion locations, elements by relative position. Also defines comparison and logical test methods for use in constructing its-based references.</dd>
|
|
136
|
+
|
|
137
|
+
<dt><code>MultipleElements</code></dt>
|
|
138
|
+
<dd>Defines methods for identifying specific elements of a multi-element reference.</dd>
|
|
139
|
+
|
|
140
|
+
<dt><code>Test</code></dt>
|
|
141
|
+
<dd>Defines logical test methods for use in constructing its-based references.</dd>
|
|
142
|
+
</dl>
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
<h3>Base classes</h3>
|
|
147
|
+
|
|
148
|
+
<h4>Basic methods</h4>
|
|
149
|
+
|
|
150
|
+
<pre><code>Query -- Base class for all reference form and test clause classes.
|
|
151
|
+
hash -- aem references can be used as dictionary keys
|
|
152
|
+
|
|
153
|
+
==(value) -- aem references can be compared for equality</code></pre>
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
<h4>Methods for all position specifiers</h4>
|
|
157
|
+
|
|
158
|
+
<pre><code>PositionSpecifier < Specifier -- base class for all property and element
|
|
159
|
+
reference forms (i.e. all forms except insertion location)
|
|
160
|
+
|
|
161
|
+
Methods:
|
|
162
|
+
|
|
163
|
+
beginning
|
|
164
|
+
Result : InsertionSpecifier
|
|
165
|
+
|
|
166
|
+
end
|
|
167
|
+
Result : InsertionSpecifier
|
|
168
|
+
|
|
169
|
+
before
|
|
170
|
+
Result : InsertionSpecifier
|
|
171
|
+
|
|
172
|
+
after
|
|
173
|
+
Result : InsertionSpecifier
|
|
174
|
+
|
|
175
|
+
property(code)
|
|
176
|
+
code : str -- four-char property code, e.g. 'pnam'
|
|
177
|
+
Result : Property
|
|
178
|
+
|
|
179
|
+
user_property(name)
|
|
180
|
+
name : str
|
|
181
|
+
Result : UserProperty
|
|
182
|
+
|
|
183
|
+
elements(ccode)
|
|
184
|
+
code : str -- four-char class code, e.g. 'docu'
|
|
185
|
+
Result : AllElements
|
|
186
|
+
|
|
187
|
+
previous(code)
|
|
188
|
+
code : str -- four-char class code
|
|
189
|
+
Result : Element
|
|
190
|
+
|
|
191
|
+
next(code)
|
|
192
|
+
code : str -- four-char class code
|
|
193
|
+
Result : Element
|
|
194
|
+
|
|
195
|
+
-- Note: following methods are for use on
|
|
196
|
+
its-based references only
|
|
197
|
+
|
|
198
|
+
gt(val) -- self is greater than value
|
|
199
|
+
val : anything
|
|
200
|
+
Result : Test
|
|
201
|
+
|
|
202
|
+
ge(val) -- self is greater than or equal to value
|
|
203
|
+
val : anything
|
|
204
|
+
Result : Test
|
|
205
|
+
|
|
206
|
+
eq(val) -- self equals value
|
|
207
|
+
val : anything
|
|
208
|
+
Result : Test
|
|
209
|
+
|
|
210
|
+
ne(val) -- self does not equal value
|
|
211
|
+
val : anything
|
|
212
|
+
Result : Test
|
|
213
|
+
|
|
214
|
+
lt(val) -- self is less than value
|
|
215
|
+
val : anything
|
|
216
|
+
Result : Test
|
|
217
|
+
|
|
218
|
+
le(val) -- self is less than or equal to value
|
|
219
|
+
val : anything
|
|
220
|
+
Result : Test
|
|
221
|
+
|
|
222
|
+
begins_with(val) -- self begins with value
|
|
223
|
+
val : anything
|
|
224
|
+
Result : Test
|
|
225
|
+
|
|
226
|
+
ends_with(val) -- self ends with value
|
|
227
|
+
val : anything
|
|
228
|
+
Result : Test
|
|
229
|
+
|
|
230
|
+
contains(val) -- self contains value
|
|
231
|
+
val : anything
|
|
232
|
+
Result : Test
|
|
233
|
+
|
|
234
|
+
is_in(val) -- self is in value
|
|
235
|
+
val : anything
|
|
236
|
+
Result : Test</code></pre>
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
<h4>Methods for all multi-element specifiers</h4>
|
|
240
|
+
|
|
241
|
+
<pre><code>MultipleElements < PositionSpecifier -- base class for all multi-
|
|
242
|
+
element reference forms
|
|
243
|
+
|
|
244
|
+
Methods:
|
|
245
|
+
|
|
246
|
+
first
|
|
247
|
+
Result : Element
|
|
248
|
+
|
|
249
|
+
middle
|
|
250
|
+
Result : Element
|
|
251
|
+
|
|
252
|
+
last
|
|
253
|
+
Result : Element
|
|
254
|
+
|
|
255
|
+
any
|
|
256
|
+
Result : Element
|
|
257
|
+
|
|
258
|
+
by_index(key)
|
|
259
|
+
key : integer -- normally an integer, though some apps may
|
|
260
|
+
accept other types (e.g. Finder accepts a MacTypes::Alias)
|
|
261
|
+
Result : ElementByIndex
|
|
262
|
+
|
|
263
|
+
by_name(key)
|
|
264
|
+
key : string -- the object's name
|
|
265
|
+
Result : ElementByName
|
|
266
|
+
|
|
267
|
+
by_id(key)
|
|
268
|
+
key : anything -- the object's unique id
|
|
269
|
+
Result : ElementByID
|
|
270
|
+
|
|
271
|
+
by_range(start, stop)
|
|
272
|
+
start : Element -- an app- or con-based reference
|
|
273
|
+
stop : Element -- an app- or con-based reference
|
|
274
|
+
Result : ElementByRange
|
|
275
|
+
|
|
276
|
+
by_filter(test)
|
|
277
|
+
test : Test -- an its-based reference
|
|
278
|
+
Result : ElementsByFilter</code></pre>
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
<h4>Methods for all test clause classes</h4>
|
|
282
|
+
|
|
283
|
+
<pre><code>Test < Query -- represents a comparison/logic test
|
|
284
|
+
|
|
285
|
+
Methods:
|
|
286
|
+
|
|
287
|
+
and(*operands) -- apply a logical 'and' test to self and
|
|
288
|
+
one or more other operands
|
|
289
|
+
*operands : Test -- one or more comparison/logic test
|
|
290
|
+
objects
|
|
291
|
+
Result : Test
|
|
292
|
+
|
|
293
|
+
or(*operands) -- apply a logical 'or' test to self and one
|
|
294
|
+
or more other operands
|
|
295
|
+
*operands : Test -- one or more comparison/logic test
|
|
296
|
+
objects
|
|
297
|
+
Result : Test
|
|
298
|
+
|
|
299
|
+
not -- apply a logical 'not' test to self
|
|
300
|
+
Result : Test</code></pre>
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
<h3>Concrete classes</h3>
|
|
305
|
+
|
|
306
|
+
<h4>Insertion location reference form</h4>
|
|
307
|
+
|
|
308
|
+
<pre><code>InsertionSpecifier < Specifier -- refers to insertion point before or after/at
|
|
309
|
+
beginning or end of element(s); e.g. ref.before</code></pre>
|
|
310
|
+
|
|
311
|
+
<h4>Property reference forms</h4>
|
|
312
|
+
|
|
313
|
+
<pre><code>Property < PositionSpecifier -- refers to a property (whose value
|
|
314
|
+
may be a basic type, application object or reference);
|
|
315
|
+
e.g. ref.property('ctxt')
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
UserProperty < PositionSpecifier -- refers to a user-defined property
|
|
319
|
+
(typically in an OSA applet); e.g. ref.user_property('myVar')</code></pre>
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
<h4>Single element reference forms</h4>
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
<pre><code>ElementByIndex < SingleElement -- refers to a single element in the referenced
|
|
326
|
+
container object(s) by index; e.g. ref.by_index(3)
|
|
327
|
+
|
|
328
|
+
ElementByName < SingleElement -- refers to a single element in the referenced
|
|
329
|
+
container object(s) by name; e.g. ref.by_name('Documents')
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
ElementByID < SingleElement -- refers to a single element in the referenced container
|
|
333
|
+
object(s) by unique id; e.g. ref.by_id(3456)
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
ElementByOrdinal < SingleElement -- refers to first, middle, last or any element in
|
|
337
|
+
the referenced container object(s); e.g. ref.first
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
ElementByRelativePosition < SingleElement -- refers to the previous or next element
|
|
341
|
+
of the given class in the referenced container object(s);
|
|
342
|
+
e.g. ref.next('cpar')</code></pre>
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
<h4>Multiple element reference forms</h4>
|
|
346
|
+
|
|
347
|
+
<pre><code>ElementsByRange < MultipleElements -- refers to a range of elements
|
|
348
|
+
in the referenced container object(s) (including beginning and
|
|
349
|
+
end points); e.g. ref.by_range(AEM.con.elements('cpar').by_index(2),
|
|
350
|
+
AEM.con.elements('cpar').last)
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
ElementsByFilter < MultipleElements -- refers to all elements in the
|
|
354
|
+
referenced container object(s) that fulfill a given condition;
|
|
355
|
+
e.g. ref.by_filter(AEM.its.property('pnam').begins_with('a'))
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
AllElements < MultipleElements -- refers to all elements of the given class
|
|
359
|
+
in the referenced container object(s); e.g. ref.elements('docu')</code></pre>
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
<h4>Tests</h4>
|
|
363
|
+
|
|
364
|
+
<p>The <code>Test</code> class represents a comparison test or logical test, and defines methods for composing additional logical tests on top of these. Each kind of test clause is represented by a different subclass of the main <code>Test</code> class. The details are not that important, however, so they're not listed here.</p>
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
<h4>Reference Roots</h4>
|
|
370
|
+
|
|
371
|
+
<p>The following classes are used to construct standard AEM references:</p>
|
|
372
|
+
|
|
373
|
+
<pre><code>ApplicationRoot < PositionSpecifier
|
|
374
|
+
-- AEM.app returns an instance of this class
|
|
375
|
+
|
|
376
|
+
CurrentContainer < PositionSpecifier
|
|
377
|
+
-- AEM.con returns an instance of this class
|
|
378
|
+
|
|
379
|
+
ObjectBeingExamined < PositionSpecifier
|
|
380
|
+
-- AEM.its returns an instance of this class</code></pre>
|
|
381
|
+
|
|
382
|
+
<p>Clients shouldn't instantiate the above classes directly; instead, they should use the <code>AEM.app</code>, <code>AEM.con</code> and <code>AEM.its</code> methods which return the appropriate objects.</p>
|
|
383
|
+
|
|
384
|
+
<p>The <code>CustomRoot</code> class is used to construct AEM references with a non-standard root:</p>
|
|
385
|
+
|
|
386
|
+
<pre><code>CustomRoot(ReferenceRoot) -- used to construct references with
|
|
387
|
+
a custom root
|
|
388
|
+
|
|
389
|
+
Constructor:
|
|
390
|
+
|
|
391
|
+
initialize(value)
|
|
392
|
+
value : anything -- value to use as innermost container
|
|
393
|
+
in nested object specifiers</code></pre>
|
|
394
|
+
|
|
395
|
+
<p>Clients can use the <code>AEM.custom_root</code> method to create new <code>CustomRoot</code> instances, passing the root object as method's sole argument.</p>
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
</div>
|
|
399
|
+
|
|
400
|
+
<!-- bottom navigation -->
|
|
401
|
+
|
|
402
|
+
<div class="footer">
|
|
403
|
+
<a href="03_packingandunpackingdata.html">Previous</a> •
|
|
404
|
+
<a href="index.html">Up</a> •
|
|
405
|
+
<a href="05_targetingapplications.html">Next</a>
|
|
406
|
+
</div>
|
|
407
|
+
|
|
408
|
+
</body>
|
|
409
|
+
</html>
|