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.
- data/CHANGES +30 -0
- data/LICENSE +1 -1
- data/README +7 -3
- data/TODO +7 -1
- data/doc/aem-manual/01_introduction.html +23 -9
- data/doc/aem-manual/02_apioverview.html +25 -11
- data/doc/aem-manual/03_packingandunpackingdata.html +22 -17
- data/doc/aem-manual/04_references.html +49 -36
- data/doc/aem-manual/05_targettingapplications.html +25 -14
- data/doc/aem-manual/06_buildingandsendingevents.html +47 -21
- data/doc/aem-manual/07_findapp.html +22 -11
- data/doc/aem-manual/08_examples.html +21 -10
- data/doc/aem-manual/index.html +28 -12
- data/doc/appscript-manual/01_introduction.html +40 -27
- data/doc/appscript-manual/02_aboutappscripting.html +28 -15
- data/doc/appscript-manual/03_quicktutorial.html +29 -16
- data/doc/appscript-manual/04_gettinghelp.html +31 -16
- data/doc/appscript-manual/05_keywordconversion.html +23 -10
- data/doc/appscript-manual/06_classesandenums.html +32 -19
- data/doc/appscript-manual/07_applicationobjects.html +31 -18
- data/doc/appscript-manual/08_realvsgenericreferences.html +23 -11
- data/doc/appscript-manual/09_referenceforms.html +33 -20
- data/doc/appscript-manual/10_referenceexamples.html +30 -17
- data/doc/appscript-manual/11_applicationcommands.html +25 -13
- data/doc/appscript-manual/12_commandexamples.html +26 -15
- data/doc/appscript-manual/13_performanceissues.html +46 -20
- data/doc/appscript-manual/14_notes.html +29 -19
- data/doc/appscript-manual/index.html +27 -11
- data/doc/full.css +95 -9
- data/doc/index.html +27 -10
- data/doc/mactypes-manual/01_introduction.html +56 -0
- data/doc/mactypes-manual/02_aliasclass.html +134 -0
- data/doc/mactypes-manual/03_fileurlclass.html +136 -0
- data/doc/mactypes-manual/04_unitsclass.html +102 -0
- data/doc/mactypes-manual/index.html +26 -227
- data/doc/osax-manual/01_introduction.html +69 -0
- data/doc/osax-manual/02_interface.html +149 -0
- data/doc/osax-manual/03_examples.html +75 -0
- data/doc/osax-manual/04_notes.html +80 -0
- data/doc/osax-manual/index.html +26 -195
- data/doc/rb-appscript-logo.png +0 -0
- data/rb-appscript.gemspec +2 -2
- data/sample/TextEdit_demo.rb +1 -1
- data/src/lib/_aem/aemreference.rb +1 -1
- data/src/lib/_aem/codecs.rb +42 -8
- data/src/lib/_aem/connect.rb +3 -1
- data/src/lib/_aem/findapp.rb +1 -1
- data/src/lib/_aem/mactypes.rb +1 -1
- data/src/lib/_aem/send.rb +162 -142
- data/src/lib/_aem/typewrappers.rb +2 -2
- data/src/lib/_appscript/defaultterminology.rb +76 -46
- data/src/lib/_appscript/referencerenderer.rb +1 -1
- data/src/lib/_appscript/reservedkeywords.rb +2 -2
- data/src/lib/_appscript/safeobject.rb +1 -1
- data/src/lib/_appscript/terminology.rb +30 -19
- data/src/lib/aem.rb +1 -6
- data/src/lib/appscript.rb +65 -20
- data/src/lib/osax.rb +21 -18
- data/src/rbae.c +1 -1
- data/test/test_appscriptcommands.rb +1 -1
- metadata +12 -3
|
@@ -0,0 +1,149 @@
|
|
|
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-osax manual | 2. Interface</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_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
|
+
<strong><a href="../osax-manual/index.html">osax</a></strong> /
|
|
25
|
+
<a href="../aem-manual/index.html">aem</a>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>2. Interface</h2>
|
|
33
|
+
|
|
34
|
+
<h3>The <code>scriptingadditions</code> method</h3>
|
|
35
|
+
|
|
36
|
+
<p>The <code>OSAX.scripting_additions</code> method returns the names of all installed scripting additions:</p>
|
|
37
|
+
|
|
38
|
+
<pre><code>require "osax"
|
|
39
|
+
|
|
40
|
+
p OSAX.scripting_additions
|
|
41
|
+
# Result: ["Digital Hub Scripting", "StandardAdditions", ...]</code></pre>
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
<h3>The <code>osax</code> method</h3>
|
|
45
|
+
|
|
46
|
+
<p>The <code>OSAX.osax</code> method provides a convenient shortcut for creating new <code>ScriptingAddition</code> instances.</p>
|
|
47
|
+
|
|
48
|
+
<pre><code>osax(name=nil, app_name=nil) -- convenience method for
|
|
49
|
+
creating a new ScriptingAddition instance
|
|
50
|
+
name : String | nil -- scripting addition's name
|
|
51
|
+
(nil = "StandardAdditions")
|
|
52
|
+
app_name : String | nil -- target application's name/path, or nil
|
|
53
|
+
for current application
|
|
54
|
+
Result : ScriptingAddition</code></pre>
|
|
55
|
+
|
|
56
|
+
<p>For example:</p>
|
|
57
|
+
|
|
58
|
+
<pre><code>require "osax"
|
|
59
|
+
|
|
60
|
+
sa = OSAX.osax
|
|
61
|
+
|
|
62
|
+
p sa
|
|
63
|
+
# Result: #<OSAX::ScriptingAddition
|
|
64
|
+
# name="StandardAdditions"
|
|
65
|
+
# target=AEM::Application.current></code></pre>
|
|
66
|
+
|
|
67
|
+
<p>In addition, the <code>osax</code> function accepts an application name as an optional second argument, allowing you to specify the application you want to handle the scripting addition's commands, e.g.:</p>
|
|
68
|
+
|
|
69
|
+
<pre><code>OSAX.osax("StandardAdditions", "System Events")</code></pre>
|
|
70
|
+
|
|
71
|
+
<p>is shorthand for:</p>
|
|
72
|
+
|
|
73
|
+
<pre><code>OSAX::ScriptingAddition.new("StandardAdditions").by_name("System Events")</code></pre>
|
|
74
|
+
|
|
75
|
+
<p>To specify applications by other means (e.g. URL), create a <code>ScriptingAddition</code> object first, then call the appropriate <code>by...</code> method.</p>
|
|
76
|
+
|
|
77
|
+
<p>For convenience, if both arguments are nil then a <code>ScriptingAddition</code> object for StandardAdditions is created and returned. This object is also cached internally for efficiency and returned as-is in subsequent calls; thus, for example:</p>
|
|
78
|
+
|
|
79
|
+
<pre><code>sa = osax
|
|
80
|
+
sa.some_command
|
|
81
|
+
sa.another_command</code></pre>
|
|
82
|
+
|
|
83
|
+
<p>could also be written as:</p>
|
|
84
|
+
|
|
85
|
+
<pre><code>osax.some_command
|
|
86
|
+
osax.another_command</code></pre>
|
|
87
|
+
|
|
88
|
+
<p>without the additional overhead of creating a new ScriptingAddition object each time.</p>
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
<h3>The <code>ScriptingAddition</code> class</h3>
|
|
92
|
+
|
|
93
|
+
<pre><code>ScriptingAddition -- represents a single scripting addition and its
|
|
94
|
+
target application
|
|
95
|
+
|
|
96
|
+
Constructors:
|
|
97
|
+
|
|
98
|
+
ScriptingAddition.new(name, terms=nil) -- make a ScriptingAddition
|
|
99
|
+
object for the specified scripting addition, targeted
|
|
100
|
+
at the current application
|
|
101
|
+
|
|
102
|
+
name: string -- a scripting addition's name,
|
|
103
|
+
e.g. "StandardAdditions"; basically its filename
|
|
104
|
+
minus the '.osax' suffix
|
|
105
|
+
|
|
106
|
+
terms : module or nil -- an optional terminology glue
|
|
107
|
+
module,as exported by Terminology.dump; if
|
|
108
|
+
given, ScriptingAddition will use this instead
|
|
109
|
+
of retrieving the terminology dynamically
|
|
110
|
+
|
|
111
|
+
Methods:
|
|
112
|
+
|
|
113
|
+
# Introspection:
|
|
114
|
+
|
|
115
|
+
commands -- returns names of all available commands
|
|
116
|
+
|
|
117
|
+
parameters(command_name) -- returns a command's parameter names
|
|
118
|
+
|
|
119
|
+
# Specifying a different target application:
|
|
120
|
+
|
|
121
|
+
# Each of the following methods returns a new ScriptingAddition
|
|
122
|
+
# instance targeted at the specified application. The arguments
|
|
123
|
+
# are the same as for the by_name, by_creator, etc. methods in
|
|
124
|
+
# appscript.
|
|
125
|
+
|
|
126
|
+
by_name(name) -- name or full path of application, e.g. "Finder"
|
|
127
|
+
|
|
128
|
+
by_creator(creator) -- four-character creator code, e.g. "ttxt"
|
|
129
|
+
|
|
130
|
+
by_id(id) -- bundle id, e.g. "com.apple.ical"
|
|
131
|
+
|
|
132
|
+
by_pid(pid) -- Unix process ID, e.g. 4005
|
|
133
|
+
|
|
134
|
+
by_url(url) -- eppc URL, e.g. "eppc://jukebox-mac.local/iTunes"</code></pre>
|
|
135
|
+
|
|
136
|
+
</div>
|
|
137
|
+
|
|
138
|
+
<!-- bottom navigation -->
|
|
139
|
+
|
|
140
|
+
<div class="footer">
|
|
141
|
+
<a href="01_introduction.html">Previous</a> •
|
|
142
|
+
<a href="index.html">Up</a> •
|
|
143
|
+
<a href="03_examples.html">Next</a>
|
|
144
|
+
|
|
145
|
+
<span>© 2006-2008 HAS</span>
|
|
146
|
+
</div>
|
|
147
|
+
|
|
148
|
+
</body>
|
|
149
|
+
</html>
|
|
@@ -0,0 +1,75 @@
|
|
|
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-osax manual | 3. 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><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_interface.html">Previous</a> •
|
|
18
|
+
<a href="index.html">Up</a> •
|
|
19
|
+
<a href="04_notes.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
|
+
<strong><a href="../osax-manual/index.html">osax</a></strong> /
|
|
25
|
+
<a href="../aem-manual/index.html">aem</a>
|
|
26
|
+
</span>
|
|
27
|
+
</div>
|
|
28
|
+
|
|
29
|
+
<!-- content -->
|
|
30
|
+
<div id="content">
|
|
31
|
+
|
|
32
|
+
<h2>3. Examples</h2>
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
<pre><code>require "osax"
|
|
36
|
+
|
|
37
|
+
# Create a new ScriptingAddition object:
|
|
38
|
+
|
|
39
|
+
sa = OSAX.osax
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
# List all available commands:
|
|
43
|
+
|
|
44
|
+
p sa.commands
|
|
45
|
+
# Result: ["ASCII_character", "ASCII_number", "activate", ...]
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
# Call some commands:
|
|
49
|
+
|
|
50
|
+
sa.beep
|
|
51
|
+
|
|
52
|
+
p sa.path_to(:scripts_folder)
|
|
53
|
+
# Result: MacTypes::Alias.at("/Users/foo/Library/Scripts/")
|
|
54
|
+
|
|
55
|
+
p sa.display_dialog("Ruby says hello!",
|
|
56
|
+
:buttons=>["Hi!", "Howdy!", "Duuuude!"],
|
|
57
|
+
:default_button=>3)
|
|
58
|
+
# Result: {:button_returned=>"Howdy!"}</code></pre>
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
</div>
|
|
63
|
+
|
|
64
|
+
<!-- bottom navigation -->
|
|
65
|
+
|
|
66
|
+
<div class="footer">
|
|
67
|
+
<a href="02_interface.html">Previous</a> •
|
|
68
|
+
<a href="index.html">Up</a> •
|
|
69
|
+
<a href="04_notes.html">Next</a>
|
|
70
|
+
|
|
71
|
+
<span>© 2006-2008 HAS</span>
|
|
72
|
+
</div>
|
|
73
|
+
|
|
74
|
+
</body>
|
|
75
|
+
</html>
|
|
@@ -0,0 +1,80 @@
|
|
|
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-osax manual | 4. 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><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_examples.html">Previous</a> •
|
|
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
|
+
<strong><a href="../osax-manual/index.html">osax</a></strong> /
|
|
24
|
+
<a href="../aem-manual/index.html">aem</a>
|
|
25
|
+
</span>
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
<!-- content -->
|
|
29
|
+
<div id="content">
|
|
30
|
+
|
|
31
|
+
<h2>4. Notes</h2>
|
|
32
|
+
|
|
33
|
+
<h3>GUI interaction</h3>
|
|
34
|
+
|
|
35
|
+
<p>When using scripting addition commands that require GUI access (e.g. <code>display_dialog</code>) targeted at the command-line Ruby interpreter, the osax module will automatically convert the non-GUI interpreter process into a full GUI process to allow these commands to operate correctly. If you want to avoid this, target these commands at a faceless GUI application such as System Events instead:</p>
|
|
36
|
+
|
|
37
|
+
<pre><code>sa = OSAX.osax("StandardAdditions", "System Events")
|
|
38
|
+
sa.activate # give focus to System Events
|
|
39
|
+
p sa.display_dialog("Ruby says hello!",
|
|
40
|
+
:buttons=>["Hi!", "Howdy!", "Duuuude!"],
|
|
41
|
+
:default_button=>3)
|
|
42
|
+
# Result: {:button_returned=>"Duuuude!"}</code></pre>
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
<h3>64-bit limitations</h3>
|
|
46
|
+
|
|
47
|
+
<p>The <code>OSAX</code> module currently only supports dynamic retrieval of scripting addition terminology when running in 32-bit processes. To use it in 64-bit processes, use the <code>Terminology</code> module's <code>dump</code> method to export a static terminology 'glue' module for the desired scripting addition (running it in a 32-bit process), then import that module and pass it as the second argument to the <code>ScriptingAddition</code> class's initialiser. For example, to export a glue module for Standard Additions:</p>
|
|
48
|
+
|
|
49
|
+
<pre><code>require 'appscript'
|
|
50
|
+
|
|
51
|
+
Terminology.dump('/System/Library/ScriptingAdditions/StandardAdditions.osax',
|
|
52
|
+
'StandardAdditions', 'standard_additions.rb')</code></pre>
|
|
53
|
+
|
|
54
|
+
<p>To create a new <code>ScriptingAddition</code> instance using the terminology provided by this glue module:</p>
|
|
55
|
+
|
|
56
|
+
<pre><code>require 'osax'
|
|
57
|
+
require 'standard_additions'
|
|
58
|
+
|
|
59
|
+
sa = OSAX::ScriptingAddition.new('StandardAdditions', StandardAdditions)</code></pre>
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
<h3>Known problems</h3>
|
|
63
|
+
|
|
64
|
+
<p>When using the <code>OSAX</code> module within RubyCocoa-based applications, avoid creating <code>ScriptingAddition</code> instances before the main event loop is started as this can result in the application behaving strangely (minimised windows don't expand correctly) due to a bug in OS X's <code>OSAGetAppTerminology</code> function.</p>
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
</div>
|
|
69
|
+
|
|
70
|
+
<!-- bottom navigation -->
|
|
71
|
+
|
|
72
|
+
<div class="footer">
|
|
73
|
+
<a href="03_examples.html">Previous</a> •
|
|
74
|
+
<a href="index.html">Up</a>
|
|
75
|
+
|
|
76
|
+
<span>© 2006-2008 HAS</span>
|
|
77
|
+
</div>
|
|
78
|
+
|
|
79
|
+
</body>
|
|
80
|
+
</html>
|
data/doc/osax-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>osax</title>
|
|
5
|
+
<title>rb-osax manual</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,215 +10,46 @@
|
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
|
12
12
|
|
|
13
|
-
<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
|
-
|
|
17
|
+
<a href="../index.html">Previous</a> •
|
|
18
|
+
<a href="../index.html">Up</a> •
|
|
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
|
+
<strong><a href="../osax-manual/index.html">osax</a></strong> /
|
|
25
|
+
<a href="../aem-manual/index.html">aem</a>
|
|
26
|
+
</span>
|
|
18
27
|
</div>
|
|
19
28
|
|
|
20
29
|
<!-- content -->
|
|
21
30
|
<div id="content">
|
|
22
|
-
<h2>What is osax?</h2>
|
|
23
31
|
|
|
24
|
-
<
|
|
25
|
-
|
|
26
|
-
<p>The <code>ScriptingAddition</code> class represents a single scripting addition. It is similar to an appscript application object, except that it defines commands for the specified scripting addition instead of the application's normal commands. </p>
|
|
27
|
-
|
|
28
|
-
<p>Once you've created a <code>ScriptingAddition</code> instance, you can invoke its commands in exactly the same way as you would call a scriptable application's commands in appscript.</p>
|
|
29
|
-
|
|
30
|
-
<p>For example:</p>
|
|
31
|
-
|
|
32
|
-
<pre><code>require "osax"
|
|
33
|
-
|
|
34
|
-
sa = OSAX::ScriptingAddition.new("StandardAdditions")
|
|
35
|
-
|
|
36
|
-
sa.say("Hello world", :using=>"Victoria")</code></pre>
|
|
37
|
-
|
|
38
|
-
<p>The default application commands (<code>run</code>, <code>activate</code>, <code>quit</code>, etc.) are also available; see the appscript manual for details on those.</p>
|
|
39
|
-
|
|
40
|
-
<p>By default, <code>ScriptingAddition</code> objects are targeted at the current application. You can obtain a <code>ScriptingAddition</code> object targeted at another application by calling one of its <code>by...</code> methods.</p>
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
<h2><code>OSAX.scripting_additions</code></h2>
|
|
45
|
-
|
|
46
|
-
<p>The <code>scripting_additions</code> function returns the names of all installed scripting additions:</p>
|
|
47
|
-
|
|
48
|
-
<pre><code>require "osax"
|
|
49
|
-
|
|
50
|
-
p OSAX.scripting_additions
|
|
51
|
-
# Result: ["Digital Hub Scripting", "StandardAdditions", ...]</code></pre>
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
<h2><code>OSAX.osax</code></h2>
|
|
56
|
-
|
|
57
|
-
<p>The <code>osax</code> function provides a convenient shortcut for creating new <code>ScriptingAddition</code> instances.</p>
|
|
58
|
-
|
|
59
|
-
<pre><code>osax(name=nil, app_name=nil) -- convenience method for
|
|
60
|
-
creating a new ScriptingAddition instance
|
|
61
|
-
name : String | nil -- scripting addition's name
|
|
62
|
-
(nil = "StandardAdditions")
|
|
63
|
-
app_name : String | nil -- target application's name/path, or nil
|
|
64
|
-
for current application
|
|
65
|
-
Result : ScriptingAddition</code></pre>
|
|
66
|
-
|
|
67
|
-
<p>For example:</p>
|
|
68
|
-
|
|
69
|
-
<pre><code>require "osax"
|
|
70
|
-
|
|
71
|
-
sa = OSAX.osax
|
|
72
|
-
|
|
73
|
-
p sa
|
|
74
|
-
# Result: #<OSAX::ScriptingAddition
|
|
75
|
-
# name="StandardAdditions"
|
|
76
|
-
# target=AEM::Application.current></code></pre>
|
|
77
|
-
|
|
78
|
-
<p>In addition, the <code>osax</code> function accepts an application name as an optional second argument, allowing you to specify the application you want to handle the scripting addition's commands, e.g.:</p>
|
|
79
|
-
|
|
80
|
-
<pre><code>OSAX.osax("StandardAdditions", "System Events")</code></pre>
|
|
81
|
-
|
|
82
|
-
<p>is shorthand for:</p>
|
|
83
|
-
|
|
84
|
-
<pre><code>OSAX::ScriptingAddition.new("StandardAdditions").by_name("System Events")</code></pre>
|
|
85
|
-
|
|
86
|
-
<p>To specify applications by other means (e.g. URL), create a <code>ScriptingAddition</code> object first, then call the appropriate <code>by...</code> method.</p>
|
|
87
|
-
|
|
88
|
-
<p>For convenience, if both arguments are nil then a <code>ScriptingAddition</code> object for StandardAdditions is created and returned. This object is also cached internally for efficiency and returned as-is in subsequent calls; thus, for example:</p>
|
|
89
|
-
|
|
90
|
-
<pre><code>sa = osax
|
|
91
|
-
sa.some_command
|
|
92
|
-
sa.another_command</code></pre>
|
|
93
|
-
|
|
94
|
-
<p>could also be written as:</p>
|
|
95
|
-
|
|
96
|
-
<pre><code>osax.some_command
|
|
97
|
-
osax.another_command</code></pre>
|
|
98
|
-
|
|
99
|
-
<p>without the additional overhead of creating a new ScriptingAddition object each time.</p>
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
<h2><code>OSAX::ScriptingAddition</code></h2>
|
|
104
|
-
|
|
105
|
-
<pre><code>ScriptingAddition -- represents a single scripting addition and its
|
|
106
|
-
target application
|
|
107
|
-
|
|
108
|
-
Constructors:
|
|
109
|
-
|
|
110
|
-
ScriptingAddition.new(name, terms=nil) -- make a ScriptingAddition
|
|
111
|
-
object for the specified scripting addition, targeted
|
|
112
|
-
at the current application
|
|
113
|
-
|
|
114
|
-
name: string -- a scripting addition's name,
|
|
115
|
-
e.g. "StandardAdditions"; basically its filename
|
|
116
|
-
minus the '.osax' suffix
|
|
117
|
-
|
|
118
|
-
terms : module or nil -- an optional terminology glue
|
|
119
|
-
module,as exported by Terminology.dump; if
|
|
120
|
-
given, ScriptingAddition will use this instead
|
|
121
|
-
of retrieving the terminology dynamically
|
|
122
|
-
|
|
123
|
-
Methods:
|
|
124
|
-
|
|
125
|
-
# Introspection:
|
|
126
|
-
|
|
127
|
-
commands -- returns names of all available commands
|
|
128
|
-
|
|
129
|
-
parameters(command_name) -- returns a command's parameter names
|
|
130
|
-
|
|
131
|
-
# Specifying a different target application:
|
|
132
|
-
|
|
133
|
-
# Each of the following methods returns a new ScriptingAddition
|
|
134
|
-
# instance targeted at the specified application. The arguments
|
|
135
|
-
# are the same as for the by_name, by_creator, etc. methods in
|
|
136
|
-
# appscript.
|
|
137
|
-
|
|
138
|
-
by_name(name) -- name or full path of application, e.g. "Finder"
|
|
139
|
-
|
|
140
|
-
by_creator(creator) -- four-character creator code, e.g. "ttxt"
|
|
141
|
-
|
|
142
|
-
by_id(id) -- bundle id, e.g. "com.apple.ical"
|
|
143
|
-
|
|
144
|
-
by_pid(pid) -- Unix process ID, e.g. 4005
|
|
145
|
-
|
|
146
|
-
by_url(url) -- eppc URL, e.g. "eppc://jukebox-mac.local/iTunes"</code></pre>
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
<h2>Examples</h2>
|
|
150
|
-
|
|
151
|
-
<pre><code>require "osax"
|
|
152
|
-
|
|
153
|
-
# Create a new ScriptingAddition object:
|
|
154
|
-
|
|
155
|
-
sa = OSAX.osax
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
# List all available commands:
|
|
159
|
-
|
|
160
|
-
p sa.commands
|
|
161
|
-
# Result: ["ASCII_character", "ASCII_number", "activate", ...]
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
# Call some commands:
|
|
165
|
-
|
|
166
|
-
sa.beep
|
|
167
|
-
|
|
168
|
-
p sa.path_to(:scripts_folder)
|
|
169
|
-
# Result: MacTypes::Alias.at("/Users/foo/Library/Scripts/")
|
|
170
|
-
|
|
171
|
-
p sa.display_dialog("Ruby says hello!",
|
|
172
|
-
:buttons=>["Hi!", "Howdy!", "Duuuude!"],
|
|
173
|
-
:default_button=>3)
|
|
174
|
-
# Result: {:button_returned=>"Howdy!"}</code></pre>
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
<h2>Notes</h2>
|
|
178
|
-
|
|
179
|
-
<h3>GUI interaction</h3>
|
|
180
|
-
|
|
181
|
-
<p>When using scripting addition commands that require GUI access (e.g. <code>display_dialog</code>) targeted at the command-line Ruby interpreter, the osax module will automatically convert the non-GUI interpreter process into a full GUI process to allow these commands to operate correctly. If you want to avoid this, target these commands at a faceless GUI application such as System Events instead:</p>
|
|
182
|
-
|
|
183
|
-
<pre><code>sa = OSAX.osax("StandardAdditions", "System Events")
|
|
184
|
-
sa.activate # give focus to System Events
|
|
185
|
-
p sa.display_dialog("Ruby says hello!",
|
|
186
|
-
:buttons=>["Hi!", "Howdy!", "Duuuude!"],
|
|
187
|
-
:default_button=>3)
|
|
188
|
-
# Result: {:button_returned=>"Duuuude!"}</code></pre>
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
<h3>64-bit limitations</h3>
|
|
192
|
-
|
|
193
|
-
<p>The <code>osax</code> module currently only supports dynamic retrieval of scripting addition terminology when running in 32-bit processes. To use it in 64-bit processes, use the <code>Terminology</code> module's <code>dump</code> method to export a static terminology 'glue' module for the desired scripting addition (running it in a 32-bit process), then import that module and pass it as the second argument to the <code>ScriptingAddition</code> class's initialiser. For example, to export a glue module for Standard Additions:</p>
|
|
194
|
-
|
|
195
|
-
<pre><code>require 'appscript'
|
|
196
|
-
|
|
197
|
-
Terminology.dump('/System/Library/ScriptingAdditions/StandardAdditions.osax',
|
|
198
|
-
'StandardAdditions', 'standard_additions.rb')</code></pre>
|
|
199
|
-
|
|
200
|
-
<p>To create a new <code>ScriptingAddition</code> instance using the terminology provided by this glue module:</p>
|
|
201
|
-
|
|
202
|
-
<pre><code>require 'osax'
|
|
203
|
-
require 'standard_additions'
|
|
204
|
-
|
|
205
|
-
sa = OSAX::ScriptingAddition.new('StandardAdditions', StandardAdditions)</code></pre>
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
<h3>Known problems</h3>
|
|
209
|
-
|
|
210
|
-
<p>When using the <code>osax</code> module within RubyCocoa-based applications, avoid creating <code>ScriptingAddition</code> instances before the main event loop is started as this can result in the application behaving strangely (minimised windows don't expand correctly) due to a bug in OS X's <code>OSAGetAppTerminology</code> function.</p>
|
|
32
|
+
<h2>Contents</h2>
|
|
211
33
|
|
|
34
|
+
<ol>
|
|
35
|
+
<li><a href="01_introduction.html">Introduction</a></li>
|
|
36
|
+
<li><a href="02_interface.html">Interface</a></li>
|
|
37
|
+
<li><a href="03_examples.html">Examples</a></li>
|
|
38
|
+
<li><a href="04_notes.html">Notes</a></li>
|
|
212
39
|
|
|
40
|
+
</ol>
|
|
213
41
|
|
|
214
42
|
</div>
|
|
215
43
|
|
|
216
44
|
<!-- bottom navigation -->
|
|
217
|
-
|
|
218
|
-
|
|
45
|
+
|
|
46
|
+
<div class="footer">
|
|
47
|
+
<a href="../index.html">Previous</a> •
|
|
48
|
+
<a href="../index.html">Up</a> •
|
|
49
|
+
<a href="01_introduction.html">Next</a>
|
|
50
|
+
|
|
51
|
+
<span>© 2006-2008 HAS</span>
|
|
219
52
|
</div>
|
|
220
53
|
|
|
221
|
-
<!--footer-->
|
|
222
|
-
<p class="footer">© 2006-2008 HAS</p>
|
|
223
54
|
</body>
|
|
224
55
|
</html>
|