rb-appscript 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. data/CHANGES +30 -0
  2. data/LICENSE +1 -1
  3. data/README +7 -3
  4. data/TODO +7 -1
  5. data/doc/aem-manual/01_introduction.html +23 -9
  6. data/doc/aem-manual/02_apioverview.html +25 -11
  7. data/doc/aem-manual/03_packingandunpackingdata.html +22 -17
  8. data/doc/aem-manual/04_references.html +49 -36
  9. data/doc/aem-manual/05_targettingapplications.html +25 -14
  10. data/doc/aem-manual/06_buildingandsendingevents.html +47 -21
  11. data/doc/aem-manual/07_findapp.html +22 -11
  12. data/doc/aem-manual/08_examples.html +21 -10
  13. data/doc/aem-manual/index.html +28 -12
  14. data/doc/appscript-manual/01_introduction.html +40 -27
  15. data/doc/appscript-manual/02_aboutappscripting.html +28 -15
  16. data/doc/appscript-manual/03_quicktutorial.html +29 -16
  17. data/doc/appscript-manual/04_gettinghelp.html +31 -16
  18. data/doc/appscript-manual/05_keywordconversion.html +23 -10
  19. data/doc/appscript-manual/06_classesandenums.html +32 -19
  20. data/doc/appscript-manual/07_applicationobjects.html +31 -18
  21. data/doc/appscript-manual/08_realvsgenericreferences.html +23 -11
  22. data/doc/appscript-manual/09_referenceforms.html +33 -20
  23. data/doc/appscript-manual/10_referenceexamples.html +30 -17
  24. data/doc/appscript-manual/11_applicationcommands.html +25 -13
  25. data/doc/appscript-manual/12_commandexamples.html +26 -15
  26. data/doc/appscript-manual/13_performanceissues.html +46 -20
  27. data/doc/appscript-manual/14_notes.html +29 -19
  28. data/doc/appscript-manual/index.html +27 -11
  29. data/doc/full.css +95 -9
  30. data/doc/index.html +27 -10
  31. data/doc/mactypes-manual/01_introduction.html +56 -0
  32. data/doc/mactypes-manual/02_aliasclass.html +134 -0
  33. data/doc/mactypes-manual/03_fileurlclass.html +136 -0
  34. data/doc/mactypes-manual/04_unitsclass.html +102 -0
  35. data/doc/mactypes-manual/index.html +26 -227
  36. data/doc/osax-manual/01_introduction.html +69 -0
  37. data/doc/osax-manual/02_interface.html +149 -0
  38. data/doc/osax-manual/03_examples.html +75 -0
  39. data/doc/osax-manual/04_notes.html +80 -0
  40. data/doc/osax-manual/index.html +26 -195
  41. data/doc/rb-appscript-logo.png +0 -0
  42. data/rb-appscript.gemspec +2 -2
  43. data/sample/TextEdit_demo.rb +1 -1
  44. data/src/lib/_aem/aemreference.rb +1 -1
  45. data/src/lib/_aem/codecs.rb +42 -8
  46. data/src/lib/_aem/connect.rb +3 -1
  47. data/src/lib/_aem/findapp.rb +1 -1
  48. data/src/lib/_aem/mactypes.rb +1 -1
  49. data/src/lib/_aem/send.rb +162 -142
  50. data/src/lib/_aem/typewrappers.rb +2 -2
  51. data/src/lib/_appscript/defaultterminology.rb +76 -46
  52. data/src/lib/_appscript/referencerenderer.rb +1 -1
  53. data/src/lib/_appscript/reservedkeywords.rb +2 -2
  54. data/src/lib/_appscript/safeobject.rb +1 -1
  55. data/src/lib/_appscript/terminology.rb +30 -19
  56. data/src/lib/aem.rb +1 -6
  57. data/src/lib/appscript.rb +65 -20
  58. data/src/lib/osax.rb +21 -18
  59. data/src/rbae.c +1 -1
  60. data/test/test_appscriptcommands.rb +1 -1
  61. metadata +12 -3
