rb-scrpt 1.0.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (96) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGES +497 -0
  3. data/README.md +8 -0
  4. data/Rakefile +32 -0
  5. data/doc/aem-manual/01_introduction.html +60 -0
  6. data/doc/aem-manual/02_apioverview.html +107 -0
  7. data/doc/aem-manual/03_packingandunpackingdata.html +135 -0
  8. data/doc/aem-manual/04_references.html +409 -0
  9. data/doc/aem-manual/05_targetingapplications.html +164 -0
  10. data/doc/aem-manual/06_buildingandsendingevents.html +229 -0
  11. data/doc/aem-manual/07_findapp.html +63 -0
  12. data/doc/aem-manual/08_examples.html +94 -0
  13. data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
  14. data/doc/aem-manual/index.html +56 -0
  15. data/doc/appscript-manual/01_introduction.html +94 -0
  16. data/doc/appscript-manual/02_aboutappscripting.html +247 -0
  17. data/doc/appscript-manual/03_quicktutorial.html +167 -0
  18. data/doc/appscript-manual/04_gettinghelp.html +188 -0
  19. data/doc/appscript-manual/05_keywordconversion.html +106 -0
  20. data/doc/appscript-manual/06_classesandenums.html +192 -0
  21. data/doc/appscript-manual/07_applicationobjects.html +211 -0
  22. data/doc/appscript-manual/08_realvsgenericreferences.html +96 -0
  23. data/doc/appscript-manual/09_referenceforms.html +241 -0
  24. data/doc/appscript-manual/10_referenceexamples.html +154 -0
  25. data/doc/appscript-manual/11_applicationcommands.html +245 -0
  26. data/doc/appscript-manual/12_commandexamples.html +138 -0
  27. data/doc/appscript-manual/13_performanceissues.html +142 -0
  28. data/doc/appscript-manual/14_notes.html +80 -0
  29. data/doc/appscript-manual/application_architecture.gif +0 -0
  30. data/doc/appscript-manual/application_architecture2.gif +0 -0
  31. data/doc/appscript-manual/finder_to_textedit_event.gif +0 -0
  32. data/doc/appscript-manual/index.html +62 -0
  33. data/doc/appscript-manual/relationships_example.gif +0 -0
  34. data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
  35. data/doc/full.css +106 -0
  36. data/doc/index.html +45 -0
  37. data/doc/mactypes-manual/01_introduction.html +54 -0
  38. data/doc/mactypes-manual/02_aliasclass.html +124 -0
  39. data/doc/mactypes-manual/03_fileurlclass.html +126 -0
  40. data/doc/mactypes-manual/04_unitsclass.html +100 -0
  41. data/doc/mactypes-manual/index.html +53 -0
  42. data/doc/osax-manual/01_introduction.html +67 -0
  43. data/doc/osax-manual/02_interface.html +147 -0
  44. data/doc/osax-manual/03_examples.html +73 -0
  45. data/doc/osax-manual/04_notes.html +61 -0
  46. data/doc/osax-manual/index.html +53 -0
  47. data/doc/rb-appscript-logo.png +0 -0
  48. data/extconf.rb +63 -0
  49. data/rb-scrpt.gemspec +16 -0
  50. data/sample/AB_export_vcard.rb +31 -0
  51. data/sample/AB_list_people_with_emails.rb +13 -0
  52. data/sample/Add_iCal_event.rb +21 -0
  53. data/sample/Create_daily_iCal_todos.rb +75 -0
  54. data/sample/Export_Address_Book_phone_numbers.rb +59 -0
  55. data/sample/Hello_world.rb +21 -0
  56. data/sample/List_iTunes_playlist_names.rb +11 -0
  57. data/sample/Make_Mail_message.rb +33 -0
  58. data/sample/Open_file_in_TextEdit.rb +13 -0
  59. data/sample/Organize_Mail_messages.rb +61 -0
  60. data/sample/Print_folder_tree.rb +16 -0
  61. data/sample/Select_all_HTML_files.rb +14 -0
  62. data/sample/Set_iChat_status.rb +24 -0
  63. data/sample/Simple_Finder_GUI_Scripting.rb +18 -0
  64. data/sample/Stagger_Finder_windows.rb +25 -0
  65. data/sample/TextEdit_demo.rb +130 -0
  66. data/sample/iTunes_top40_to_html.rb +69 -0
  67. data/src/SendThreadSafe.c +380 -0
  68. data/src/SendThreadSafe.h +139 -0
  69. data/src/lib/_aem/aemreference.rb +1021 -0
  70. data/src/lib/_aem/codecs.rb +661 -0
  71. data/src/lib/_aem/connect.rb +205 -0
  72. data/src/lib/_aem/encodingsupport.rb +74 -0
  73. data/src/lib/_aem/findapp.rb +85 -0
  74. data/src/lib/_aem/mactypes.rb +250 -0
  75. data/src/lib/_aem/send.rb +279 -0
  76. data/src/lib/_aem/typewrappers.rb +59 -0
  77. data/src/lib/_appscript/defaultterminology.rb +277 -0
  78. data/src/lib/_appscript/referencerenderer.rb +242 -0
  79. data/src/lib/_appscript/reservedkeywords.rb +116 -0
  80. data/src/lib/_appscript/safeobject.rb +250 -0
  81. data/src/lib/_appscript/terminology.rb +470 -0
  82. data/src/lib/aem.rb +253 -0
  83. data/src/lib/kae.rb +1489 -0
  84. data/src/lib/osax.rb +659 -0
  85. data/src/lib/rb-scrpt.rb +1073 -0
  86. data/src/lib/version.rb +3 -0
  87. data/src/rbae.c +979 -0
  88. data/test/README +3 -0
  89. data/test/test_aemreference.rb +115 -0
  90. data/test/test_appscriptcommands.rb +149 -0
  91. data/test/test_appscriptreference.rb +103 -0
  92. data/test/test_codecs.rb +181 -0
  93. data/test/test_findapp.rb +23 -0
  94. data/test/test_mactypes.rb +77 -0
  95. data/test/test_osax.rb +52 -0
  96. metadata +146 -0
