rb-appscript 0.5.1 → 0.5.2

Sign up to get free protection for your applications and to get access to all the features.
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>