data/doc/aem-manual/05_targettingapplications.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>aem | 5. Targetting Applications</title>
5
+ <title>rb-aem manual | 5. Targetting Applications</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,20 +10,28 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>5. Targetting Applications</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="04_references.html">Previous</a> | <a href="index.html">Up</a> | <a href="06_buildingandsendingevents.html">Next</a>
17
+ <a href="04_references.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="06_buildingandsendingevents.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>
18
27
  </div>
19
28
 
20
29
  <!-- content -->
21
30
  <div id="content">
22
31
 
32
+ <h2>5. Targetting Applications</h2>
23
33
 
24
-
25
-
26
- <h2>The <code>Application</code> class</h2>
34
+ <h3>The <code>Application</code> class</h3>
27
35
 
28
36
  <p>The <code>Application</code> class represents an application to which Apple events will be sent. Its constructor allows applications to be identified in one of four ways: by full path, by eppc URL, by custom <code>AEAddressDesc</code>, or the host application if no other value is given. Its main method, <code>#event</code>, is used to construct the Apple events to send. Several utility methods are also provided.</p>
29
37
 
@@ -99,7 +107,7 @@
99
107
  via the by_path constructor.)</code></pre>
100
108
 
101
109
 
102
- <h2>Creating <code>Application</code> objects</h2>
110
+ <h3>Creating <code>Application</code> objects</h3>
103
111
 
104
112
  <p>When targetting a local application by path, the full path to the application (or application bundle) must be given, including a <code>.app</code> suffix if present. Note that aem identifies local applications by process serial number for reliability. If the target application is not already running when a new <code>Application</code> instance is created, it will be started automatically so that a PSN can be acquired. If the application can't be launched for some reason (e.g. if it's in the Trash), an <code>AEM::CantLaunchApplicationError</code> error will be raised.</p>
105
113
 
@@ -117,12 +125,12 @@ KAE::TypeProcessSerialNumber</code></pre>
117
125
  <p>See the Apple Event Manager documentation for more information on these addressing modes.</p>
118
126
 
119
127
 
120
- <h2>Launching applications</h2>
128
+ <h3>Launching applications</h3>
121
129
 
122
130
  <p><code>Application.launch</code> is a class method attached to the <code>Application</code> class for convenience. It allows a non-running application to be launched without sending it the 'run' event (<code>aevtoapp</code>) normally sent to applications - a 'no-op' event (<code>ascrnoop</code>) is sent instead. It should be called before creating an <code>Application</code> object for the target application, otherwise the application will be launched as normal.</p>
123
131
 
124
132
 
125
- <h2>Transactions</h2>
133
+ <h3>Transactions</h3>
126
134
 
127
135
  <p>The <code>#begin_transaction</code> and <code>#end_transaction</code> methods are used to start and stop transaction sessions for applications that support this. All events <em>created</em> while a transaction session is active will be identified as part of that transaction.</p>
128
136
 
@@ -131,7 +139,7 @@ KAE::TypeProcessSerialNumber</code></pre>
131
139
  <p>The <code>#end_transaction</code> method must be called to close both successful and failed transactions on completion. If a transaction session is accidentally left open, aem will attempt to close it when the <code>Application</code> object is garbage-collected, although this cannot be guaranteed to succeed.</p>
132
140
 
133
141
 
134
- <h2>Reconnecting to local applications</h2>
142
+ <h3>Reconnecting to local applications</h3>
135
143
 
136
144
  <p>Because local applications are identified by process serial number, an existing <code>Application</code> object created using the <code>by_path</code> constructor will no longer hold a valid <code>AEAddressDesc</code> if the target application subsequently quits. Sending events to an invalid address will cause a <code>CommandError</code> -600 ("application isn't running") or -609 ("connection is invalid") to be raised.</p>
