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

F-Script Anywhere 1.1.5 [1 October 2002]
=======================

Add a F-Script interpreter to Cocoa applications dynamically.

Written by Nicholas Riley <mailto:fsa@sabi.net>.
Obtain updates from <http://web.sabi.net/nriley/software/>.


WHAT IS IT?
-----------

Ever wanted to inspect a Cocoa applicationÕs objects from the inside?
Frustrated with using GDB to debug Objective-C?

You need F-Script Anywhere! (with apologies to Guido van Rossum)


INSTALLATION
------------

Install F-Script; you can download it at <http://www.fscript.org/>.
In particular, make sure the framework is installed in a Frameworks
directory, such as /Library/Frameworks or ~/Library/Frameworks.

F-Script Anywhere 1.1.5 was tested with FScript.framework 1.2.2
(20020604), Mac OS X 10.1.5 (5S66) and 10.2.1 (6D52).  It may or may
not work with earlier or later versions, I don't know.  If you are
using an earlier F-Script version, please upgrade.


USAGE
-----

Open the F-Script Anywhere application.  Pick a Cocoa application from
the list and click Install or press return.  F-Script Anywhere will
either install itself in that application, give you an error message,
or crash.  (Hopefully not the latter!)

Switch to the application, and you should find a ÒFSAÓ menu there.
Select ÒNew F-Script WorkspaceÓ to display a F-Script workspace.
This behaves like any other workspace, except it's executing within
the context of the application.

You can also install F-Script Anywhere by using its dock menu.  If
the frontmost application is a Cocoa application, just pick ÒInstallÉÓ
from the menu and F-Script Anywhere will install in that application.
If F-Script Anywhere canÕt install, the menu item will tell you so,
or F-Script AnywhereÕs icon will bounce to indicate a pending sheet
explaining the problem.

When you're finished, quit the application before quitting F-Script
Anywhere, otherwise the application will crash.  This is an inherent
limitation of the Objective-C runtime, and I can't do anything about
it.  F-Script Anywhere will warn you if you try to quit it when it's
still installed in active applications.


BUILDING
--------

The source to F-Script Anywhere is included.  It has a number of
dependencies.

1. Install FScript.framework (see above).

2. Install libPatch 1.2.1.

   <http://web.sabi.net/nriley/software/libPatch-1.2.1.tgz>

   I'd suggest you do it this way:

   % cd /
   % sudo gnutar --preserve-permissions -zxf libPatch-1.2.1.tgz
   Password:
     (please don't use StuffIt Expander)

   This installs files in /Developer/Examples and
   /usr/local/{bin,include,lib}.  If you're paranoid, you may want to
   check the contents of the directory before installing.

   Please note that the layout of the libPatch distribution has changed
   since libPatch 1.0; the above instructions will not work for 1.0.
   
   I did not write libPatch, but am distributing it for your convenience
   because it may be unavailable from its original source.  libPatch is
   unsupported; please do not contact libPatchÕs author for support.

3. Check out the source of 'otool' from the Darwin CVS repository.
   This is required because there's a bug in the function that returns
   the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
   It identifies all Cocoa applications as Carbon ones.  So as a
   workaround, F-Script Anywhere examines the application itself to
   see what libraries it links with.  (This may fail if you're doing
   something weird like linking to development versions of Foundation
   and AppKit, but since I don't work for Apple, I couldn't test that
   eventuality.)

   Check out Commands/Apple/cctools/{include,libstuff} from Darwin
   CVS into the "Darwin source" directory.  If you don't have a CVS
   account, go to <http://www.opensource.apple.com/> and get one.

   cd to the libstuff directory and type 'make' (it doesn't use
   jam/pbxbuild).  I _think_ this is all you need.

4. Open 'F-Script Anywhere.pbproj' in Project Builder and build the
   Application target.  It depends on the Library target, so you don't
   need to build it separately.  You shouldnÕt see any errors or
   warnings, and the F-Script Anywhere application (as well as the
   library, which you can ignore because it is also copied into the
   application bundle) will appear in the build product directory.

If you have any problems building F-Script Anywhere, please let me
know.


FREQUENTLY ASKED QUESTIONS
--------------------------

Q. What is F-Script?

A. F-Script is a dialect of Smalltalk which includes a bridge to
   the Objective-C runtime on Mac OS X.  It's open-source, and
   very nice.  Its author, Philippe Mougin, has written several
   articles on it, and documentation is available from the
   F-Script Web site:

   <http://www.fscript.org/>


Q. How do you access user interface elements?

A. One way is to access a window and its views programmatically:

   > app := NSApplication sharedApplication

   > windows := app windows

   > windows
   NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
   0x1f0cea0>}

   > windows collect: [:each | each title]

   error: an instance of NSWindow does not respond to "collect:"

   (...a gentle reminder that this is not Smalltalk...)

   > windows title
   {'F-Script', '', ''}

   (...but F-Script has some tricks of its own...)

   > fsw := windows at: 0

   > fswView := fsw contentView

   To open an F-Script object browser on fswView, type:

   > sys browse: fswView

   Or, click ÒNew Browser: Object...Ó, then click on fswView.
   Click 'subviews' in the message list.  You can use 'subviews'
   repeatedly on container views if needed.


