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

Last change on this file since 78 was 19, checked in by Nicholas Riley, 22 years ago

F-Script Anywhere 1.1.6d1

File size: 10.3 KB
RevLine 
[16]1F-Script Anywhere 1.1.5 [1 October 2002]
[14]2=======================
[7]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
[14]13Ever wanted to inspect a Cocoa applicationÕs objects from the inside?
[7]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
[16]26F-Script Anywhere 1.1.5 was tested with FScript.framework 1.2.2
27(20020604), Mac OS X 10.1.5 (5S66) and 10.2.1 (6D52). It may or may
28not work with earlier or later versions, I don't know. If you are
29using an earlier F-Script version, please upgrade.
[7]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
[16]672. Install libPatch 1.2.1.
[7]68
[16]69 <http://web.sabi.net/nriley/software/libPatch-1.2.1.tgz>
[7]70
71 I'd suggest you do it this way:
72
73 % cd /
[16]74 % sudo gnutar --preserve-permissions -zxf libPatch-1.2.1.tgz
[7]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.
[16]84
85 I did not write libPatch, but am distributing it for your convenience
86 because it may be unavailable from its original source. libPatch is
87 unsupported; please do not contact libPatchÕs author for support.
[7]88
893. Check out the source of 'otool' from the Darwin CVS repository.
90 This is required because there's a bug in the function that returns
91 the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
92 It identifies all Cocoa applications as Carbon ones. So as a
93 workaround, F-Script Anywhere examines the application itself to
94 see what libraries it links with. (This may fail if you're doing
95 something weird like linking to development versions of Foundation
96 and AppKit, but since I don't work for Apple, I couldn't test that
97 eventuality.)
98
99 Check out Commands/Apple/cctools/{include,libstuff} from Darwin
100 CVS into the "Darwin source" directory. If you don't have a CVS
101 account, go to <http://www.opensource.apple.com/> and get one.
102
103 cd to the libstuff directory and type 'make' (it doesn't use
104 jam/pbxbuild). I _think_ this is all you need.
105
1064. Open 'F-Script Anywhere.pbproj' in Project Builder and build the
107 Application target. It depends on the Library target, so you don't
[16]108 need to build it separately. You shouldnÕt see any errors or
[7]109 warnings, and the F-Script Anywhere application (as well as the
110 library, which you can ignore because it is also copied into the
111 application bundle) will appear in the build product directory.
112
113If you have any problems building F-Script Anywhere, please let me
114know.
115
116
117FREQUENTLY ASKED QUESTIONS
118--------------------------
119
120Q. What is F-Script?
121
122A. F-Script is a dialect of Smalltalk which includes a bridge to
123 the Objective-C runtime on Mac OS X. It's open-source, and
124 very nice. Its author, Philippe Mougin, has written several
125 articles on it, and documentation is available from the
126 F-Script Web site:
127
128 <http://www.fscript.org/>
129
130
131Q. How do you access user interface elements?
132
[14]133A. One way is to access a window and its views programmatically:
[7]134
135 > app := NSApplication sharedApplication
136
137 > windows := app windows
138
139 > windows
140 NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
141 0x1f0cea0>}
142
143 > windows collect: [:each | each title]
144
145 error: an instance of NSWindow does not respond to "collect:"
146
147 (...a gentle reminder that this is not Smalltalk...)
148
149 > windows title
150 {'F-Script', '', ''}
151
152 (...but F-Script has some tricks of its own...)
153
154 > fsw := windows at: 0
155
156 > fswView := fsw contentView
157
[14]158 To open an F-Script object browser on fswView, type:
159
160 > sys browse: fswView
161
162 Or, click ÒNew Browser: Object...Ó, then click on fswView.
163 Click 'subviews' in the message list. You can use 'subviews'
[7]164 repeatedly on container views if needed.
165
166
[14]167Q. ThatÕs too hard, especially all that scrolling.
[7]168
[16]169A. If you need to access a view (such as a button or text field), menu or
[14]170 window, youÕre in luck. Click in an F-Script workspace window, then
171 choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
172 Follow the instructions in the window to select a user interface
173 element, view it in an object browser or assign it to a variable.
[7]174
175
[14]176Q. F-Script Anywhere fails miserably on Jaguar.
177
[16]178A. It shouldnÕt. Apple re-added support for libPatch to Jaguar late
179 in the development process, with the result that F-Script Anywhere
180 works. libPatch nevertheless needs to be replaced with a more
181 robust mechanism, and I am currently working on using the Application
182 Enhancer SDK <http://www.unsanity.com/haxies/ape/sdk/> for a future
183 version of F-Script Anywhere.
[14]184
185
[16]186Q. F-Script Anywhere fails to recognize Spring as a Cocoa application.
[7]187
[16]188A. Yes, I'm aware of the irony: I contributed code to Spring. Spring
189 uses a unique application launching mechanism which makes it
190 difficult to determine what type of application it is. The only
191 current workaround is to upgrade to Jaguar, where Spring will be
192 correctly identified. This problem will be remedied with the move
193 to Application Enhancer, described above, in a future version of
194 F-Script Anywhere.
195
196
197Q. I donÕt like F-ScriptÕs syntax. I don't like the object browser.
198 I donÕt like you either.
199
[14]200A. I didnÕt write F-Script. Please address your questions to
201 F-ScriptÕs author or the F-Script mailing list.
[7]202
203 <http://www.fscript.org/contacts.htm>
204
205 Oh, and get lost.
206
207
208Q. My question isn't answered here.
209
210A. That's not a question. But if you have a question about F-Script
211 Anywhere, a suggestion or a bug to report, please email it to me at
212 <fsa@sabi.net>. Please try to keep your messages short and to the
213 point, and I'll get back to you as soon as my schedule will allow.
214 Thanks!
215
216
217VERSION HISTORY
218---------------
219
[19]2201.1.6 - - better manage window on startup (only display
221 when launch complete)
[16]2221.1.5 - 1 October 2002 - better identify Cocoa vs. Carbon applications
223 on Jaguar; added hierarchical window list to
224 FSA menu; fixed startup crash on Puma with
225 certain Carbon CFM applications
2261.1.4 - 25 August 2002 - fixed miscellaneous Jaguar issues; worked
227 around broken application quit notifications;
228 added unique interpreter/associate window titles
2291.1.3 - 24 July 2002 - added bullseye-menu targeting cursor; added menu
230 association; work around bug by stopping capture
231 on suspend; added delegate, data source, target,
232 cell selection for views; window controller for
233 windows
[14]2341.1.2 - 18 July 2002 - fixed more startup issues with list management;
[7]235 properly scale icons of apps which have no
[14]236 small icons; added user interface association
[7]2371.1.1 - 3 July 2002 - fixed inefficiencies responsible for long
238 startup time; reorganized Window menu; support
239 paths to applications which contain non-ASCII
240 characters [Martin HŠcker]; added sample code
241 to grab UI elements [Philippe Mougin]; cleaned
242 up code and distribution layout
2431.1 - 25 April 2002 - revised terminology; updated for F-Script 1.2;
244 zoom to fit in application list; added help
245 tags for workspace; focus workspace initially
2461.0.2 - (unreleased) - minor cleanups, added error messages, updated
247 scroll view component for faster UI response,
248 removed help menu item because it's useless
2491.0.1 - 1 March 2002 - corrected message for error 5; libPatch 1.2;
250 fixed endless confirmation on window close
2511.0.1d1 1 February 2002 - added error messages
2521.0 - 3 February 2002 - added dock menu, URL launching, check for
253 F-Script framework, floating window,
254 application name in interpreter window title,
255 fixed bugs, cleaned up error handling,
256 licensed under the GPL (because of ASM code),
257 packaged, added Read Me file and license
2581.0d1 - 1 February 2002 - proof of feasibility, private test version
259
260
261CREDITS
262-------
263
264Thanks to the following people for their software and generous
265donations of source code:
266
267Philippe Mougin, for F-Script
268Mike Ferris, for TextExtras
269Apple, for Darwin
270Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.