source: trunk/Cocoa/F-Script Anywhere/Source/Read Me@ 14

Last change on this file since 14 was 14, checked in by Nicholas Riley, 20 years ago

F-Script Anywhere 1.1.2

File size: 8.7 KB
Line 
1F-Script Anywhere 1.1.2 [18 July 2002]
2=======================
3
4Add a F-Script interpreter to Cocoa applications dynamically.
5
6Written by Nicholas Riley <mailto:fsa@sabi.net>.
7Obtain updates from <http://web.sabi.net/nriley/software/>.
8
9
10WHAT IS IT?
11-----------
12
13Ever wanted to inspect a Cocoa applicationÕs objects from the inside?
14Frustrated with using GDB to debug Objective-C?
15
16You need F-Script Anywhere! (with apologies to Guido van Rossum)
17
18
19INSTALLATION
20------------
21
22Install F-Script; you can download it at <http://www.fscript.org/>.
23In particular, make sure the framework is installed in a Frameworks
24directory, such as /Library/Frameworks or ~/Library/Frameworks.
25
26F-Script Anywhere 1.1.2 was tested with FScript.framework 1.2.2
27(20020604) and Mac OS X 10.1.5 (5S66). It may or may not work with
28earlier or later versions, I don't know. If you are using an earlier
29F-Script version, please upgrade.
30
31
32USAGE
33-----
34
35Open the F-Script Anywhere application. Pick a Cocoa application from
36the list and click Install or press return. F-Script Anywhere will
37either install itself in that application, give you an error message,
38or crash. (Hopefully not the latter!)
39
40Switch to the application, and you should find a ÒFSAÓ menu there.
41Select ÒNew F-Script WorkspaceÓ to display a F-Script workspace.
42This behaves like any other workspace, except it's executing within
43the context of the application.
44
45You can also install F-Script Anywhere by using its dock menu. If
46the frontmost application is a Cocoa application, just pick ÒInstallÉÓ
47from the menu and F-Script Anywhere will install in that application.
48If F-Script Anywhere canÕt install, the menu item will tell you so,
49or F-Script AnywhereÕs icon will bounce to indicate a pending sheet
50explaining the problem.
51
52When you're finished, quit the application before quitting F-Script
53Anywhere, otherwise the application will crash. This is an inherent
54limitation of the Objective-C runtime, and I can't do anything about
55it. F-Script Anywhere will warn you if you try to quit it when it's
56still installed in active applications.
57
58
59BUILDING
60--------
61
62The source to F-Script Anywhere is included. It has a number of
63dependencies.
64
651. Install FScript.framework (see above).
66
672. Install libPatch by Ed Wynne.
68
69 <http://www.phasic.com/~arwyn/libPatch-1.2.tgz>
70
71 I'd suggest you do it this way:
72
73 % cd /
74 % sudo gnutar --preserve-permissions -zxf libPatch-1.2.tgz
75 Password:
76 (please don't use StuffIt Expander)
77
78 This installs files in /Developer/Examples and
79 /usr/local/{bin,include,lib}. If you're paranoid, you may want to
80 check the contents of the directory before installing.
81
82 Please note that the layout of the libPatch distribution has changed
83 since libPatch 1.0; the above instructions will not work for 1.0.
84
853. Check out the source of 'otool' from the Darwin CVS repository.
86 This is required because there's a bug in the function that returns
87 the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
88 It identifies all Cocoa applications as Carbon ones. So as a
89 workaround, F-Script Anywhere examines the application itself to
90 see what libraries it links with. (This may fail if you're doing
91 something weird like linking to development versions of Foundation
92 and AppKit, but since I don't work for Apple, I couldn't test that
93 eventuality.)
94
95 Check out Commands/Apple/cctools/{include,libstuff} from Darwin
96 CVS into the "Darwin source" directory. If you don't have a CVS
97 account, go to <http://www.opensource.apple.com/> and get one.
98
99 cd to the libstuff directory and type 'make' (it doesn't use
100 jam/pbxbuild). I _think_ this is all you need.
101
1024. Open 'F-Script Anywhere.pbproj' in Project Builder and build the
103 Application target. It depends on the Library target, so you don't
104 need to build it separately. You shouldn't see any errors or
105 warnings, and the F-Script Anywhere application (as well as the
106 library, which you can ignore because it is also copied into the
107 application bundle) will appear in the build product directory.
108
109If you have any problems building F-Script Anywhere, please let me
110know.
111
112
113FREQUENTLY ASKED QUESTIONS
114--------------------------
115
116Q. What is F-Script?
117
118A. F-Script is a dialect of Smalltalk which includes a bridge to
119 the Objective-C runtime on Mac OS X. It's open-source, and
120 very nice. Its author, Philippe Mougin, has written several
121 articles on it, and documentation is available from the
122 F-Script Web site:
123
124 <http://www.fscript.org/>
125
126
127Q. How do you access user interface elements?
128
129A. One way is to access a window and its views programmatically:
130
131 > app := NSApplication sharedApplication
132
133 > windows := app windows
134
135 > windows
136 NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
137 0x1f0cea0>}
138
139 > windows collect: [:each | each title]
140
141 error: an instance of NSWindow does not respond to "collect:"
142
143 (...a gentle reminder that this is not Smalltalk...)
144
145 > windows title
146 {'F-Script', '', ''}
147
148 (...but F-Script has some tricks of its own...)
149
150 > fsw := windows at: 0
151
152 > fswView := fsw contentView
153
154 To open an F-Script object browser on fswView, type:
155
156 > sys browse: fswView
157
158 Or, click ÒNew Browser: Object...Ó, then click on fswView.
159 Click 'subviews' in the message list. You can use 'subviews'
160 repeatedly on container views if needed.
161
162
163Q. ThatÕs too hard, especially all that scrolling.
164
165A. If you need to access a view (such as a button or text field) or
166 window, youÕre in luck. Click in an F-Script workspace window, then
167 choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
168 Follow the instructions in the window to select a user interface
169 element, view it in an object browser or assign it to a variable.
170
171
172Q. F-Script Anywhere fails miserably on Jaguar.
173
174A. So IÕve heard (I donÕt have access to Jaguar developer seeds). This
175 is an issue with libPatch, and affects far more than F-Script Anywhere.
176 Default Folder X and UnsanityÕs haxies are similarly rendered useless.
177 A Jaguar-compatible replacement for libPatch is under development,
178 but it does not yet contain support for applications such as F-Script
179 Anywhere (which is unique in its use of libPatch). IÕll fix this
180 as soon as it does.
181
182
183Q. I don't like F-ScriptÕs syntax. I don't like the object browser.
184 I don't like you either.
185
186A. I didnÕt write F-Script. Please address your questions to
187 F-ScriptÕs author or the F-Script mailing list.
188
189 <http://www.fscript.org/contacts.htm>
190
191 Oh, and get lost.
192
193
194Q. My question isn't answered here.
195
196A. That's not a question. But if you have a question about F-Script
197 Anywhere, a suggestion or a bug to report, please email it to me at
198 <fsa@sabi.net>. Please try to keep your messages short and to the
199 point, and I'll get back to you as soon as my schedule will allow.
200 Thanks!
201
202
203VERSION HISTORY
204---------------
205
2061.1.2 - 18 July 2002 - fixed more startup issues with list management;
207 properly scale icons of apps which have no
208 small icons; added user interface association
2091.1.1 - 3 July 2002 - fixed inefficiencies responsible for long
210 startup time; reorganized Window menu; support
211 paths to applications which contain non-ASCII
212 characters [Martin HŠcker]; added sample code
213 to grab UI elements [Philippe Mougin]; cleaned
214 up code and distribution layout
2151.1 - 25 April 2002 - revised terminology; updated for F-Script 1.2;
216 zoom to fit in application list; added help
217 tags for workspace; focus workspace initially
2181.0.2 - (unreleased) - minor cleanups, added error messages, updated
219 scroll view component for faster UI response,
220 removed help menu item because it's useless
2211.0.1 - 1 March 2002 - corrected message for error 5; libPatch 1.2;
222 fixed endless confirmation on window close
2231.0.1d1 1 February 2002 - added error messages
2241.0 - 3 February 2002 - added dock menu, URL launching, check for
225 F-Script framework, floating window,
226 application name in interpreter window title,
227 fixed bugs, cleaned up error handling,
228 licensed under the GPL (because of ASM code),
229 packaged, added Read Me file and license
2301.0d1 - 1 February 2002 - proof of feasibility, private test version
231
232
233CREDITS
234-------
235
236Thanks to the following people for their software and generous
237donations of source code:
238
239Philippe Mougin, for F-Script
240Mike Ferris, for TextExtras
241Apple, for Darwin
242Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.