rb-appscript 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +243 -0
- data/LICENSE +1 -0
- data/README +42 -0
- data/TODO +31 -0
- data/doc/aem-manual/01_introduction.html +48 -0
- data/doc/aem-manual/02_apioverview.html +89 -0
- data/doc/aem-manual/03_packingandunpackingdata.html +98 -0
- data/doc/aem-manual/04_references.html +401 -0
- data/doc/aem-manual/05_targettingapplications.html +133 -0
- data/doc/aem-manual/06_buildingandsendingevents.html +175 -0
- data/doc/aem-manual/07_findapp.html +54 -0
- data/doc/aem-manual/08_examples.html +85 -0
- data/doc/aem-manual/09_notes.html +41 -0
- data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
- data/doc/aem-manual/full.css +21 -0
- data/doc/aem-manual/index.html +43 -0
- data/doc/appscript-manual/01_introduction.html +82 -0
- data/doc/appscript-manual/02_aboutappscripting.html +244 -0
- data/doc/appscript-manual/03_quicktutorial.html +154 -0
- data/doc/appscript-manual/04_gettinghelp.html +101 -0
- data/doc/appscript-manual/05_keywordconversion.html +91 -0
- data/doc/appscript-manual/06_classesandenums.html +174 -0
- data/doc/appscript-manual/07_applicationobjects.html +181 -0
- data/doc/appscript-manual/08_realvsgenericreferences.html +86 -0
- data/doc/appscript-manual/09_referenceforms.html +232 -0
- data/doc/appscript-manual/10_referenceexamples.html +142 -0
- data/doc/appscript-manual/11_applicationcommands.html +204 -0
- data/doc/appscript-manual/12_commandexamples.html +129 -0
- data/doc/appscript-manual/13_performanceissues.html +115 -0
- data/doc/appscript-manual/14_problemapps.html +193 -0
- data/doc/appscript-manual/15_notes.html +84 -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/full.css +21 -0
- data/doc/appscript-manual/index.html +49 -0
- data/doc/appscript-manual/relationships_example.gif +0 -0
- data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
- data/doc/index.html +30 -0
- data/doc/mactypes-manual/index.html +216 -0
- data/doc/osax-manual/index.html +169 -0
- data/extconf.rb +54 -0
- data/misc/adobeunittypes.rb +14 -0
- data/misc/dump.rb +72 -0
- data/rb-appscript.gemspec +20 -0
- data/sample/AB_list_people_with_emails.rb +8 -0
- data/sample/Create_daily_iCal_todos.rb +72 -0
- data/sample/Hello_world.rb +9 -0
- data/sample/List_iTunes_playlist_names.rb +7 -0
- data/sample/Make_Mail_message.rb +29 -0
- data/sample/Open_file_in_TextEdit.rb +9 -0
- data/sample/Organize_Mail_messages.rb +57 -0
- data/sample/Print_folder_tree.rb +12 -0
- data/sample/Select_all_HTML_files.rb +8 -0
- data/sample/Set_iChat_status.rb +20 -0
- data/sample/Simple_Finder_GUI_Scripting.rb +14 -0
- data/sample/Stagger_Finder_windows.rb +21 -0
- data/sample/TextEdit_demo.rb +126 -0
- data/sample/iTunes_top40_to_html.rb +64 -0
- data/src/lib/_aem/aemreference.rb +1006 -0
- data/src/lib/_aem/codecs.rb +617 -0
- data/src/lib/_aem/connect.rb +100 -0
- data/src/lib/_aem/findapp.rb +83 -0
- data/src/lib/_aem/mactypes.rb +228 -0
- data/src/lib/_aem/send.rb +257 -0
- data/src/lib/_aem/typewrappers.rb +57 -0
- data/src/lib/_appscript/defaultterminology.rb +245 -0
- data/src/lib/_appscript/referencerenderer.rb +132 -0
- data/src/lib/_appscript/reservedkeywords.rb +107 -0
- data/src/lib/_appscript/terminology.rb +314 -0
- data/src/lib/aem.rb +216 -0
- data/src/lib/appscript.rb +830 -0
- data/src/lib/kae.rb +1484 -0
- data/src/lib/osax.rb +171 -0
- data/src/rbae.c +766 -0
- data/test/README +1 -0
- data/test/test_aemreference.rb +112 -0
- data/test/test_appscriptreference.rb +102 -0
- data/test/test_codecs.rb +159 -0
- data/test/test_findapp.rb +24 -0
- data/test/test_mactypes.rb +67 -0
- data/test/testall.sh +9 -0
- metadata +143 -0
|
@@ -0,0 +1,129 @@
|
|
|
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>appscript | 12. Command Examples</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>12. Command Examples</h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="11_applicationcommands.html">Previous</a> | <a href="index.html">Up</a> | <a href="13_performanceissues.html">Next</a>
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<!-- content -->
|
|
22
|
+
<div id="content">
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
<h2><code>get</code></h2>
|
|
26
|
+
|
|
27
|
+
<p>Get the name of every folder in the user's home folder:</p>
|
|
28
|
+
|
|
29
|
+
<pre><code># tell application "Finder" to get name of every folder of home
|
|
30
|
+
|
|
31
|
+
AS.app('Finder').get(AS.app.home.folders.name)</code></pre>
|
|
32
|
+
|
|
33
|
+
<p>Note that if the direct parameter is omitted from the argument list, the reference that the command is invoked on is used instead. For example, the above example would normally be written as:</p>
|
|
34
|
+
|
|
35
|
+
<pre><code>AS.app('Finder').home.folders.name.get</code></pre>
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
<h2><code>set</code></h2>
|
|
39
|
+
|
|
40
|
+
<p>Set the content of a TextEdit document:</p>
|
|
41
|
+
|
|
42
|
+
<pre><code># tell application "TextEdit" to set text of document 1 to "Hello World"
|
|
43
|
+
|
|
44
|
+
AS.app('TextEdit').documents[1].text.set('Hello World')</code></pre>
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
<h2><code>count</code></h2>
|
|
48
|
+
|
|
49
|
+
<p>Count the words in a TextEdit document:</p>
|
|
50
|
+
|
|
51
|
+
<pre><code># tell application "TextEdit" to count words of document 1
|
|
52
|
+
|
|
53
|
+
AS.app('TextEdit').documents[1].words.count</code></pre>
|
|
54
|
+
|
|
55
|
+
<p>Count the items in the current user's home folder:</p>
|
|
56
|
+
|
|
57
|
+
<pre><code>#tell application "Finder" to count items of home
|
|
58
|
+
|
|
59
|
+
AS.app('Finder').home.count(:each => :item)</code></pre>
|
|
60
|
+
|
|
61
|
+
<p>(Note that the <code>each</code> parameter is required in Finder's <code>count</code> command.)</p>
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
<h2><code>make</code></h2>
|
|
65
|
+
|
|
66
|
+
<p>Create a new TextEdit document:</p>
|
|
67
|
+
|
|
68
|
+
<pre><code># tell application "TextEdit" to make new document ¬
|
|
69
|
+
# with properties {text:"Hello World\n"}
|
|
70
|
+
|
|
71
|
+
AS.app('TextEdit').make(
|
|
72
|
+
:new => :document,
|
|
73
|
+
:with_properties => {:text => "Hello World\n"})</code></pre>
|
|
74
|
+
|
|
75
|
+
<p>Append text to a TextEdit document:</p>
|
|
76
|
+
|
|
77
|
+
<pre><code># tell application "TextEdit" to make new paragraph ¬
|
|
78
|
+
# at end of text of document 1 ¬
|
|
79
|
+
# with properties {text:"Yesterday\nToday\nTomorrow\n"}
|
|
80
|
+
|
|
81
|
+
AS.app('TextEdit').make(
|
|
82
|
+
:new => :paragraph,
|
|
83
|
+
:at => AS.app.documents[1].text.end,
|
|
84
|
+
:with_data => "Yesterday\nToday\nTomorrow\n")</code></pre>
|
|
85
|
+
|
|
86
|
+
<p>Note that the <code>make</code> command's <code>at</code> parameter can be omitted for convenience, in which case the reference that the command is invoked on is used instead:</p>
|
|
87
|
+
|
|
88
|
+
<pre><code>AS.app('TextEdit').documents[1].text.end.make(
|
|
89
|
+
:new => :paragraph,
|
|
90
|
+
:with_data => "Yesterday\nToday\nTomorrow\n")</code></pre>
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
<h2><code>duplicate</code></h2>
|
|
94
|
+
|
|
95
|
+
<p>Duplicate a folder to a disk, replacing an existing item if one exists:</p>
|
|
96
|
+
|
|
97
|
+
<pre><code># tell application "Finder" to ¬
|
|
98
|
+
# duplicate folder "Projects" of home to disk "Work" with replacing
|
|
99
|
+
|
|
100
|
+
AS.app('Finder').home.folders['Projects'].duplicate(
|
|
101
|
+
:to => AS.app.disks['Backup'], :replacing => true)</code></pre>
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
<h2><code>add</code></h2>
|
|
105
|
+
|
|
106
|
+
<p>Add every person with a known birthday to a group named "Birthdays":</p>
|
|
107
|
+
|
|
108
|
+
<pre><code># tell application "Address Book" to add ¬
|
|
109
|
+
# every person whose birth date is not missing value ¬
|
|
110
|
+
# to group "Birthdays"
|
|
111
|
+
|
|
112
|
+
AS.app('Address Book').people[
|
|
113
|
+
AS.its.birth_date.ne(:missing_value)
|
|
114
|
+
].add(:to => AS.app.groups['Birthdays'])</code></pre>
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
</div>
|
|
119
|
+
|
|
120
|
+
<!-- bottom navigation -->
|
|
121
|
+
<div class="navbar">
|
|
122
|
+
<a href="11_applicationcommands.html">Previous</a> | <a href="index.html">Up</a> | <a href="13_performanceissues.html">Next</a>
|
|
123
|
+
|
|
124
|
+
</div>
|
|
125
|
+
|
|
126
|
+
<!--footer-->
|
|
127
|
+
<p class="footer">© 2006 HAS</p>
|
|
128
|
+
</body>
|
|
129
|
+
</html>
|
|
@@ -0,0 +1,115 @@
|
|
|
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>appscript | 13. Performance Issues</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>13. Performance Issues</h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_problemapps.html">Next</a>
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<!-- content -->
|
|
22
|
+
<div id="content">
|
|
23
|
+
<h2>About Performance</h2>
|
|
24
|
+
|
|
25
|
+
<p>Application scripting is subject to a number of potential performance bottlenecks:</p>
|
|
26
|
+
|
|
27
|
+
<ul>
|
|
28
|
+
<li>Sending Apple events is more expensive than calling local functions.</li>
|
|
29
|
+
|
|
30
|
+
<li>There may be significant overheads in how applications resolve individual object references.</li>
|
|
31
|
+
|
|
32
|
+
<li>Packing and unpacking large and/or complex values (e.g. a long list of object specifiers) can take an appreciable amount of time.</li>
|
|
33
|
+
</ul>
|
|
34
|
+
|
|
35
|
+
<p>Fortunately, it's often possible to minimise performance overheads by using fewer commands to do more work. Let's consider a typical example: obtaining the name of every person in <code>Address Book.app</code> who has a particular email address. There are several possible solutions to this, each with very different performance characteristics:</p>
|
|
36
|
+
|
|
37
|
+
<h2>The iterative OO-style approach</h2>
|
|
38
|
+
|
|
39
|
+
<p>While iterating over application objects and manipulating each in turn is a common technique, it's also the slowest by far:</p>
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
desiredEmail = 'sam.brown@foo.com'
|
|
43
|
+
|
|
44
|
+
foundNames = []
|
|
45
|
person.emails.get.each do |email|
|
|
1
46
|
if email.value.get == desiredEmail
|
|
2
47
|
foundNames.push(person.name.get)
|
|
48
|
+
end
|
|
49
|
+
end
|
|
50
|
+
end
|
|
51
|
+
p foundNames</code></pre>
|
|
52
|
+
<p>The above script sends one Apple event to get a list of references to all people, then one Apple event for each person to get a list of references to their emails, then one Apple event for each of those emails. Thus the time taken increases directly in proportion to the number of people in Address Book. If there's hundreds of people to search, that's hundreds of Apple events to be built, sent and individually resolved, and performance suffers as a result.</p>
|
|
53
|
+
|
|
54
|
+
<p>The solution, where possible, is to use fewer, more sophisticated commands to do the same job.</p>
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
<h2>The smart query-oriented approach</h2>
|
|
58
|
+
|
|
59
|
+
<p>While there are some situations where iterating over and manipulating each application object individually is the only option (for example, when setting a property in each object to a different value), in this case there is plenty of room for improvement. Depending on how well an application implements its AEOM support, it's possible to construct queries that identify more than one application object at a time, allowing a single command to manipulate multiple objects in a single operation.</p>
|
|
60
|
+
|
|
61
|
+
<p>In this case, the entire search can be performed using a single complex query sent to Address Book via a single Apple event:</p>
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
desiredEmail = 'sam.brown@foo.com'
|
|
65
|
+
AS.its.emails.value.contains(desiredEmail)
|
|
66
|
+
].name.get</code></pre>
|
|
67
|
+
|
|
68
|
+
<p>To explain:</p>
|
|
69
|
+
|
|
70
|
+
<ul>
|
|
71
|
+
<li>The query states: find the name of every person object that passes a specific test.</li>
|
|
72
|
+
|
|
73
|
+
<li>The test is: does a given value, 'sam.brown@foo.com', appear in a list that consists of the value of each email object contained by an individual person?</li>
|
|
74
|
+
|
|
75
|
+
<li>The command is: evaluate that query against the AEOM and get (return) the result, which is a list of zero or more strings: the names of the people matched by the query.</li>
|
|
76
|
+
</ul>
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
<h2>The hybrid solution</h2>
|
|
80
|
+
|
|
81
|
+
<p>While AEOM queries can be surprisingly powerful, there are still many problems too complex for the application to evaluate entirely by itself. For example, let's say that you want to obtain the name of every person who has an email addresses that uses a particular domain name. Unfortunately, this test is too complex to express as a single AEOM query; however, it can still be solved reasonably efficiently by obtaining all the data from the application up-front and processing it locally. For this we need: 1. the name of every person in the Address Book, and 2. each person's email addresses. Fortunately, each of these can be expressed in a single query, allowing all this data to be retrieved using just two <code>get</code> commands.</p>
|
|
82
|
+
|
|
83
|
+
<pre><code>require "appscript"
|
|
84
|
+
|
|
85
|
+
desiredDomain = 'foo.com'
|
|
86
|
+
|
|
87
|
+
domainPattern = Regexp.new(Regexp.escape('@'+desiredDomain) + '$')
|
|
88
|
+
|
|
89
|
+
# get a list of name strings
|
|
90
|
+
names = AS.app('Address Book').people.name.get
|
|
91
|
+
|
|
92
|
+
# a list of lists of email strings
|
|
93
|
+
emailsOfEveryPerson = AS.app('Address Book').people.emails.value.get
|
|
94
|
+
|
|
95
|
+
result = []
|
|
96
|
+
names.zip(emailsOfEveryPerson).each do |name, emails|
|
|
97
|
+
emails.each do |email|
|
|
98
|
+
if domainPattern.match(email):
|
|
99
|
+
result.push(name)
|
|
100
|
+
break
|
|
101
|
+
end
|
|
102
|
+
end
|
|
103
|
+
end
|
|
104
|
+
p result</code></pre>
|
|
105
|
+
|
|
106
|
+
<p>This solution isn't as fast as the pure-query approach, but is still far more efficient than iterating over and manipulating each of the application objects themselves.</p>
|
|
107
|
+
</div>
|
|
108
|
+
|
|
109
|
+
<!-- bottom navigation -->
|
|
110
|
+
<div class="navbar">
|
|
111
|
+
<a href="12_commandexamples.html">Previous</a> | <a href="index.html">Up</a> | <a href="14_problemapps.html">Next</a>
|
|
112
|
+
|
|
113
|
+
</div>
|
|
114
|
+
|
|
115
|
+
<!--footer-->
|
|
116
|
+
<p class="footer">© 2006 HAS</p>
|
|
117
|
+
</body>
|
|
118
|
+
</html>
|
|
@@ -0,0 +1,193 @@
|
|
|
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>appscript | 14. Dealing With Problem Applications</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>14. Dealing With Problem Applications</h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="13_performanceissues.html">Previous</a> | <a href="index.html">Up</a> | <a href="15_notes.html">Next</a>
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<!-- content -->
|
|
22
|
+
<div id="content">
|
|
23
|
+
|
|
24
|
+
<p>Appscript provides a number of mechanisms for dealing with problematic applications. The following topics are currently covered:</p>
|
|
25
|
+
|
|
26
|
+
<ul>
|
|
27
|
+
<li><a href="#defective_terminology">Dealing with defective terminology</a></li>
|
|
28
|
+
<li><a href="#non_stay_open_applications">Scripting non-stay-open applications</a></li>
|
|
29
|
+
</ul>
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
<!-- TO DO:
|
|
33
|
+
- patching AS_app_data codecs
|
|
34
|
+
- adding application-specific unit types
|
|
35
|
+
- FSRef/FileURL/FSSpec, string/unicode/international text compatibility issues with older apps
|
|
36
|
+
-->
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
<h2><a name="defective_terminology"></a>Dealing with defective terminology</h2>
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
<p>There are two ways to work around missing or incorrect terminology: use <code>aem</code> or use the <code>dump</code> tool.</p>
|
|
43
|
+
|
|
44
|
+
<h3>Use aem</h3>
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
<p>If faulty terminology prevents you from correctly constructing an appscript reference or command, one solution is to use the lower-level aem module, which uses raw codes instead of human-readable names. (You can use the <a href="http://sourceforge.net/project/showfiles.php?group_id=175009">ASDictionary</a> application to obtain a plain text listing of raw codes from an application's terminology resource.)</p>
|
|
48
|
+
|
|
49
|
+
<p>Note that you can obtain an aem reference from an existing appscript reference by calling its <code>AS_aem_reference</code> method. You can also pass an aem reference as a parameter to an appscript command. (You cannot use an appscript reference in an aem event, however; you have to extract its aem reference and use that.)</p>
|
|
50
|
+
|
|
51
|
+
<p>For example:</p>
|
|
52
|
+
|
|
53
|
+
<pre><code>aem_ref = AS.app('TextEdit').documents[1].text.AS_aem_reference
|
|
54
|
+
|
|
55
|
+
# aem_ref contains an aem reference:
|
|
56
|
+
# app.elements('docu').by_index(1).elements('ctxt')
|
|
57
|
+
|
|
58
|
+
app('TextEdit').get(aem_ref)</code></pre>
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
<p class="hilitebox">Note that the rb-aem documentation is not yet available; for now, refer to the py-aem documentation (rb-aem's API is virtually identical to py-aem's) and rb-aem source code for more information.</p>
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
<h3>Use dump</h3>
|
|
66
|
+
|
|
67
|
+
<p>Another way to deal with buggy or imcomplete application terminology is to export it as a Ruby module and correct it by hand. Appscript can then use the terminology data from this module instead of the broken terminology from the application itself.</p>
|
|
68
|
+
|
|
69
|
+
<p>Exporting an application's terminology is done using the <code>dump.rb</code> script located in the <code>misc</code> folder. This script is designed to be run from the command line, and takes three arguments: the name or path of the application whose terminology you wish to export, followed by the new module's Ruby name and file path. For example:</p>
|
|
70
|
+
|
|
71
|
+
<pre><code>ruby dump.rb iCal.app ICalTerminology ~/ical_terms.rb</code></pre>
|
|
72
|
+
|
|
73
|
+
<p>The dump tool will generate a new Ruby module similar to the following:</p>
|
|
74
|
+
|
|
75
|
+
<pre><code>module ICalTerminology
|
|
76
|
+
Version = 1.1
|
|
77
|
+
Path = "/Applications/iCal.app"
|
|
78
|
+
|
|
79
|
+
Classes = [
|
|
80
|
+
["application", "capp"],
|
|
81
|
+
["attachment", "atts"],
|
|
82
|
+
["attendee", "wrea"],
|
|
83
|
+
...
|
|
84
|
+
]
|
|
85
|
+
|
|
86
|
+
Enumerators = [
|
|
87
|
+
["accepted", "E6ap"],
|
|
88
|
+
["ask", "ask "],
|
|
89
|
+
...
|
|
90
|
+
]
|
|
91
|
+
|
|
92
|
+
Properties = [
|
|
93
|
+
["allday_event", "wrad"],
|
|
94
|
+
["bounds", "pbnd"],
|
|
95
|
+
...
|
|
96
|
+
]
|
|
97
|
+
|
|
98
|
+
Elements = [
|
|
99
|
+
["applications", "capp"],
|
|
100
|
+
["attachment", "atts"],
|
|
101
|
+
...
|
|
102
|
+
]
|
|
103
|
+
|
|
104
|
+
Commands = [
|
|
105
|
+
["GetURL", "GURLGURL", [
|
|
106
|
+
]],
|
|
107
|
+
["close", "coreclos", [
|
|
108
|
+
["saving", "savo"],
|
|
109
|
+
["saving_in", "kfil"],
|
|
110
|
+
]],
|
|
111
|
+
...
|
|
112
|
+
]
|
|
113
|
+
end</code></pre>
|
|
114
|
+
|
|
115
|
+
<p>Every terminology module contains the following constants:</p>
|
|
116
|
+
|
|
117
|
+
<dl>
|
|
118
|
+
<dt>Version</dt>
|
|
119
|
+
<dd>Indicates the terminology module's format. This is currently 1.1.</dd>
|
|
120
|
+
|
|
121
|
+
<dt>Path</dt>
|
|
122
|
+
<dd>The application from which this terminology was obtained.</dd>
|
|
123
|
+
|
|
124
|
+
<dt>Classes</dt>
|
|
125
|
+
<dd>A list of class names and their corresponding four-character codes as name-code pairs, e.g. <code>["document", "docu"]</code>.</dd>
|
|
126
|
+
|
|
127
|
+
<dt>Enumerators</dt>
|
|
128
|
+
<dd>A list of enumerator names and their corresponding four-character codes as name-code pairs, e.g. <code>["yes", "yes "]</code>.</dd>
|
|
129
|
+
|
|
130
|
+
<dt>Properties</dt>
|
|
131
|
+
<dd>A list of property names and their corresponding four-character codes as name-code pairs, e.g. <code>["name", "pnam"]</code>.</dd>
|
|
132
|
+
|
|
133
|
+
<dt>Elements</dt>
|
|
134
|
+
<dd>A list of element names and their corresponding four-character codes as name-code pairs, e.g. <code>["documents", "docu"]</code>. Note that this list should be identical to the <code>Classes</code> list, except that each element name should be the plural form of the corresponding class name.</dd>
|
|
135
|
+
|
|
136
|
+
<dt>Commands</dt>
|
|
137
|
+
<dd>A list of command names and their corresponding eight-character codes, followed by a list of keyword argument names and their corresponding four-character codes as name-code pairs, e.g. <code>["make", "corecrel", [["new", "kocl"],...]]</code>.</dd>
|
|
138
|
+
</dl>
|
|
139
|
+
|
|
140
|
+
<p>You can edit any of the five terminology lists as needed, e.g. to add missing class and element definitions, to correct faulty four-character codes, etc. (Make sure any changes are correctly formatted as appscript doesn't perform any special error checking when reading data from this module.) Once the changes are complete, place the module file somewhere on Ruby's module search path (e.g. in <code>/usr/lib/ruby/site_ruby/1.8</code>) so it can be imported into scripts when needed.</p>
|
|
141
|
+
|
|
142
|
+
<p>To use a terminology module, first import it as normal. Then, when creating a new application object for the problem application, pass this module to the constructor call as its second argument (or first argument if it's the <code>current</code> constructor). For example:</p>
|
|
143
|
+
|
|
144
|
+
<pre><code>require "appscript"
|
|
145
|
+
require "ical_terms"
|
|
146
|
+
|
|
147
|
+
ical = AS.app('iCal', ICalTerminology)
|
|
148
|
+
...</code></pre>
|
|
149
|
+
|
|
150
|
+
<p>Finally, remember to file a bug report with the application's developer so that they can fix the problem in a future release!</p>
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
<h2><a name="non_stay_open_applications">Scripting non-stay-open applications</h2>
|
|
156
|
+
|
|
157
|
+
<p>When scripting AppleScript applets and other applications that take only a single <code>run</code> or <code>open</code> event, scripts must take some additional steps to avoid problems:<p>
|
|
158
|
+
|
|
159
|
+
<ol>
|
|
160
|
+
<li>When creating an application object, the <code>:terms</code> argument must be <code>false</code>. This will prevent appscript from repeatedly starting the application in an (unsuccessful) attempt to retrieve its terminology.</li>
|
|
161
|
+
|
|
162
|
+
<li>When sending an <code>open</code> event, the application must first be started using the <code>launch</code> command to avoid it receiving the usual <code>run</code> event upon start-up.</li>
|
|
163
|
+
|
|
164
|
+
<li>Since non-stay-open applications don't reply to commands, the <code>run</code>/<code>open</code> command's <code>:wait_reply</code> argument must be <code>false</code> to prevent appscript waiting for a non-existent response.</li>
|
|
165
|
+
</ol>
|
|
166
|
+
|
|
167
|
+
<p>Examples:</p>
|
|
168
|
+
|
|
169
|
+
<pre><code>require "appscript"
|
|
170
|
+
require "macfile"
|
|
171
|
+
|
|
172
|
+
# Run
|
|
173
|
+
AS.app('Foo', false).run(:wait_reply => false)
|
|
174
|
+
|
|
175
|
+
# Open
|
|
176
|
+
bar = AS.app('Bar', false)
|
|
177
|
+
bar.launch
|
|
178
|
+
bar.open([MacFile::Alias.path('/path/to/item 1'), ...], :wait_reply => false)</code></pre>
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
</div>
|
|
183
|
+
|
|
184
|
+
<!-- bottom navigation -->
|
|
185
|
+
<div class="navbar">
|
|
186
|
+
<a href="13_performanceissues.html">Previous</a> | <a href="index.html">Up</a> | <a href="15_notes.html">Next</a>
|
|
187
|
+
|
|
188
|
+
</div>
|
|
189
|
+
|
|
190
|
+
<!--footer-->
|
|
191
|
+
<p class="footer">© 2006 HAS</p>
|
|
192
|
+
</body>
|
|
193
|
+
</html>
|
|
@@ -0,0 +1,84 @@
|
|
|
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>appscript | 15. Notes</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>15. Notes</h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="14_problemapps.html">Previous</a> | <a href="index.html">Up</a>
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<!-- content -->
|
|
22
|
+
<div id="content">
|
|
23
|
+
<h2>Security Issues</h2>
|
|
24
|
+
|
|
25
|
+
<p>If including user names and/or passwords in remote application URLs, please note that appscript retains these URLs in both the <code>Terminology</code> module's internal cache and in the Application and Reference objects subsequently created from those URLs. Security here is the user's responsibility, as it's their code that creates and retains these objects.</p>
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
<h2>GUI Scripting</h2>
|
|
29
|
+
|
|
30
|
+
<p>Non-scriptable applications may in some cases be controlled from Ruby by using System Events to manipulate their graphical user interface. Note that the "Enable access for assistive devices" checkbox must be selected in the Universal Access system preferences pane for GUI Scripting to work.</p>
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
<h2>AEDescs</h2>
|
|
34
|
+
|
|
35
|
+
<p>Some applications (e.g. QuarkXpress) may return values which appscript cannot convert to equivalent Ruby types. These values are usually of types which are defined, used and understood only by that particular application, and will be represented in Ruby as raw <code>AE::AEDesc</code> objects (e.g. <code>#<AE::AEDesc:0x33fc40></code>). While there's not much you can do with raw <code>AEDesc</code> objects within Ruby (it's best just to treat them as opaque types), subsequent commands can pass them back to the application for further use and/or conversion just like any other value.</p>
|
|
36
|
+
|
|
37
|
+
<!--
|
|
38
|
+
<h2>aemcodegen</h2>
|
|
39
|
+
|
|
40
|
+
<p>The <code>appscript.tools.aemcodegen</code> module is an convenience tool for translating appscript commands into their aem equivalents; useful if you want to control applications using the lower-level aem package. See the <code>aemcodegen</code> module's docstring for more information.</p>
|
|
41
|
+
-->
|
|
42
|
+
|
|
43
|
+
<h2>Appscript and threads</h2>
|
|
44
|
+
|
|
45
|
+
<p>When using appscript in multi-threaded systems, always send application commands from the main thread. (This is a limitation of the underlying aem package, which currently doesn't support receiving reply events on non-main threads.)</p>
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
<h2>Credits</h2>
|
|
49
|
+
|
|
50
|
+
<p>Many thanks to Bill Birkett, Jordan Breeding, FUJIMOTO Hisakuni, Alexander Kellett, Chris Nebel, Matt Neuburg, Laurent Sansonetti and Michelle Steiner, and to all those who have contributed comments, suggestions and bug reports to py-appscript.</p>
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
<h2>Donations</h2>
|
|
54
|
+
|
|
55
|
+
<p>You can <a href="http://sourceforge.net/donate/index.php?group_id=175009">donate to the appscript project</a> via SourceForge.net. Special thanks to all those appscript users who have already contributed.</p>
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
<h2>Copyright</h2>
|
|
59
|
+
|
|
60
|
+
<p>(C) 2006 HAS -- hhas -at- users - sourceforge - net; <a href="http://rb-appscript.rubyforge.org">http://rb-appscript.rubyforge.org</a></p>
|
|
61
|
+
|
|
62
|
+
<p>Appscript is released under the <a href="License.txt">MIT License</a>.</p>
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
<h2>Useful Links</h2>
|
|
66
|
+
|
|
67
|
+
<ul>
|
|
68
|
+
<li><a href="http://www.cs.utexas.edu/users/wcook/papers/AppleScript/AppleScript95.pdf">The Open Scripting Architecture: Automating, Integrating, and Customizing Applications</a> (Cook & Harris, 1993) -- An excellent overview of the OSA infrastructure, which includes Apple event-based application scripting. (PDF)</li>
|
|
69
|
+
|
|
70
|
+
</ul>
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
</div>
|
|
74
|
+
|
|
75
|
+
<!-- bottom navigation -->
|
|
76
|
+
<div class="navbar">
|
|
77
|
+
<a href="14_problemapps.html">Previous</a> | <a href="index.html">Up</a>
|
|
78
|
+
|
|
79
|
+
</div>
|
|
80
|
+
|
|
81
|
+
<!--footer-->
|
|
82
|
+
<p class="footer">© 2006 HAS</p>
|
|
83
|
+
</body>
|
|
84
|
+
</html>
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
body {font-family: sans-serif; line-height:140%; color:#000; background-color:#fff; margin: 0 10%;}
|
|
2
|
+
|
|
3
|
+
#content {margin:2em 0 2.25em;}
|
|
4
|
+
dt {font-weight:bold;}
|
|
5
|
+
|
|
6
|
+
.comment {color:#666; background-color:transparent;}
|
|
7
|
+
|
|
8
|
+
hr {height: 1px; background-color: #114; border: 0px solid #114;}
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
table {line-height:130%; width:100%; color:#000; background-color:#e8e8ff; border:dotted black 1px; margin:1.2em 0em 2.4em; padding: 0 0 1em;}
|
|
12
|
+
|
|
13
|
+
th, td {padding: 0.4em 1.6em; margin: 0; border-width: 0;}
|
|
14
|
+
|
|
15
|
+
th {text-align:left; font-size:0.95em; color:#225; background-color:#ccd;}
|
|
16
|
+
|
|
17
|
+
thead {background-color:#ccd;}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
h1+.navbar {margin-top:0;
|
|
21
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
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>appscript | Contents</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>Contents</h1>
|
|
14
|
+
|
|
15
|
+
<!-- top navigation -->
|
|
16
|
+
<div class="navbar">
|
|
17
|
+
<a href="01_introduction.html">Next</a>
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
<!-- content -->
|
|
22
|
+
<div id="content"><ol>
|
|
23
|
+
<li><a href="01_introduction.html">Introduction</a></li>
|
|
24
|
+
<li><a href="02_aboutappscripting.html">About Application Scripting</a></li>
|
|
25
|
+
<li><a href="03_quicktutorial.html">Quick Tutorial</a></li>
|
|
26
|
+
<li><a href="04_gettinghelp.html">Getting Help</a></li>
|
|
27
|
+
<li><a href="05_keywordconversion.html">Keyword Conversion</a></li>
|
|
28
|
+
<li><a href="06_classesandenums.html">Classes and Enumerated Types</a></li>
|
|
29
|
+
<li><a href="07_applicationobjects.html">Application Objects</a></li>
|
|
30
|
+
<li><a href="08_realvsgenericreferences.html">Real vs Generic References</a></li>
|
|
31
|
+
<li><a href="09_referenceforms.html">Reference Forms</a></li>
|
|
32
|
+
<li><a href="10_referenceexamples.html">Reference Examples</a></li>
|
|
33
|
+
<li><a href="11_applicationcommands.html">Application Commands</a></li>
|
|
34
|
+
<li><a href="12_commandexamples.html">Command Examples</a></li>
|
|
35
|
+
<li><a href="13_performanceissues.html">Performance Issues</a></li>
|
|
36
|
+
<li><a href="14_problemapps.html">Dealing With Problem Applications</a></li>
|
|
37
|
+
<li><a href="15_notes.html">Notes</a></li>
|
|
38
|
+
</ol></div>
|
|
39
|
+
|
|
40
|
+
<!-- bottom navigation -->
|
|
41
|
+
<div class="navbar">
|
|
42
|
+
<a href="01_introduction.html">Next</a>
|
|
43
|
+
|
|
44
|
+
</div>
|
|
45
|
+
|
|
46
|
+
<!--footer-->
|
|
47
|
+
<p class="footer">© 2006 HAS</p>
|
|
48
|
+
</body>
|
|
49
|
+
</html>
|
|
Binary file
|
|
Binary file
|
data/doc/index.html
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
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>Appscript Documentation</title>
|
|
6
|
+
|
|
7
|
+
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
8
|
+
<style type="text/css" media="all"><!--@import url(appscript-manual/full.css);--></style>
|
|
9
|
+
|
|
10
|
+
</head>
|
|
11
|
+
<body>
|
|
12
|
+
|
|
13
|
+
<h1>Appscript Documentation</h1>
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
<!-- content -->
|
|
17
|
+
<div id="content">
|
|
18
|
+
|
|
19
|
+
<ol>
|
|
20
|
+
<li><a href="appscript-manual/index.html">appscript manual</a></li>
|
|
21
|
+
<li><a href="mactypes-manual/index.html">mactypes manual</a></li>
|
|
22
|
+
<li><a href="osax-manual/index.html">osax manual</a></li>
|
|
23
|
+
<li><a href="aem-manual/index.html">aem manual</a></li>
|
|
24
|
+
</ol>
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
</body>
|
|
30
|
+
</html>
|