data/doc/mactypes-manual/03_fileurlclass.html ADDED
@@ -0,0 +1,126 @@
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-mactypes manual | 3. FileURL class</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_aliasclass.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="04_unitsclass.html">Next</a>
20
+
21
+ <span>
22
+ <a href="../appscript-manual/index.html">appscript</a> /
23
+ <strong><a href="../mactypes-manual/index.html">mactypes</a></strong> /
24
+ <a href="../osax-manual/index.html">osax</a> /
25
+ <a href="../aem-manual/index.html">aem</a>
26
+ </span>
27
+ </div>
28
+
29
+ <!-- content -->
30
+ <div id="content">
31
+
32
+
33
+ <h2>3. The <code>MacTypes::FileURL</code> class</h2>
34
+
35
+ <p>The <code>FileURL</code> class represents a fixed filesystem location. This may be deterministic (i.e. existing locations only) or non-deterministic depending on how the object is created.</p>
36
+
37
+ <h3>Methods</h3>
38
+
39
+ <pre><code>FileURL -- identifies a fixed filesystem location
40
+ Constructors:
41
+
42
+ FileURL.path(path) -- make FileURL object from POSIX path string
43
+
44
+ FileURL.hfs_path(path) -- make FileURL object from HFS path string
45
+
46
+ FileURL.url(url) -- make FileURL object from a local file:// URL string
47
+
48
+ FileURL.desc(desc) -- make FileURL object from an AE::AEDesc
49
+ of TypeFSS, TypeFSRef or TypeFileURL
50
+
51
+ Methods:
52
+
53
+ ==
54
+
55
+ hash
56
+
57
+ inspect
58
+
59
+ path -- returns POSIX path string
60
+
61
+ hfs_path -- returns HFS path string
62
+
63
+ url -- returns file:// URL string
64
+
65
+ desc -- returns AE::AEDesc of TypeFSRef, TypeFSS or TypeFileURL
66
+
67
+ to_s -- synonym for #path
68
+
69
+ to_alias -- returns a MacTypes::Alias object
70
+
71
+ to_file_url -- returns a new MacTypes::FileURL object</code></pre>
72
+
73
+
74
+ <h3>Examples</h3>
75
+
76
+ <pre><code>require "appscript"
77
+
78
+ f = MacTypes::FileURL.path('/Users/foo/new file')
79
+
80
+ puts f.to_s
81
+ # /Users/foo/new file
82
+
83
+ puts f.url
84
+ # file://localhost/Users/foo/some%20file
85
+
86
+ puts f.inspect
87
+ # MacTypes::FileURL.path("/Users/foo/new file")
88
+
89
+ Appscript.app('TextEdit').documents[1].save(:in => f)
90
+ # saves front TextEdit document at the given location</code></pre>
91
+
92
+
93
+ <h3>Notes</h3>
94
+
95
+ <p>Unlike the <code>Alias</code> class which wraps <code>TypeAlias</code> values only, the <code>FileURL</code> class provides a uniform wrapper for several file-related types that may be returned by applications: <code>TypeFSS</code>, <code>TypeFSRef</code> and <code>TypeFileURL</code>. When passing <code>FileURL</code> values to applications, you should not normally need to worry about which value type a <code>FileURL</code> object contains as well-designed applications will ask the Apple Event Manager to coerce the given value to the desired type as necessary.</p>
96
+
97
+ <p>When dealing with less well-behaved applications, however, you may need to pass an AEDesc of a specific type. In this case you should use the <code>desc</code> method to obtain an <code>AE::AEDesc</code> object, then call its <code>coerce</code> method to obtain an AEDesc of the desired type. For example, if an older Carbon application refuses to accept a FileURL identifying a non-existing file location, you may need to provide a FSSpec instead:</p>
98
+
99
+ <pre><code>require "appscript"
100
+
101
+ file_url = MacTypes::FileURL.path('/Users/foo/new file')
102
+
103
+ fs_spec = file_url.desc.coerce(KAE::TypeFSS)
104
+
105
+ Appscript.app('older app').documents[1].save(:in => fs_spec)</code></pre>
106
+
107
+ <p>When used in an application command, a <code>FileURL</code> object returned by appscript will always pack into the same <code>TypeFSRef</code>, <code>TypeFileURL</code> or <code>TypeFSS</code> AEDesc it was created from. A <code>FileURL</code> object returned by <code>FileURL.path</code>, <code>Alias#to_file_url</code> or <code>FileURL#to_file_url</code> will always pack into an AEDesc of <code>TypeFileURL</code>.</p>
108
+
109
+ <p>When comparing <code>FileURL</code> objects for equality, be aware that <code>FileURL#==</code> always performs case-sensitive comparisons, regardless of how the underlying filesystem handles case-[in]sensitivity.</p>
110
+
111
+ <p>Note that AEDescs of <code>TypeFSRef</code> can represent existing filesystem locations only. AEDescs of <code>TypeFileURL</code> can represent both existing and non-existing locations. AEDescs of <code>TypeFSS</code> (FSSpecs) are deprecated on Mac OS X due to lack of proper Unicode and long filename support, and are retained for backwards compatibility with older applications only.</p>
112
+
113
+ <p>Be aware that <code>FileURL#==</code> does not normalize file URLs; thus minor differences in capitalization, etc. can result in <code>FileURL#==</code> returning <code>false</code> even if both objects happen to identify the same filesystem location.</p>
114
+
115
+ </div>
116
+
117
+ <!-- bottom navigation -->
118
+
119
+ <div class="footer">
120
+ <a href="02_aliasclass.html">Previous</a> &bull;
121
+ <a href="index.html">Up</a> &bull;
122
+ <a href="04_unitsclass.html">Next</a>
123
+ </div>
124
+
125
+ </body>
126
+ </html>
data/doc/mactypes-manual/04_unitsclass.html ADDED
@@ -0,0 +1,100 @@
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-mactypes manual | 4. Units class</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_fileurlclass.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a>
19
+
20
+ <span>
21
+ <a href="../appscript-manual/index.html">appscript</a> /
22
+ <strong><a href="../mactypes-manual/index.html">mactypes</a></strong> /
23
+ <a href="../osax-manual/index.html">osax</a> /
24
+ <a href="../aem-manual/index.html">aem</a>
25
+ </span>
26
+ </div>
27
+
28
+ <!-- content -->
29
+ <div id="content">
30
+
31
+ <h2>4. The <code>MacTypes::Units</code> class</h2>
32
+
33
+ <p>The <code>Units</code> class represents a measurement of some sort, e.g. 3 inches, 98.5 degrees Fahrenheit.</p>
34
+
35
+ <pre><code>class Units
36
+
37
+ Constructor:
38
+
39
+ Units.new(value, type)
40
+ value : Fixnum | Bignum | Float -- the amount, e.g. 3.5
41
+ type : Symbol -- the unit of measurement, e.g. :centimeters
42
+
43
+ Methods:
44
+
45
+ ==
46
+
47
+ hash
48
+
49
+ inspect
50
+
51
+ value -- returns the amount
52
+
53
+ type -- returns the unit of measurement
54
+
55
+ to_i -- returns the amount as an integer
56
+
57
+ to_f -- returns the amount as a float
58
+
59
+ to_s -- returns the measurement as a string, e.g. "3.5 centimeters"</code></pre>
60
+
61
+ <p>The following unit types are defined as standard:</p>
62
+
63
+ <pre><code>:centimeters :cubic_inches
64
+ :meters :cubic_feet
65
+ :kilometers :cubic_yards
66
+ :inches
67
+ :feet :liters
68
+ :yards :quarts
69
+ :miles :gallons
70
+
71
+ :square_meters :grams
72
+ :square_kilometers :kilograms
73
+ :square_feet :ounces
74
+ :square_yards :pounds
75
+ :square_miles
76
+ :degrees_Celsius
77
+ :cubic_centimeters :degrees_Fahrenheit
78
+ :cubic_meters :degrees_Kelvin</code></pre>
79
+
80
+ <p>Additional application-specific unit types can be added if needed.</p>
81
+
82
+
83
+ <h3>Examples</h3>
84
+
85
+ <pre><code>MacTypes::Units.new(14, :inches)
86
+
87
+ MacTypes::Units.new(3.5, :square_meters)</code></pre>
88
+
89
+
90
+ </div>
91
+
92
+ <!-- bottom navigation -->
93
+
94
+ <div class="footer">
95
+ <a href="03_fileurlclass.html">Previous</a> &bull;
96
+ <a href="index.html">Up</a>
97
+ </div>
98
+
99
+ </body>
100
+ </html>
data/doc/mactypes-manual/index.html ADDED
@@ -0,0 +1,53 @@
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-mactypes manual</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="../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
+ <strong><a href="../mactypes-manual/index.html">mactypes</a></strong> /
24
+ <a href="../osax-manual/index.html">osax</a> /
25
+ <a href="../aem-manual/index.html">aem</a>
26
+ </span>
27
+ </div>
28
+
29
+ <!-- content -->
30
+ <div id="content">
31
+
32
+ <h2>Contents</h2>
33
+
34
+ <ol>
35
+ <li><a href="01_introduction.html">Introduction</a></li>
36
+ <li><a href="02_aliasclass.html">Alias class</a></li>
37
+ <li><a href="03_fileurlclass.html">FileURL class</a></li>
38
+ <li><a href="04_unitsclass.html">Units class</a></li>
39
+
40
+ </ol>
41
+
42
+ </div>
43
+
44
+ <!-- bottom navigation -->
45
+
46
+ <div class="footer">
47
+ <a href="../index.html">Previous</a> &bull;
48
+ <a href="../index.html">Up</a> &bull;
49
+ <a href="01_introduction.html">Next</a>
50
+ </div>
51
+
52
+ </body>
53
+ </html>
data/doc/osax-manual/01_introduction.html ADDED
@@ -0,0 +1,67 @@
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 | 1. Introduction</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="index.html">Previous</a> &bull;
18
+ <a href="index.html">Up</a> &bull;
19
+ <a href="02_interface.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>1. Introduction</h2>
33
+
34
+ <h3>About osax</h3>
35
+
36
+ <p>The <code>OSAX</code> module provides an easy way to call scripting additions (a.k.a. OSAXen) from Ruby. It exports a single public class, <code>ScriptingAddition</code>, and two functions, <code>osax</code> and <code>scripting_additions</code>.</p>
37
+
38
+ <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>
39
+
40
+ <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>
41
+
42
+ <p>For example:</p>
43
+
44
+ <pre><code>require "osax"
45
+
46
+ sa = OSAX::ScriptingAddition.new("StandardAdditions")
47
+
48
+ sa.say("Hello world", :using=&gt;"Victoria")</code></pre>
49
+
50
+ <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>
51
+
52
+ <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>
53
+
54
+
55
+
56
+ </div>
57
+
58
+ <!-- bottom navigation -->
59
+
60
+ <div class="footer">
61
+ <a href="index.html">Previous</a> &bull;
62
+ <a href="index.html">Up</a> &bull;
63
+ <a href="02_interface.html">Next</a>
64
+ </div>
65
+
66
+ </body>
67
+ </html>
data/doc/osax-manual/02_interface.html ADDED
@@ -0,0 +1,147 @@
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> &bull;
18
+ <a href="index.html">Up</a> &bull;
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: #&lt;OSAX::ScriptingAddition
64
+ # name="StandardAdditions"
65
+ # target=AEM::Application.current&gt;</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> &bull;
142
+ <a href="index.html">Up</a> &bull;
143
+ <a href="03_examples.html">Next</a>
144
+ </div>
145
+
146
+ </body>
147
+ </html>
data/doc/osax-manual/03_examples.html ADDED
@@ -0,0 +1,73 @@
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> &bull;
18
+ <a href="index.html">Up</a> &bull;
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=&gt;["Hi!", "Howdy!", "Duuuude!"],
57
+ :default_button=&gt;3)
58
+ # Result: {:button_returned=&gt;"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> &bull;
68
+ <a href="index.html">Up</a> &bull;
69
+ <a href="04_notes.html">Next</a>
70
+ </div>
71
+
72
+ </body>
73
+ </html>
data/doc/osax-manual/04_notes.html ADDED
@@ -0,0 +1,61 @@
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> &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
+ <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
+
34
+ <h3>Event loops</h3>
35
+
36
+ <p>Ruby-based applications that use a Carbon/Cocoa event loop can import the <code>OSAX</code> module as normal, but should not use it before the event loop has started as sending Apple events outwith the main event loop can disrupt the process's normal event handling.</p>
37
+
38
+
39
+ <h3>GUI interaction</h3>
40
+
41
+ <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>
42
+
43
+ <pre><code>sa = OSAX.osax("StandardAdditions", "System Events")
44
+ sa.activate # give focus to System Events
45
+ p sa.display_dialog("Ruby says hello!",
46
+ :buttons=&gt;["Hi!", "Howdy!", "Duuuude!"],
47
+ :default_button=&gt;3)
48
+ # Result: {:button_returned=&gt;"Duuuude!"}</code></pre>
49
+
50
+
51
+ </div>
52
+
53
+ <!-- bottom navigation -->
54
+
55
+ <div class="footer">
56
+ <a href="03_examples.html">Previous</a> &bull;
57
+ <a href="index.html">Up</a>
58
+ </div>
59
+
60
+ </body>
61
+ </html>