137
145
 
@@ -145,11 +153,14 @@ KAE::TypeProcessSerialNumber</code></pre>
145
153
  </div>
146
154
 
147
155
  <!-- bottom navigation -->
148
- <div class="navbar">
149
- <a href="04_references.html">Previous</a> | <a href="index.html">Up</a> | <a href="06_buildingandsendingevents.html">Next</a>
156
+
157
+ <div class="footer">
158
+ <a href="04_references.html">Previous</a> &bull;
159
+ <a href="index.html">Up</a> &bull;
160
+ <a href="06_buildingandsendingevents.html">Next</a>
161
+
162
+ <span>&copy; 2006-2008 HAS</span>
150
163
  </div>
151
164
 
152
- <!--footer-->
153
- <p class="footer">&copy; 2006-2008 HAS</p>
154
165
  </body>
155
166
  </html>
data/doc/aem-manual/06_buildingandsendingevents.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>aem | 6. Building and sending events</title>
5
+ <title>rb-aem manual | 6. Building and sending events</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,20 +10,29 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>6. Building and sending events</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="05_targettingapplications.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_findapp.html">Next</a>
17
+ <a href="05_targettingapplications.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="07_findapp.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>
18
27
  </div>
19
28
 
20
29
  <!-- content -->
21
30
  <div id="content">
22
31
 
32
+ <h2>6. Building and sending events</h2>
23
33
 
24
34
 
25
-
26
- <h2>The <code>Application#event</code> method</h2>
35
+ <h3>The <code>Application#event</code> method</h3>
27
36
 
28
37
  <p>The <code>Application#event</code> method is used to create new Apple events targetted at the specified application.</p>
29
38
 
@@ -45,9 +54,7 @@
45
54
 
46
55
 
47
56
 
48
-
49
-
50
- <h2>The <code>Event</code> class</h2>
57
+ <h3>The <code>Event</code> class</h3>
51
58
 
52
59
  <p>The <code>Event</code> class represents an Apple event that has been packed and is ready to send.</p>
53
60
 
@@ -66,11 +73,11 @@
66
73
  <p>The <code>send</code> method may be called any number of times.</p>
67
74
 
68
75
 
69
- <h2>Constants</h2>
76
+ <h3>Constants</h3>
70
77
 
71
78
  <p>The following constants are defined in the <code>KAE</code> module.</p>
72
79
 
73
- <h3>Common parameter keys</h3>
80
+ <h4>Common parameter keys</h4>
74
81
 
75
82
  <pre><code>KAE::KeyDirectObject
76
83
  KAE::KeyAERequestedType</code></pre>
@@ -80,10 +87,11 @@ KAE::KeyAERequestedType</code></pre>
80
87
  <p>Other parameter keys are defined by individual applications.</p>
81
88
 
82
89
 
83
- <h3>Attribute keys</h3>
90
+ <h4>Attribute keys</h4>
84
91
 
85
92
  <p>Most of the following attributes are already supplied by other means (e.g. keyEventClassAttr, keyEventIDAttr are supplied separately when creating an Apple event; keyTimeoutAttr when sending it) and are only of interest if unpacking AppleEvent descriptors manually. A few may be used when passing an attributes dict to <code>Application#event</code> (<code>EnumConsiderations</code>, <code>EnumConsidsAndIgnores</code>, <code>KeySubjectAttr</code>):</p>
86
-
93
+
94
+ <pre><code>KAE::KeyTransactionIDAttr
87
95
  KAE::KeyReturnIDAttr
88
96
  KAE::KeyEventClassAttr
89
97
  KAE::KeyEventIDAttr
@@ -115,11 +123,26 @@ KAE::KASNumericStrings</code></pre>
115
123
 
116
124
  <p>The value of the <code>EnumConsidsAndIgnores</code> attribute should be an integer composed from the sum of zero or more of the following bit masks:</p>
