Copyright ©1998 by AAA+ Software Forschungs- und Entwicklungs Ges.m.b.H. All Rights Reserved.
3 | Developing Yellow Box Applications with Joy |
This section is a step by step tutorial on how to to write a simple application with Joy inside InterfaceBuilder. It can be carried out with the free demo version of Joy as well as with a Joy Explorer license. If you want to write stand-alone applications (which can be run without InterfaceBuilder) you need a Joy Developer license.
Overview
You can not only explore the Yellow Box interactively with Joy, you can also write full applications. Still there is no need to use the compiler as you can test the whole application (not only the interface!) in InterfaceBuilder's test mode.
Joy not only lets you send messages to ObjectiveC objects and lets you inspect the runtime with the objc:info command, it also includes a full Tcl 8.0 interpreter including a byte-stream compiler and allows you to teach methods written in Tcl to any Objective-C class or object! For a detailed description of the Joy language's features see the Joy Language Summary ; For a full treatment of all available commands see the Joy Command Reference which can be opened from any Joy command window using the man command.
Some example applications are included with the Joy distribution. They can be found in the directory %NEXT_ROOT%\LocalLibrary\Joy\Examples.
An application with Joy: LengthConverter
We will now build a very simple Joy application which converts centimeters to inches and vice versa. We will only use InterfaceBuilder.app and Edit.app to do so - no ProjectBuilder, no compiler and no linker are necessary.
If you have not done so yet, start InterfaceBuilder with the Joy palette installed (see the beginning of this document). Choose the New Joy Application command in InterfaceBuilder's Joy menu. This creates an untitled nib file already containing a main menu and a Joy interpreter. Resize the document window and set its title (in the inspector panel) to "LengthConverter". Drag an NSForm from the Views palette into this window. Label the two NSFormCells "inches" and "cm". Your window should now look somehow like this:
Figure 1: The LengthConverter's document window.
Now Ctrl-drag two connections from the Joy interpreter to the two NSFormCells. Make sure to connect the Cells (black frame when connecting) and not the whole Form (gray frame). In the Interpreter's connection inspector, click the Connect button each time. Name your variables inchesCell and cmCell, respectively.
Figure 2: The interpreter's connection inspector
Now we write the application code. Double click on the interpreter icon. An alert panel will appear.
Figure 3: Unparse alert panel
Click the Unparse button. A Joy source file will be created automatically and opened in Edit. There are three objects known to the Interpreter ($inchesCell, $cmCell and $self - the interpreter itself). You can teach new methods to each of this three objects and the three objc:teach statements are already provided in the source file (only a limited number of teaches is allowed if you don't have a Joy Developer license). The most useful method is the action: method, which is invoked when a user interface element is activated (e.g. the user presses Enter in an NSFormCell or clicks an NSButton). Add the following line to $inchesCell's action: method:
$cmCell setDoubleValue: [expr [$inchesCell doubleValue] * 2.54]
Add the following line to $cmCell's action: method:
$inchesCell setDoubleValue: [expr [$cmCell doubleValue] / 2.54]
Save the source file and go back to InterfaceBuilder. Choose Test Interface in InterfaceBuilder's Document menu to test your application. You can enter numeric values into any of the two fields, which gets converted when you press Enter. Choose Quit in the Main Menu to quit LengthConverter and go back to InterfaceBuilder.
If you want to create a standalone application (that does not need InterfaceBuilder to run) you can use the Save Nib as App... command in the Joy menu (only with Joy Developer version). This application's binaries are very small (about 50 Kilobytes per platform) and run on any Yellow Box system that has a licensed version of the Joy framework installed.
Debugging with Joy
You can interactively play with your application the same way as you did play with NSWindow and NSSavePanel in the first part of this tutorial. Simply choose the Joy... menu item in your application's menu while running in InterfaceBuilder's test interface mode. In LengthConverter (see above) you can manually set a FormCell by typing
joy> $inchesCell setDoubleValue: 2
Trigger the conversion by typing
joy> $inchesCell action: $self
Check the result by typing
joy> $cmCell doubleValue
5.08
You can cause a Joy interpreter to print a line of trace information on standard output (the console if the current application was double-clicked from WorkspaceManager) for every line of Tcl code it is about to execute by typing cmdtrace on into that interpreter's command window (turn the feature off with cmdtrace off).
If you are feeling adventurous, you can also enter the Tcl debugger, which provides single-stepping and break point functionality, by typing the command dbg:debug -now. Then type h to get a listing of the available debugger commands. Be aware, though, that you can easily hang or crash your application (or InterfaceBuilder!) by setting a break point in the wrong place. Not every AppKit method likes to be intercepted by a modal command loop!
Though you can write full-fledged applications using Joy alone, in many cases you will want to add Joy to your existing projects written in Objective-C or Java, maybe adding some new modules written in Joy or just using it as a debugging tool. The next section shows you step by step how you can link Joy to an existing project.