F-Script Anywhere 2.0d2 [24 February 2008]
=======================
Add a F-Script interpreter to Cocoa applications dynamically.
Written by Nicholas Riley <mailto:fsa@sabi.net> and Robert Chin.
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 2.0d2 was tested with FScript.framework 2.0a2 and
Mac OS X 10.5.2 (9C31). If you are using an earlier F-Script version,
please upgrade. F-Script Anywhere 2.0 requires Mac OS X 10.5 or
later; if you're using Mac OS X 10.4, download F-Script 1.3.5
(20070421) which includes F-Script Anywhere 1.3.
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.
To remove F-Script Anywhere from an application, quit the application.
Because of limitations in Apple's Objective-C runtime, it is
impossible to remove F-Script Anywhere while the application is
running.
BUILDING
--------
The source to F-Script Anywhere is included. It has a number of
dependencies.
1. Install FScript.framework (see above).
2. In the "Darwin source" directory, check out Darwin's cctools from
<http://www.opensource.apple.com/>, untar it and rename the
directory to "cctools". cd to the libstuff directory and type
'make RC_CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc" RC_XBS=YES dynamic'.
3. Put a version of FScript.framework into the Source folder. This
is used for the F-Script framework auto installer.
4. Open 'F-Script Anywhere.xcodeproj' in Xcode and build the Application
target. This target depends on the Bundle and Bundle Loader
targets, so you don't need to build them separately. You
shouldn’t see any errors or warnings, and the F-Script Anywhere
application (as well as two bundles, which you can ignore because
they are 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
click or choose “Browser for Target…” 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.
The F-Script object browser now provides a similar feature: click the
“Select View” button.
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>. I'll get back to you as soon as my schedule will
allow. Thanks!
VERSION HISTORY
---------------
2.0 - unreleased - Injectable into Cocoa garbage collected apps
(64-bit applications are not yet supported)
- Requires F-Script 2.0 and Mac OS X 10.5
1.3.1 - 17 October 2007 - Compatible with Mac OS X 10.5
1.3 - 5 May 2006 - Fixed leaking of file handles
- Removed deprecated F-Script functions
- New associate option that automatically
brings up a new browser without an
interpreter window
- Auto-inject feature
1.2 - 5 January 2004 - fixed window behavior on startup, delaying
display until launch is complete
- replaced libPatch with mach_inject and
SCPatch: provides improved compatibility
with Mac OS X 10.3 (doesn't crash randomly
any more!)
- no longer requires F-Script Anywhere
application to be running while installed
in applications
- F-Script Anywhere can now be installed in
itself
- check for F-Script version on startup
- use new, documented F-Script API for
identifier validation in associate window
- prepared for localization
- enable "Install" button when appropriate at
application startup
- fixed focus ring "flicker" on Mac OS X 10.3
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
Robert Chin, for maintenance and Intel/Leopard porting
Jonathan 'Wolf' Rentsch and Bertrand Guihéneuf, for mach_inject
Jon Gotow, for SCPatch and lots of advice
Mike Ferris, for TextExtras
Apple, for Darwin
Frank Vercruesse, for ASM