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.
- 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>
|