Q. ThatÕs too hard, especially all that scrolling.

A. If you need to access a view (such as a button or text field), menu or
   window, youÕre in luck.  Click in an F-Script workspace window, then
   choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
   Follow the instructions in the window to select a user interface
   element, view it in an object browser or assign it to a variable.


Q. F-Script Anywhere fails miserably on Jaguar.

A. It shouldnÕt.  Apple re-added support for libPatch to Jaguar late
   in the development process, with the result that F-Script Anywhere
   works.  libPatch nevertheless needs to be replaced with a more
   robust mechanism, and I am currently working on using the Application
   Enhancer SDK <http://www.unsanity.com/haxies/ape/sdk/> for a future
   version of F-Script Anywhere.


Q. F-Script Anywhere fails to recognize Spring as a Cocoa application.

A. Yes, I'm aware of the irony: I contributed code to Spring.  Spring
   uses a unique application launching mechanism which makes it
   difficult to determine what type of application it is.  The only
   current workaround is to upgrade to Jaguar, where Spring will be
   correctly identified.  This problem will be remedied with the move
   to Application Enhancer, described above, in a future version of
   F-Script Anywhere.


Q. I donÕt like F-ScriptÕs syntax.  I don't like the object browser.
   I donÕt like you either.

A. I didnÕt write F-Script.  Please address your questions to
   F-ScriptÕs author or the F-Script mailing list.
   
   <http://www.fscript.org/contacts.htm>

   Oh, and get lost.


Q. My question isn't answered here.

A. That's not a question.  But if you have a question about F-Script
   Anywhere, a suggestion or a bug to report, please email it to me at
   <fsa@sabi.net>.  Please try to keep your messages short and to the
   point, and I'll get back to you as soon as my schedule will allow.
   Thanks!


VERSION HISTORY
---------------

1.1.5 - 1 October 2002  - better identify Cocoa vs. Carbon applications
                          on Jaguar; added hierarchical window list to
                          FSA menu; fixed startup crash on Puma with
                          certain Carbon CFM applications
1.1.4 - 25 August 2002  - fixed miscellaneous Jaguar issues; worked
                          around broken application quit notifications;
                          added unique interpreter/associate window titles
1.1.3 - 24 July 2002    - added bullseye-menu targeting cursor; added menu
                          association; work around bug by stopping capture
                          on suspend; added delegate, data source, target,
                          cell selection for views; window controller for
                          windows
1.1.2 - 18 July 2002    - fixed more startup issues with list management;
                          properly scale icons of apps which have no
                          small icons; added user interface association
1.1.1 - 3 July 2002     - fixed inefficiencies responsible for long
                          startup time; reorganized Window menu; support
                          paths to applications which contain non-ASCII
                          characters [Martin HŠcker]; added sample code
                          to grab UI elements [Philippe Mougin]; cleaned
                          up code and distribution layout
1.1   - 25 April 2002   - revised terminology; updated for F-Script 1.2;
                          zoom to fit in application list; added help
                          tags for workspace; focus workspace initially
1.0.2 - (unreleased)    - minor cleanups, added error messages, updated
                          scroll view component for faster UI response,
                          removed help menu item because it's useless
1.0.1 - 1 March 2002    - corrected message for error 5; libPatch 1.2;
                          fixed endless confirmation on window close
1.0.1d1 1 February 2002 - added error messages
1.0   - 3 February 2002 - added dock menu, URL launching, check for
                          F-Script framework, floating window,
                          application name in interpreter window title,
                          fixed bugs, cleaned up error handling,
                          licensed under the GPL (because of ASM code),
                          packaged, added Read Me file and license
1.0d1 - 1 February 2002 - proof of feasibility, private test version


CREDITS
-------

Thanks to the following people for their software and generous
donations of source code:

Philippe Mougin, for F-Script
Mike Ferris, for TextExtras
Apple, for Darwin
Frank Vercruesse, for ASM