rb-appscript 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (83) hide show
  1. data/CHANGES +243 -0
  2. data/LICENSE +1 -0
  3. data/README +42 -0
  4. data/TODO +31 -0
  5. data/doc/aem-manual/01_introduction.html +48 -0
  6. data/doc/aem-manual/02_apioverview.html +89 -0
  7. data/doc/aem-manual/03_packingandunpackingdata.html +98 -0
  8. data/doc/aem-manual/04_references.html +401 -0
  9. data/doc/aem-manual/05_targettingapplications.html +133 -0
  10. data/doc/aem-manual/06_buildingandsendingevents.html +175 -0
  11. data/doc/aem-manual/07_findapp.html +54 -0
  12. data/doc/aem-manual/08_examples.html +85 -0
  13. data/doc/aem-manual/09_notes.html +41 -0
  14. data/doc/aem-manual/aemreferenceinheritance.gif +0 -0
  15. data/doc/aem-manual/full.css +21 -0
  16. data/doc/aem-manual/index.html +43 -0
  17. data/doc/appscript-manual/01_introduction.html +82 -0
  18. data/doc/appscript-manual/02_aboutappscripting.html +244 -0
  19. data/doc/appscript-manual/03_quicktutorial.html +154 -0
  20. data/doc/appscript-manual/04_gettinghelp.html +101 -0
  21. data/doc/appscript-manual/05_keywordconversion.html +91 -0
  22. data/doc/appscript-manual/06_classesandenums.html +174 -0
  23. data/doc/appscript-manual/07_applicationobjects.html +181 -0
  24. data/doc/appscript-manual/08_realvsgenericreferences.html +86 -0
  25. data/doc/appscript-manual/09_referenceforms.html +232 -0
  26. data/doc/appscript-manual/10_referenceexamples.html +142 -0
  27. data/doc/appscript-manual/11_applicationcommands.html +204 -0
  28. data/doc/appscript-manual/12_commandexamples.html +129 -0
  29. data/doc/appscript-manual/13_performanceissues.html +115 -0
  30. data/doc/appscript-manual/14_problemapps.html +193 -0
  31. data/doc/appscript-manual/15_notes.html +84 -0
  32. data/doc/appscript-manual/application_architecture.gif +0 -0
  33. data/doc/appscript-manual/application_architecture2.gif +0 -0
  34. data/doc/appscript-manual/finder_to_textedit_event.gif +0 -0
  35. data/doc/appscript-manual/full.css +21 -0
  36. data/doc/appscript-manual/index.html +49 -0
  37. data/doc/appscript-manual/relationships_example.gif +0 -0
  38. data/doc/appscript-manual/ruby_to_itunes_event.gif +0 -0
  39. data/doc/index.html +30 -0
  40. data/doc/mactypes-manual/index.html +216 -0
  41. data/doc/osax-manual/index.html +169 -0
  42. data/extconf.rb +54 -0
  43. data/misc/adobeunittypes.rb +14 -0
  44. data/misc/dump.rb +72 -0
  45. data/rb-appscript.gemspec +20 -0
  46. data/sample/AB_list_people_with_emails.rb +8 -0
  47. data/sample/Create_daily_iCal_todos.rb +72 -0
  48. data/sample/Hello_world.rb +9 -0
  49. data/sample/List_iTunes_playlist_names.rb +7 -0
  50. data/sample/Make_Mail_message.rb +29 -0
  51. data/sample/Open_file_in_TextEdit.rb +9 -0
  52. data/sample/Organize_Mail_messages.rb +57 -0
  53. data/sample/Print_folder_tree.rb +12 -0
  54. data/sample/Select_all_HTML_files.rb +8 -0
  55. data/sample/Set_iChat_status.rb +20 -0
  56. data/sample/Simple_Finder_GUI_Scripting.rb +14 -0
  57. data/sample/Stagger_Finder_windows.rb +21 -0
  58. data/sample/TextEdit_demo.rb +126 -0
  59. data/sample/iTunes_top40_to_html.rb +64 -0
  60. data/src/lib/_aem/aemreference.rb +1006 -0
  61. data/src/lib/_aem/codecs.rb +617 -0
  62. data/src/lib/_aem/connect.rb +100 -0
  63. data/src/lib/_aem/findapp.rb +83 -0
  64. data/src/lib/_aem/mactypes.rb +228 -0
  65. data/src/lib/_aem/send.rb +257 -0
  66. data/src/lib/_aem/typewrappers.rb +57 -0
  67. data/src/lib/_appscript/defaultterminology.rb +245 -0
  68. data/src/lib/_appscript/referencerenderer.rb +132 -0
  69. data/src/lib/_appscript/reservedkeywords.rb +107 -0
  70. data/src/lib/_appscript/terminology.rb +314 -0
  71. data/src/lib/aem.rb +216 -0
  72. data/src/lib/appscript.rb +830 -0
  73. data/src/lib/kae.rb +1484 -0
  74. data/src/lib/osax.rb +171 -0
  75. data/src/rbae.c +766 -0
  76. data/test/README +1 -0
  77. data/test/test_aemreference.rb +112 -0
  78. data/test/test_appscriptreference.rb +102 -0
  79. data/test/test_codecs.rb +159 -0
  80. data/test/test_findapp.rb +24 -0
  81. data/test/test_mactypes.rb +67 -0
  82. data/test/testall.sh +9 -0
  83. metadata +143 -0