117
125
 
118
- <pre><code>KAE::KAECaseConsiderMask
119
-
126
+ <pre><code>KAE::KAECaseConsiderMask
127
+ KAE::KAEDiacriticConsiderMask
128
+ KAE::KAEWhiteSpaceConsiderMask
129
+ KAE::KAEHyphensConsiderMask
130
+ KAE::KAEExpansionConsiderMask
131
+ KAE::KAEPunctuationConsiderMask
132
+ KAE::KASConsiderRepliesConsiderMask
133
+ KAE::KASNumericStringsConsiderMask
120
134
 
135
+ KAE::KAECaseIgnoreMask
136
+ KAE::KAEDiacriticIgnoreMask
137
+ KAE::KAEWhiteSpaceIgnoreMask
138
+ KAE::KAEHyphensIgnoreMask
139
+ KAE::KAEExpansionIgnoreMask
140
+ KAE::KAEPunctuationIgnoreMask
141
+ KAE::KASConsiderRepliesIgnoreMask
142
+ KAE::KASNumericStringsIgnoreMask</code></pre>
121
143
 
122
- <h3>Send flag constants</h3>
144
+
145
+ <h4>Send flag constants</h4>
123
146
 
124
147
  <p>The value of the <code>send</code> method's <code>flags</code> argument should be an integer composed from the sum of zero or more of the following bit masks:</p>
125
148
 
@@ -140,12 +163,12 @@ KAE::KAECanSwitchLayer</code></pre>
140
163
  <p>See the <a href="http://developer.apple.com/documentation/Carbon/Reference/Apple_Event_Manager/apple_event_manager_ref/chapter_1.4_section_6.html">Apple Event Manager</a> API reference for details.</p>
141
164
 
142
165
 
143
- <h3>Other constants</h3>
166
+ <h4>Other constants</h4>
144
167
 
145
168
  <pre><code>KAE::KAutoGenerateReturnID</code></pre>
146
169
 
147
170
 
148
- <h2>The <code>CommandError</code> class</h2>
171
+ <h3>The <code>CommandError</code> class</h3>
149
172
 
150
173
  <p>The <code>CommandError</code> class is raised by <code>Event#send</code> and represents an error raised by the target application or Apple Event Manager when sending an event.</p>
151
174
 
@@ -165,11 +188,14 @@ KAE::KAECanSwitchLayer</code></pre>
165
188
  </div>
166
189
 
167
190
  <!-- bottom navigation -->
168
- <div class="navbar">
169
- <a href="05_targettingapplications.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_findapp.html">Next</a>
191
+
192
+ <div class="footer">
193
+ <a href="05_targettingapplications.html">Previous</a> &bull;
194
+ <a href="index.html">Up</a> &bull;
195
+ <a href="07_findapp.html">Next</a>
196
+
197
+ <span>&copy; 2006-2008 HAS</span>
170
198
  </div>
171
199
 
172
- <!--footer-->
173
- <p class="footer">&copy; 2006-2008 HAS</p>
174
200
  </body>
175
201
  </html>
data/doc/aem-manual/07_findapp.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>aem | 7. Locating applications</title>
5
+ <title>rb-aem manual | 7. Locating applications</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,22 +10,30 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>7. Locating applications</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="06_buildingandsendingevents.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_examples.html">Next</a>
17
+ <a href="06_buildingandsendingevents.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="08_examples.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>
18
27
  </div>
19
28
 
20
29
  <!-- content -->
21
30
  <div id="content">
22
31
 
32
+ <h2>7. Locating applications</h2>
23
33
 
34
+ <h3>The <code>FindApp</code> module</h3>
24
35
 
25
-
26
- <h2>The <code>FindApp</code> module</h2>
27
-
28
- <p>The <code>FindApp</code> module is used to obtain the full path to an application given it file name, bundle ID, or creator code. It exports the following functions:</p>
36
+ <p>The <code>FindApp</code> module is used to obtain the full path to an application given its file name, bundle ID, or creator code. It exports the following methods:</p>
29
37
 
