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

Last change on this file since 16 was 16, checked in by Nicholas Riley, 17 years ago

F-Script Anywhere 1.1.5

File size: 10.1 KB
Line 
1F-Script Anywhere 1.1.5 [1 October 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.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.
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 1.2.1.
68
69   <http://web.sabi.net/nriley/software/libPatch-1.2.1.tgz>
70
71   I'd suggest you do it this way:
72
73   % cd /
74   % sudo gnutar --preserve-permissions -zxf libPatch-1.2.1.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   
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.
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
108   need to build it separately.  You shouldnÕt see any errors or
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
133A. One way is to access a window and its views programmatically:
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
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'
164   repeatedly on container views if needed.
165
166
167Q. ThatÕs too hard, especially all that scrolling.
168
169A. If you need to access a view (such as a button or text field), menu or
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.
174
175
176Q. F-Script Anywhere fails miserably on Jaguar.
177
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.
184
185
186Q. F-Script Anywhere fails to recognize Spring as a Cocoa application.
187
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
200A. I didnÕt write F-Script.  Please address your questions to
201   F-ScriptÕs author or the F-Script mailing list.
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
2201.1.5 - 1 October 2002  - better identify Cocoa vs. Carbon applications
221                          on Jaguar; added hierarchical window list to
222                          FSA menu; fixed startup crash on Puma with
223                          certain Carbon CFM applications
2241.1.4 - 25 August 2002  - fixed miscellaneous Jaguar issues; worked
225                          around broken application quit notifications;
226                          added unique interpreter/associate window titles
2271.1.3 - 24 July 2002    - added bullseye-menu targeting cursor; added menu
228                          association; work around bug by stopping capture
229                          on suspend; added delegate, data source, target,
230                          cell selection for views; window controller for
231                          windows
2321.1.2 - 18 July 2002    - fixed more startup issues with list management;
233                          properly scale icons of apps which have no
234                          small icons; added user interface association
2351.1.1 - 3 July 2002     - fixed inefficiencies responsible for long
236                          startup time; reorganized Window menu; support
237                          paths to applications which contain non-ASCII
238                          characters [Martin HŠcker]; added sample code
239                          to grab UI elements [Philippe Mougin]; cleaned
240                          up code and distribution layout
2411.1   - 25 April 2002   - revised terminology; updated for F-Script 1.2;
242                          zoom to fit in application list; added help
243                          tags for workspace; focus workspace initially
2441.0.2 - (unreleased)    - minor cleanups, added error messages, updated
245                          scroll view component for faster UI response,
246                          removed help menu item because it's useless
2471.0.1 - 1 March 2002    - corrected message for error 5; libPatch 1.2;
248                          fixed endless confirmation on window close
2491.0.1d1 1 February 2002 - added error messages
2501.0   - 3 February 2002 - added dock menu, URL launching, check for
251                          F-Script framework, floating window,
252                          application name in interpreter window title,
253                          fixed bugs, cleaned up error handling,
254                          licensed under the GPL (because of ASM code),
255                          packaged, added Read Me file and license
2561.0d1 - 1 February 2002 - proof of feasibility, private test version
257
258
259CREDITS
260-------
261
262Thanks to the following people for their software and generous
263donations of source code:
264
265Philippe Mougin, for F-Script
266Mike Ferris, for TextExtras
267Apple, for Darwin
268Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.