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

Last change on this file since 14 was 14, checked in by Nicholas Riley, 17 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.