30
38
  <pre><code>by_name(name) -- Find the application with the given name.
31
39
  name : string -- application's name, e.g. 'Finder.app'. The '.app' suffix
@@ -44,11 +52,14 @@ by_creator(creator) -- Find the application with the given creator type.
44
52
  </div>
45
53
 
46
54
  <!-- bottom navigation -->
47
- <div class="navbar">
48
- <a href="06_buildingandsendingevents.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_examples.html">Next</a>
55
+
56
+ <div class="footer">
57
+ <a href="06_buildingandsendingevents.html">Previous</a> &bull;
58
+ <a href="index.html">Up</a> &bull;
59
+ <a href="08_examples.html">Next</a>
60
+
61
+ <span>&copy; 2006-2008 HAS</span>
49
62
  </div>
50
63
 
51
- <!--footer-->
52
- <p class="footer">&copy; 2006-2008 HAS</p>
53
64
  </body>
54
65
  </html>
data/doc/aem-manual/08_examples.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>aem | 8. Examples</title>
5
+ <title>rb-aem manual | 8. Examples</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,18 +10,27 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>8. Examples</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a>
17
+ <a href="07_findapp.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a>
19
+
20
+ <span>
21
+ <a href="../appscript-manual/index.html">appscript</a> /
22
+ <a href="../mactypes-manual/index.html">mactypes</a> /
23
+ <a href="../osax-manual/index.html">osax</a> /
24
+ <strong><a href="../aem-manual/index.html">aem</a></strong>
25
+ </span>
18
26
  </div>
19
27
 
20
28
  <!-- content -->
21
29
  <div id="content">
22
30
 
31
+ <h2>8. Examples</h2>
23
32
 
24
- <h2>Identifying applications</h2>
33
+ <h3>Identifying applications</h3>
25
34
 
26
35
  <pre><code># application "Macintosh HD:Applications:TextEdit.app"
27
36
  textedit = AEM::Application.by_path('/Applications/TextEdit.app')
@@ -33,7 +42,7 @@ textedit = AEM::Application.by_path(FindApp.by_name('TextEdit'))
33
42
  textedit = AEM::Application.by_url('eppc://my-mac.local/TextEdit')</code></pre>
34
43
 
35
44
 
36
- <h2>Building references</h2>
45
+ <h3>Building references</h3>
37
46
 
38
47
  <pre><code># name (of application)
39
48
  AEM.app.property('pnam')