data/doc/appscript-manual/06_classesandenums.html ADDED
@@ -0,0 +1,174 @@
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 | 6. Classes and Enumerated Types</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>6. Classes and Enumerated Types</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="05_keywordconversion.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_applicationobjects.html">Next</a>
18
+
19
+ </div>
20
+
21
+ <!-- content -->
22
+ <div id="content">
23
+ <h2>Appscript keywords</h2>
24
+
25
+ <p>For your convenience, appscript represents Apple event type names and application-specific class and enumerator names as Ruby symbols. Examples:</p>
26
+
27
+ <pre><code># AEM-defined data types:
28
+ :boolean
29
+ :unicode_text
30
+ :list
31
+
32
+ # Application-defined class names:
33
+ :document
34
+ :window
35
+ :disk
36
+
37
+ # Application-defined enumerators:
38
+ :yes
39
+ :no
40
+ :ask</code></pre>
41
+
42
+ <p>Occasionally an application dictionary defines a type or enumerator without providing it with a corresponding name name. In these cases, the value will be represented as a raw <code>AEM::AEType</code> or <code>AEM::AEEnum</code> object instead of a symbol, e.g.: <!--The aem package's documentation provides more information on these lower-level objects, should you need to use them.--></p>
43
+
44
+ <pre><code>AEM::AEType.new('abcd')
45
+
46
+ AEM::AEEnum.new('xyz ')</code></pre>
47
+
48
+ <h2>Common AE types</h2>
49
+
50
+ <table width=100% summary="AE-Ruby type mappings">
51
+ <thead>
52
+ <tr><th>AE type</th><th>appscript name</th><th>Ruby class</th></tr>
53
+ </thead>
54
+ <tbody>
55
+ <tr><td><code>typeNull</code></td><td><code>:null</code></td><td><code>NilClass</code></td></tr>
56
+ <tr><td><code>typeBoolean</code></td><td><code>:boolean</code></td><td><code>TrueClass/FalseClass</code></td></tr>
57
+ <tr><td><code>typeInteger</code></td><td><code>:integer</code></td><td><code>Fixnum/Bignum</code></td></tr>
58
+ <tr><td><code>typeFloat</code></td><td><code>:float</code></td><td><code>Float</code></td></tr>
59
+ <tr><td><code>typeChar</code> *</td><td><code>:string</code></td><td><code>String</code></td></tr>
60
+ <tr><td><code>typeStyledText</code> *</td><td><code>:styled_text</code></td><td><code>String</code></td></tr>
61
+ <tr><td><code>typeIntlText</code> *</td><td><code>:international_text</code></td><td><code>String</code></td></tr>
62
+ <tr><td><code>typeUnicodeText</code></td><td><code>:unicode_text</code></td><td><code>String</code></td></tr>
63
+ <tr><td><code>typeAEList</code></td><td><code>:list</code></td><td><code>Array</code></td></tr>
64
+ <tr><td><code>typeAERecord</code></td><td><code>:record</code></td><td><code>Hash</code></td></tr>
65
+ <tr><td><code>typeLongDateTime</code></td><td><code>:date</code></td><td><code>Time</code></td></tr>
66
+ <tr><td><code>typeAlias</code></td><td><code>:alias</code></td><td><code>MacTypes::Alias</code></td></tr>
67
+ <tr><td><code>typeFileURL</code></td><td><code>:file_url</code></td><td><code>MacTypes::FileURL</code></td></tr>
68
+ <tr><td><code>typeFSRef</code></td><td><code>:file_ref</code></td><td><code>MacTypes::FileURL</code></td></tr>
69
+ <tr><td><code>typeFSS</code> *</td><td><code>:file_specification</code></td><td><code>MacTypes::FileURL</code></td></tr>
70
+ <tr><td><code>typeObjectSpecifier</code></td><td><code>:reference</code></td><td><code>AS::Reference</code></td></tr>
71
+ <tr><td><code>typeInsertionLoc</code></td><td><code>:location_reference</code></td><td><code>AS::Reference</code></td></tr>
72
+ <tr><td><code>typeType</code></td><td><code>:type_class</code></td><td><code>Symbol</code></td></tr>
73
+ <tr><td><code>typeEnumerated</code></td><td><code>:enumerator</code></td><td><code>Symbol</code></td></tr>
74
+ <tr><td><small>unit types; e.g. </small> <code>typeFeet</code></td><td><small>unit names; e.g.</small> <code>:feet</code></td><td><code>MacTypes::Units</code></td></tr>
75
+ </tbody>
76
+ </table>
77
+
78
+ <p>(Note that types marked with '*' are officially deprecated and/or their use discouraged in Mac OS X. They remain supported to ensure backwards compatibility with older applications that may use them.)</p>
79
+
80
+
81
+ <h2>Type mapping notes</h2>
82
+
83
+ <p>While AEM-Ruby type conversions generally work quite seamlessly, it is sometimes useful to know some of the details involved, particularly when troubleshooting code that deals with older or buggy applications.</p>
84
+
85
+ <h3>Numbers</h3>
86
+
87
+ <p>When packing a <code>Bignum</code>, appscript will pack it either as a 32-bit integer (most preferred), 64-bit integer, or 64-bit float (least preferred), depending on the value's size.</p>
88
+
89
+
90
+ <h3>Strings</h3>
91
+
92
+ <p>Because Ruby lacks a native Unicode class, appscript unpacks all text-related AE types (<code>typeChar</code>, <code>typeUnicodeText</code>, etc.) as UTF8-encoded Ruby strings.</p>
93
+
94
+ <p>Appscript packs UTF8-encoded Ruby strings as the <code>typeUnicodeText</code> AE type. If the string does not contain valid UTF8 data, a TypeError will be raised.</p>
95
+
96
+ <div class="hilitebox">
97
+ <p>You can enable a degree of UTF8 support in Ruby's <code>String</code> class via the Jcode module (included in Ruby's standard library). To use Jcode, add the following lines to the start of your Ruby scripts, irb sessions, etc.:</p>
98
+ <pre><code>require "jcode"
99
+ $KCODE = "UTF8"</code></pre>
100
+
101
+ <p>This will improve the display of non-ASCII characters in irb, amongst other things.</p>
102
+
103
+ </div>
104
+ <p>Note that while <code>typeUnicodeText</code> is formally deprecated in Mac OS X 10.4+ in favour of <code>typeUTF8Text</code> and <code>typeUTF16ExternalRepresentation</code>, it is still in common usage so appscript continues to use it to ensure the broadest compatibility with existing scriptable applications.</p>
105
+
106
+
107
+ <h3>Filesystem references</h3>
108
+
109
+ <p>The <code>typeAlias</code> AE type represents a filesystem object, and will continue to point to that object even if it's renamed or moved to another location on the same disk. The <code>typeFSRef</code> and <code>typeFileURL</code> types represent a filesystem location. Both can represent existing locations; the <code>typeFileURL</code> type can also be used to specify locations that don't already exist.</p>
110
+
111
+ <p>FSSpecs are also supported for sake of backwards-compatibility with older Carbon applications that sometimes still use them. They're deprecated in OS X, however, due to lack of proper Unicode and long filename support, and their use is discouraged.</p>
112
+
113
+ <p>Note that appscript unpacks FSRefs, FileURLs and FSSpecs as <code>MacTypes::FileURL</code> objects; users do not normally need to worry about this. <code>MacTypes::FileURL</code> objects created in Ruby will always pack as type <code>:FileURL</code>, however. See the <a href="../mactypes-manual/index.html">mactypes manual</a> for more information on <code>MacTypes::Alias</code> and <code>MacTypes::FileURL</code>.</p>
114
+
115
+ <p>When asking an application to coerce a return value into a file type you must specify the exact type (<code>:alias</code>, <code>:file_url</code>, <code>:file_ref</code>, or <code>:file_specification</code>) in the <code>get</code> command. e.g. To get a <code>MacTypes::FileURL</code> object for the current user's home folder, you would usually use:</p>
116
+
117
+ <pre><code>AS.app('Finder').home.get(:result_type=&gt;:file_url)</code></pre>
118
+
119
+ <p>Also be aware that some applications may not support coercions to all AE file types; you'll need to experiment to find out which coercions are supported.</p>
120
+
121
+
122
+ <h3>Records</h3>
123
+
124
+ <p>The <code>typeAERecord</code> AE type is a struct-like data structure containing zero or more properties. Appscript represents AE records as Ruby hashes. The keys in this hash are usually symbols representing appscript-style property names, although they may also be <code>AEM::AEType</code> values or strings.</p>
125
+
126
+ <p>If a hash contains a <code>:class_</code> (or <code>AEM::AEType.new('pcls')</code>) key, appscript will pack the remaining items into an AE record, then coerce it to the type specified by this 'class' property. Similarly, when unpacking an record-like AEDesc with a custom type code, appscript will unpack it as a hash with the type represented by a <code>:class_</code> entry.</p>
127
+
128
+
129
+ <h3>Types and enumerators</h3>
130
+
131
+ <p>The <code>typeType</code> and <code>typeEnumerated</code> AE types are unpacked as Ruby symbols when the corresponding terminology is available, otherwise they are unpacked as <code>AEM::AEType</code> and <code>AEM::AEEnum</code> respectively.</td></tr>
132
+
133
+
134
+ <h3>Unit types</h3>
135
+
136
+ <p>The following unit types are defined as standard:</p>
137
+
138
+ <pre><code>:centimeters :cubic_inches
139
+ :meters :cubic_feet
140
+ :kilometers :cubic_yards
141
+ :inches
142
+ :feet :liters
143
+ :yards :quarts
144
+ :miles :gallons
145
+
146
+ :square_meters :grams
147
+ :square_kilometers :kilograms
148
+ :square_feet :ounces
149
+ :square_yards :pounds
150
+ :square_miles
151
+ :degrees_Celsius
152
+ :cubic_centimeters :degrees_Fahrenheit
153
+ :cubic_meters :degrees_Kelvin</code></pre>
154
+
155
+ <p>Values are represented by instances of the <code>MacTypes::Units</code> class, e.g. <code>MacTypes::Units.inches(3.0)</code>. See the <a href="../mactypes-manual/index.html">mactypes manual</a> for more information.</p>
156
+
157
+
158
+ <h3>Miscellaneous types</h3>
159
+
160
+ <p>The Apple Event Manager defines many other AE types whose names and codes are defined by appscript for completeness. A few of these types are of occasional interest to users, the rest can simply be ignored. In most cases, values of these types will be represented by raw <code>AE::AEDesc</code> instances as appscript doesn't automatically convert them to native objects.</p>
161
+
162
+
163
+ </div>
164
+
165
+ <!-- bottom navigation -->
166
+ <div class="navbar">
167
+ <a href="05_keywordconversion.html">Previous</a> | <a href="index.html">Up</a> | <a href="07_applicationobjects.html">Next</a>
168
+
169
+ </div>
170
+
171
+ <!--footer-->
172
+ <p class="footer">&copy; 2006 HAS</p>
173
+ </body>
174
+ </html>
data/doc/appscript-manual/07_applicationobjects.html ADDED
@@ -0,0 +1,181 @@
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 | 7. Application Objects</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>7. Application Objects</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="06_classesandenums.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_realvsgenericreferences.html">Next</a>
18
+
19
+ </div>
20
+
21
+ <!-- content -->
22
+ <div id="content">
23
+ <h2>Creating application objects</h2>
24
+
25
+
26
+ <p>Before you can communicate with a scriptable application you must call one of the following methods to create an application object:</p>
27
+
28
+ <pre><code>AS.app.by_name(name) # name or POSIX path of local application
29
+
30
+ AS.app.by_id(id) # bundle ID for a local application
31
+
32
+ AS.app.by_creator(creator) # 4-character creator type for a local application
33
+
34
+ AS.app.by_pid(pid) # Unix process id for a local process
35
+
36
+ AS.app.by_url(url) # eppc URL for a remote process
37
+
38
+ AS.app.current # the host process</code></pre>
39
+
40
+ <p>For convenience, the most commonly used form, <code>AS.app.by_name(name)</code>, can be shortened to:</p>
41
+
42
+ <pre><code>AS.app(name)</code></pre>
43
+
44
+
45
+ <p>To target an application you must supply one of the following arguments:</p>
46
+
47
+ <dl>
48
+ <dt><code>name</code></dt>
49
+ <dd>The application's filename or POSIX path, e.g. <code>'TextEdit'</code>, <code>'TextEdit.app'</code>, <code>'/Applications/TextEdit.app'</code>. Where a filename is provided, appscript uses LaunchServices to locate the application. Paths beginning with <code>~</code>, e.g. <code>'~/Dev/MyApp.app'</code>, will be expanded automatically. An <code>.app</code> suffix is optional. For example, given the name <code>'TextEdit'</code>, appscript will first search for an application with that exact name. If none is found, it'll automatically add a <code>.app</code> suffix (<code>'TextEdit.app'</code>) and try again.</dd>
50
+
51
+ <dt><code>id</code></dt>
52
+ <dd>The application's bundle id, e.g. <code>'com.apple.textedit'</code>. Cocoa applications often have unique bundle ids.</dd>
53
+
54
+ <dt><code>creator</code></dt>
55
+ <dd>A four-character string containing the application's creator type, e.g. <code>'ttxt'</code>. Older Carbon-based applications and some Cocoa-based applications have unique creator types.</dd>
56
+
57
+ <dt><code>pid</code></dt>
58
+ <dd>A valid Unix process id, e.g. <code>5687</code>.</dd>
59
+
60
+ <dt><code>url</code></dt>
61
+ <dd>A URL of form <code>eppc://[user[:password]@host/Application%20Name[?[uid=#]&amp;[pid=#]</code>, e.g. <code>eppc://johnsmith:foobar@office-mac.local/TextEdit?uid=501</code>. The host name/IP address and the process name (case-sensitive) are required. The username and password are optional: if omitted, the OS will obtain this information from the user's keychain or display a dialog asking the user to input one or both values. The user id and process id are also optional; if the process id is given, the process name will be ignored.</dd>
62
+ </dl>
63
+
64
+
65
+ <p>Examples:</p>
66
+
67
+ <pre><code>require "appscript"
68
+
69
+ ical = AS.app('iCal')
70
+
71
+ textedit = AS.app('TextEdit.app')
72
+
73
+ safari = AS.app('/Applications/Safari')
74
+
75
+ addressbook = AS.app.by_id('com.apple.addressbook')
76
+
77
+ quicktimeplayer = AS.app.by_creator('TVOD')
78
+
79
+ finder = AS.app.by_url('eppc://192.168.10.1/Finder')
80
+
81
+ itunes = AS.app.by_url('eppc://Jan%20Smith@G4.local/iTunes')</code></pre>
82
+
83
+
84
+ <h2>Basic commands</h2>
85
+
86
+ <p>All applications should respond to the following commands:</p>
87
+
88
+ <pre><code>run -- Run an application.
89
+ Most applications will open an empty, untitled window.
90
+
91
+ launch -- Launch an application without sending it a 'run' event. [1]
92
+ Applications that normally open a new, empty document upon launch won't.
93
+
94
+ activate -- Bring the application to the front.
95
+
96
+ reopen -- Reactivate a running application.
97
+ Some applications will open a new untitled window if no window is open.
98
+
99
+ open(directarg) -- Open the specified object(s).
100
+ directarg : anything -- list of objects to open, typically a list of MacFile::Alias
101
+
102
+ print(directarg) -- Print the specified object(s).
103
+ directarg : anything -- list of objects to print, typically a list of MacFile::Alias
104
+
105
+ quit(saving) -- Quit an application.
106
+ saving : :yes | :ask | :no -- specifies whether to save currently open documents
107
+ </code></pre>
108
+
109
+ <p><small>[1] The <code>launch</code> command should be used before constructing references or sending other commands, otherwise appscript will run the application normally.</small></p>
110
+
111
+ <p>Some applications may provide their own definitions of some or all of these commands, so check their terminology before use.</p>
112
+
113
+ <p>Appscript also defines <code>get</code> and <code>set</code> commands for any scriptable application that doesn't supply its own definitions:</p>
114
+
115
+ <pre><code>get(reference) -- Get the data for an object.
116
+ reference -- the object for the command
117
+ Result: anything -- the reply for the command
118
+
119
+ set(reference, :to =&gt; value) -- Set an object's data.
120
+ reference -- the object for the command
121
+ to : anything -- The new value.</code></pre>
122
+
123
+ <p>Note that these commands are only useful in applications that define an Apple Event Object Model as part of their Apple event interface.</p>
124
+
125
+
126
+ <h2>Transaction support</h2>
127
+
128
+ <p>Application objects implement three additional methods, <code>start_transaction</code>, <code>end_transaction</code> and <code>abort_transaction</code> that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro. Once the application object's <code>start_transaction</code> method is called, all subsequent commands to that application will be sent as part of the same transaction until <code>end_transaction</code> or <code>abort_transaction</code> is called.</p>
129
+
130
+ <p class="hilitebox">Remember to call <code>end_transaction</code> or <code>abort_transaction</code> at the end of every transaction. If a transaction is accidentally left open, appscript will try to end it automatically when the application object is garbage-collected, but this is not guaranteed to succeed.</p>
131
+
132
+
133
+ <h2>Local application launching notes</h2>
134
+
135
+ <p>Note: the following information only applies to local applications as appscript cannot directly launch applications on a remote Mac. To control a remote application, the application must be running beforehand or else launched indirectly (e.g. by using the remote Mac's Finder to open it).</p>
136
+
137
+
138
+ <h3>How applications are identified</h3>
139
+
140
+ <p>When you create an Application object by application name, bundle id or creator type, appscript uses LaunchServices to locate an application matching that description. If you have more than one copy of the same application installed, you can identify the one you want by providing its full path, otherwise LaunchServices will identify the newest copy for you.</p>
141
+
142
+ <p>Appscript identifies running applications by their process ids so it's possible to control multiple versions of an application running at the same time if their Application objects are created using process ids or eppc URLs.</p>
143
+
144
+
145
+ <h3>Using <code>launch</code> vs <code>run</code></h3>
146
+
147
+ <p>When appscript launches a non-running application, it normally sends it a <code>run</code> command as part of the launching process. If you wish to avoid this, you should start the application by sending it a <code>launch</code> command before doing anything else. For example:</p>
148
+
149
+ <pre><code>te = AS.app('TextEdit')
150
+ te.launch
151
+ # other TextEdit-related code goes here...</code></pre>
152
+
153
+ <p>This is useful when you want to start an application without it going through its normal startup procedure. For example, the above script will launch TextEdit without causing it to display a new, empty document (its usual behaviour).</p>
154
+
155
+ <p><code>launch</code> is also useful if you need to send a non-running application an <code>open</code> command as its very first instruction. For example, to send an <code>open</code> command to a non-stay-open application that batch processes one or more dropped files then quits again, you must first start it using <code>launch</code>, then send it an <code>open</code> command with the files to process. If you forget to do this, the application will first receive a <code>run</code> command and quit again before the <code>open</code> command can be handled.</p>
156
+
157
+
158
+ <h3>Restarting applications</h3>
159
+
160
+ <p>As soon as you start to construct a reference or command using a newly created Application objects, if the application is not already running then appscript will automatically launch it in order to obtain its terminology.</p>
161
+
162
+ <p>If the target application has stopped running since the Application object was created, trying to send it a command using that Application object will result in an invalid connection error (-609), unless that command is <code>run</code> or <code>launch</code>. This restriction prevents appscript accidentally restarting an application that has unexpectedly quit while a script is controlling it. Scripts can restart an application by sending an explicit <code>run</code> or <code>launch</code> command, or by creating a new Application object for it.</p>
163
+
164
+ <p>Note that you can still use Application objects to control applications that have been quit <em>and</em> restarted since the Application object was created. Appscript will automatically update the Application object's process id information as needed.</p>
165
+
166
+
167
+ <p class="hilitebox">There is a known problem with quitting and immediately relaunching an application via appscript, where the relaunch instruction is sent to the application before it has actually quit. This timing issue appears to be the OS's fault; the current workaround for scripts that need to quit and restart applications is to insert a few seconds' delay between the <code>quit</code> and <code>run</code>/<code>launch</code> using Ruby's <code>sleep</code> function.</p>
168
+
169
+
170
+ </div>
171
+
172
+ <!-- bottom navigation -->
173
+ <div class="navbar">
174
+ <a href="06_classesandenums.html">Previous</a> | <a href="index.html">Up</a> | <a href="08_realvsgenericreferences.html">Next</a>
175
+
176
+ </div>
177
+
178
+ <!--footer-->
179
+ <p class="footer">&copy; 2006 HAS</p>
180
+ </body>
181
+ </html>
data/doc/appscript-manual/08_realvsgenericreferences.html ADDED
@@ -0,0 +1,86 @@
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 | 8. Real vs. Generic References</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>8. Real vs. Generic References</h1>
14
+
15
+ <!-- top navigation -->
16
+ <div class="navbar">
17
+ <a href="07_applicationobjects.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_referenceforms.html">Next</a>
18
+
19
+ </div>
20
+
21
+ <!-- content -->
22
+ <div id="content">
23
+
24
+ <h2>Real vs. generic references</h2>
25
+
26
+ <p>References may be either 'real' or 'generic'. A real reference relates to a specific application, while a generic reference doesn't. Generic references provide a convenient shortcut for writing literal references without having to specify an application each time.</p>
27
+
28
+ <p>A real reference begins with an <code>app</code> call, followed by a <code>by_name</code>, <code>by_id</code>, <code>by_creator</code>, <code>by_pid</code>, <code>by_url</code> call that identifies the application whose object(s) it refers to, e.g.:</p>
29
+
30
+ <pre><code>AS.app.by_name('TextEdit').documents.end
31
+ AS.app.by_url('eppc://my-mac.local/Finder').home.folders.name</code></pre>
32
+
33
+ <p>(Remember than <code>AS.app.by_name('TextEdit')</code> can be shortened to <code>AS.app('TextEdit')</code> for convenience.</p>
34
+
35
+ <p>A generic reference begins with <code>app</code>, <code>con</code> or <code>its</code> and does not identify the application to which it relates, e.g.:</p>
36
+
37
+ <pre><code>AS.app.documents.end
38
+ AS.con.word[3]
39
+ AS.its.name.starts_with('d')</code></pre>
40
+
41
+ <p>Generic references are only evaluated when used used within real references, either as selectors:</p>
42
+
43
+ <pre><code>AS.app('Finder').home.folders[<em>AS.its.name.starts_with('d')</em>].get
44
+
45
+ AS.app('Tex-Edit Plus').windows[1].text[<em>AS.con.words[2]</em>, <em>AS.con.words[-2]</em>].get</code></pre>
46
+
47
+ <p>or as command parameters:</p>
48
+
49
+ <pre><code>AS.app('TextEdit').make(
50
+ :new =&gt; :word,
51
+ :at =&gt; <em>AS.app.documents[1].words.end</em>,
52
+ :with_data =&gt; 'Hello')
53
+
54
+ AS.app('Finder').desktop.duplicate(
55
+ :to =&gt; <em>AS.app.home.folders['Desktop Copy']</em>)</code></pre>
56
+
57
+
58
+ <h2>Comparing and hashing references</h2>
59
+
60
+ <p>Application references can be compared for equality and are hashable (so can be used as dictionary keys). For two real references to be considered equal, both must have the same application path or url and reference structure. Examples:</p>
61
+
62
+ <pre><code>puts AS.app('TextEdit').documents[1] == \
63
+ AS.app.by_id('com.apple.textedit').documents[1].get
64
+ # Result: true; both references evaluate to the same
65
+ # application path and reference
66
+
67
+ puts AS.app('Finder').home == AS.app('Finder').home.get
68
+ # Result: false; AS.app('Finder').home.get returns a
69
+ # different reference to the same location</code></pre>
70
+
71
+ <p>For two generic references to be equal, both must have the same reference structure. Note that comparing generic references to real references will always return a false result.</p>
72
+
73
+
74
+
75
+ </div>
76
+
77
+ <!-- bottom navigation -->
78
+ <div class="navbar">
79
+ <a href="07_applicationobjects.html">Previous</a> | <a href="index.html">Up</a> | <a href="09_referenceforms.html">Next</a>
80
+
81
+ </div>
82
+
83
+ <!--footer-->
84
+ <p class="footer">&copy; 2006 HAS</p>
85
+ </body>
86
+ </html>s