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

Last change on this file since 227 was 227, checked in by rchin, 14 years ago

Updated nib to make button and menu item have the same name. Update readme with new features.

File size: 9.6 KB
Line 
1F-Script Anywhere 1.2 [5 January 2004]
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.2 was tested with FScript.framework 1.2.5
27(20031020) and Mac OS X 10.3.2 (7D24).  If you are using an earlier
28F-Script version, please upgrade.  F-Script Anywhere 1.2 should also
29work with Mac OS X 10.2.x, but will not work with Mac OS X 10.1 or
30earlier: please use F-Script Anywhere 1.1.5 instead.
31
32
33USAGE
34-----
35
36Open the F-Script Anywhere application.  Pick a Cocoa application from
37the list and click Install or press return.  F-Script Anywhere will
38either install itself in that application, give you an error message,
39or crash.  (Hopefully not the latter!)
40
41Switch to the application, and you should find a ÒFSAÓ menu there.
42Select ÒNew F-Script WorkspaceÓ to display a F-Script workspace.
43This behaves like any other workspace, except it's executing within
44the context of the application.
45
46You can also install F-Script Anywhere by using its dock menu.  If
47the frontmost application is a Cocoa application, just pick ÒInstallÉÓ
48from the menu and F-Script Anywhere will install in that application.
49If F-Script Anywhere canÕt install, the menu item will tell you so,
50or F-Script AnywhereÕs icon will bounce to indicate a pending sheet
51explaining the problem.
52
53To remove F-Script Anywhere from an application, quit the application.
54Because of limitations in Apple's Objective-C runtime, it is
55impossible to remove F-Script Anywhere while the application is
56running.
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. Check out the source of 'otool' from the Darwin CVS repository.
68   This is required because there's a bug in the function that returns
69   the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
70   It identifies all Cocoa applications as Carbon ones.  So as a
71   workaround, F-Script Anywhere examines the application itself to
72   see what libraries it links with.  (This may fail if you're doing
73   something weird like linking to development versions of Foundation
74   and AppKit, but since I don't work for Apple, I couldn't test that
75   eventuality.)
76
77   Check out Commands/Apple/cctools/{include,libstuff} from Darwin
78   CVS into the "Darwin source" directory.  If you don't have a CVS
79   account, go to <http://www.opensource.apple.com/> and get one.
80
81   cd to the libstuff directory and type 'make' (it doesn't use
82   jam/pbxbuild).  I _think_ this is all you need.
83
843. Open 'F-Script Anywhere.pbproj' in Xcode and build the Application
85   target.  This target depends on the Bundle and Bundle Loader
86   targets, so you don't need to build them separately.  You
87   shouldnÕt see any errors or warnings, and the F-Script Anywhere
88   application (as well as two bundles, which you can ignore because
89   they are copied into the application bundle) will appear in the
90   build product directory.
91
92If you have any problems building F-Script Anywhere, please let me
93know.
94
95
96FREQUENTLY ASKED QUESTIONS
97--------------------------
98
99Q. What is F-Script?
100
101A. F-Script is a dialect of Smalltalk which includes a bridge to
102   the Objective-C runtime on Mac OS X.  It's open-source, and
103   very nice.  Its author, Philippe Mougin, has written several
104   articles on it, and documentation is available from the
105   F-Script Web site:
106
107   <http://www.fscript.org/>
108
109
110Q. How do you access user interface elements?
111
112A. One way is to access a window and its views programmatically:
113
114   > app := NSApplication sharedApplication
115
116   > windows := app windows
117
118   > windows
119   NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
120   0x1f0cea0>}
121
122   > windows collect: [:each | each title]
123
124   error: an instance of NSWindow does not respond to "collect:"
125
126   (...a gentle reminder that this is not Smalltalk...)
127
128   > windows title
129   {'F-Script', '', ''}
130
131   (...but F-Script has some tricks of its own...)
132
133   > fsw := windows at: 0
134
135   > fswView := fsw contentView
136
137   To open an F-Script object browser on fswView, type:
138
139   > sys browse: fswView
140
141   Or, click ÒNew Browser: Object...Ó, then click on fswView.
142   Click 'subviews' in the message list.  You can use 'subviews'
143   repeatedly on container views if needed.
144
145
146Q. ThatÕs too hard, especially all that scrolling.
147
148A. If you need to access a view (such as a button or text field), menu or
149   window, youÕre in luck.  Click in an F-Script workspace window, then
150   choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
151   Follow the instructions in the window to select a user interface
152   element, view it in an object browser or assign it to a variable.
153
154   The F-Script object browser now provides a similar feature: click the
155   "Select view" button.
156
157
158Q. I donÕt like F-ScriptÕs syntax.  I don't like the object browser.
159   I donÕt like you either.
160
161A. I didnÕt write F-Script.  Please address your questions to
162   F-ScriptÕs author or the F-Script mailing list.
163   
164   <http://www.fscript.org/contacts.htm>
165
166   Oh, and get lost.
167
168
169Q. My question isn't answered here.
170
171A. That's not a question.  But if you have a question about F-Script
172   Anywhere, a suggestion or a bug to report, please email it to me at
173   <fsa@sabi.net>.  Please try to keep your messages short and to the
174   point, and I'll get back to you as soon as my schedule will allow.
175   Thanks!
176
177
178VERSION HISTORY
179---------------
1801.3   - 5 May     2006  - Fixed leaking of file handles
181                        - Removed deprecated F-Script functions
182                        - New associate option that automatically
183                          brings up a new browser without an
184                          interpreter window
185                        - Auto-inject feature
1861.2   - 5 January 2004  - fixed window behavior on startup, delaying
187                          display until launch is complete
188                        - replaced libPatch with mach_inject and
189                          SCPatch: provides improved compatibility
190                          with Mac OS X 10.3 (doesn't crash randomly
191                          any more!)
192                        - no longer requires F-Script Anywhere
193                          application to be running while installed
194                          in applications
195                        - F-Script Anywhere can now be installed in
196                          itself
197                        - check for F-Script version on startup
198                        - use new, documented F-Script API for
199                          identifier validation in associate window
200                        - prepared for localization
201                        - enable "Install" button when appropriate at
202                          application startup
203                        - fixed focus ring "flicker" on Mac OS X 10.3
2041.1.5 - 1 October 2002  - better identify Cocoa vs. Carbon applications
205                          on Jaguar; added hierarchical window list to
206                          FSA menu; fixed startup crash on Puma with
207                          certain Carbon CFM applications
2081.1.4 - 25 August 2002  - fixed miscellaneous Jaguar issues; worked
209                          around broken application quit notifications;
210                          added unique interpreter/associate window titles
2111.1.3 - 24 July 2002    - added bullseye-menu targeting cursor; added menu
212                          association; work around bug by stopping capture
213                          on suspend; added delegate, data source, target,
214                          cell selection for views; window controller for
215                          windows
2161.1.2 - 18 July 2002    - fixed more startup issues with list management;
217                          properly scale icons of apps which have no
218                          small icons; added user interface association
2191.1.1 - 3 July 2002     - fixed inefficiencies responsible for long
220                          startup time; reorganized Window menu; support
221                          paths to applications which contain non-ASCII
222                          characters [Martin HŠcker]; added sample code
223                          to grab UI elements [Philippe Mougin]; cleaned
224                          up code and distribution layout
2251.1   - 25 April 2002   - revised terminology; updated for F-Script 1.2;
226                          zoom to fit in application list; added help
227                          tags for workspace; focus workspace initially
2281.0.2 - (unreleased)    - minor cleanups, added error messages, updated
229                          scroll view component for faster UI response,
230                          removed help menu item because it's useless
2311.0.1 - 1 March 2002    - corrected message for error 5; libPatch 1.2;
232                          fixed endless confirmation on window close
2331.0.1d1 1 February 2002 - added error messages
2341.0   - 3 February 2002 - added dock menu, URL launching, check for
235                          F-Script framework, floating window,
236                          application name in interpreter window title,
237                          fixed bugs, cleaned up error handling,
238                          licensed under the GPL (because of ASM code),
239                          packaged, added Read Me file and license
2401.0d1 - 1 February 2002 - proof of feasibility, private test version
241
242
243CREDITS
244-------
245
246Thanks to the following people for their software and generous
247donations of source code:
248
249Philippe Mougin, for F-Script
250Jonathan 'Wolf' Rentsch, for mach_inject
251Jon Gotow, for SCPatch and lots of advice
252Mike Ferris, for TextExtras
253Apple, for Darwin
254Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.