@@ -53,7 +62,7 @@ AEM.app.elements('docu').first.elements('cpar').by_range(
53
62
  AEM.app.elements('docu').by_index(1).elements('cpar').by_filter(AEM.its.ne("\n"))</code></pre>
54
63
 
55
64
 
56
- <h2>Sending events</h2>
65
+ <h3>Sending events</h3>
57
66
 
58
67
  <pre><code># quit TextEdit
59
68
  textedit.event('aevtquit').send
@@ -75,11 +84,13 @@ textedit.event('corecrel', {
75
84
  </div>
76
85
 
77
86
  <!-- bottom navigation -->
78
- <div class="navbar">
79
- <a href="07_findapp.html">Previous</a> | <a href="index.html">Up</a>
87
+
88
+ <div class="footer">
89
+ <a href="07_findapp.html">Previous</a> &bull;
90
+ <a href="index.html">Up</a>
91
+
92
+ <span>&copy; 2006-2008 HAS</span>
80
93
  </div>
81
94
 
82
- <!--footer-->
83
- <p class="footer">&copy; 2006-2008 HAS</p>
84
95
  </body>
85
96
  </html>
data/doc/aem-manual/index.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>appscript | Contents</title>
5
+ <title>rb-aem manual | Contents</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,16 +10,28 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>Contents</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="../index.html">Up</a> | <a href="01_introduction.html">Next</a>
18
-
19
- </div>
17
+ <a href="../index.html">Previous</a> &bull;
18
+ <a href="../index.html">Up</a> &bull;
19
+ <a href="01_introduction.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>
20
28
 
21
29
  <!-- content -->
22
- <div id="content"><ol>
30
+ <div id="content">
31
+
32
+ <h2>Contents</h2>
33
+
34
+ <ol>
23
35
  <li><a href="01_introduction.html">Introduction</a></li>
24
36
  <li><a href="02_apioverview.html">API overview</a></li>
25
37
  <li><a href="03_packingandunpackingdata.html">Packing and unpacking data</a></li>
@@ -28,15 +40,19 @@
28
40
  <li><a href="06_buildingandsendingevents.html">Building and sending events</a></li>
29
41
  <li><a href="07_findapp.html">Locating applications</a></li>
30
42
  <li><a href="08_examples.html">Examples</a></li>
31
- </ol></div>
43
+ </ol>
44
+
45
+ </div>
32
46
 
33
47
  <!-- bottom navigation -->
34
- <div class="navbar">
35
- <a href="../index.html">Up</a> | <a href="01_introduction.html">Next</a>
36
-
48
+
49
+ <div class="footer">
50
+ <a href="../index.html">Previous</a> &bull;
51
+ <a href="../index.html">Up</a> &bull;
52
+ <a href="01_introduction.html">Next</a>
53
+
54
+ <span>&copy; 2006-2008 HAS</span>
37
55
  </div>
38
56
 
39
- <!--footer-->
40
- <p class="footer">&copy; 2006-2008 HAS</p>
41
57
  </body>
42
58
  </html>
data/doc/appscript-manual/01_introduction.html CHANGED
@@ -2,7 +2,7 @@
2
2
  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
3
  <head>
4
4
 
5
- <title>appscript | 1. Introduction</title>
5
+ <title>rb-appscript manual | 1. Introduction</title>
6
6
 
7
7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8
8
  <style type="text/css" media="all"><!--@import url(../full.css);--></style>
@@ -10,19 +10,30 @@
10
10
  </head>
11
11
  <body>
12
12
 
13
- <h1>1. Introduction</h1>
13
+ <h1><img src="../rb-appscript-logo.png" alt="rb-appscript" title="rb-appscript" /></h1>
14
14
 
15
15
  <!-- top navigation -->
16
16
  <div class="navbar">
17
- <a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_aboutappscripting.html">Next</a>
18
-
17
+ <a href="index.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="02_aboutappscripting.html">Next</a>
20
+
21
+ <span>
22
+ <strong><a href="../appscript-manual/index.html">appscript</a></strong> /
23
+ <a href="../mactypes-manual/index.html">mactypes</a> /
24
+ <a href="../osax-manual/index.html">osax</a> /
25
+ <a href="../aem-manual/index.html">aem</a>
26
+ </span>
19
27
  </div>
20
28
 
21
29
  <!-- content -->
22
30
  <div id="content">
23
- <h2>What is appscript?</h2>
24
31
 
25
- <p>Ruby appscript (rb-appscript) is a high-level, user-friendly Apple event bridge that allows you to control scriptable Mac OS X applications using ordinary Ruby scripts. Appscript makes Ruby a serious alternative to Apple's own AppleScript language for automating your Mac.</p>
32
+ <h2>1. Introduction</h2>
33
+
34
+ <h3>What is appscript?</h3>
35
+
36
+ <p>Ruby appscript (rb-appscript) is an easy-to-use Apple event bridge that allows 'AppleScriptable' applications to be controlled by ordinary Ruby scripts. Appscript makes Ruby an excellent alternative to Apple's own AppleScript language for automating your Mac.</p>
26
37
 
27
38
  <p>For example, to get the value of the first paragraph of the topmost document in TextEdit:</p>
28
39
 
@@ -34,19 +45,6 @@
34
45
  get paragraph 1 of document 1
35
46
  end tell</code></pre>
36
47
 
37
- <p>Appscript builds upon lower-level Ruby modules (ae, aem) to provide:</p>
38
-
39
- <ol>
40
- <li>a high-level <em>RPC mechanism</em> for sending commands to applications via Apple events</li>
41
- <li>a mechanism for converting data between common Ruby and Apple event types</li>
42
- <li>a simple <em>embedded query language</em> for identifying one or more objects in an application's object model</li>
43
- <li>a mechanism for representing these object model "references" in human-readable form based on application-defined terminology</li>
44
- <li>a clean, <em>object oriented-like </em> syntax for ease of use.</li>
45
- </ol>
46
-
47
-
48
-
49
- <h2>"Hello World!"</h2>
50
48
 
51
49
  <p>The following script uses appscript to create a new "Hello World!" document in TextEdit:</p>
52
50
 
@@ -62,22 +60,37 @@ app('TextEdit').documents.end.make(
62
60
 
63
61
 
64
62
 
65
- <h2>Notes</h2>
63
+ <h3>Before you start...</h3>
64
+
65
+ <p>In order to use appscript effectively, you will need to understand the differences between the Apple event and Ruby object systems.</p>
66
+
67
+ <p>In contrast to the familiar object-oriented approach of other inter-process communication systems such as COM and Distributed Objects, Apple event IPC is based on a combination of <em>remote procedure calls</em> and <em>first-class queries</em> - somewhat analogous to using XPath over XML-RPC.</p>
66
68
 
67
- <p>Ruby appscript (rb-appscript) is a port of the robust, mature Python appscript (py-appscript) bridge. There are a few minor syntax and API changes to accomodate the differences between the two languages, and rb-appscript lacks the built-in help system provided by py-appscript (external help tools will be provided at a later date), but apart from that they are very similar.</p>
69
+ <p>While appscript uses an object-oriented-like syntax for conciseness and readability, like AppleScript, it behaves according to Apple event rules. As a result, Ruby users will discover that some things work differently in appscript from what they're used to. For example:</p>
68
70
 
69
- <p>Please note that rb-appscript, like py-appscript, takes a few liberties with traditional Ruby syntax and semantics in order to support the behaviours and features provided by the Apple Event Manager API. These differences are noted in later chapters.</p>
71
+ <ul>
72
+ <li>object elements are one-indexed, not zero-indexed like Ruby arrays</li>
73
+
74
+ <li>referencing a property of an application object does not automatically return the property's value (you need a <code>get</code> command for that)</li>
75
+
76
+ <li>many applications allow a single command to operate on multiple objects at the same time, providing significant performance benefits when manipulating large numbers of application objects.</li>
77
+
78
+ </ul>
79
+
80
+ <p>Chapters 2 and 3 of this manual provide further information on how Apple event IPC works and a tutorial-based introduction to the Ruby appscript bridge. Chapter 4 describes various ways of getting help when scripting applications. Chapters 5 through 12 cover the appscript API, and chapter 13 discusses techniques for optimising performance.</p>
70
81
 
71
82
 
72
83
  </div>
73
84
 
74
85
  <!-- bottom navigation -->
75
- <div class="navbar">
76
- <a href="index.html">Previous</a> | <a href="index.html">Up</a> | <a href="02_aboutappscripting.html">Next</a>
77
-
86
+
87
+ <div class="footer">
88
+ <a href="index.html">Previous</a> &bull;
89
+ <a href="index.html">Up</a> &bull;
90
+ <a href="02_aboutappscripting.html">Next</a>
91
+
92
+ <span>&copy; 2006-2008 HAS</span>
78
93
  </div>
79
94
 
80
- <!--footer-->
81
- <p class="footer">&copy; 2006-2008 HAS</p>
82
95
  </body>
83
96
  </html>