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 Joy Explorer. If you want to write more complex stand-alone applications you need a Joy Developer license.




Overview

You can not only explore the Yellow Box interactively with Joy, you can also write full applications. There is still no need to use the compiler, linker, or Project Builder as with Joy you can test the whole application, not only the interface, in InterfaceBuilder's test mode.

Joy not only lets you send messages to Objective-C 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%\Local\Library\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, compiler or 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 something 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. Save your nib-file first, then double-click on the interpreter icon. An alert panel will appear.


Figure 3: Unparse alert panel

Click the Unparse button. A Tcl 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 any of these 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 either of the two fields, which Enter is pressed the equivalent value is placed in the other . 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 previous section of this tutorial. Simply choose the Command Window menu item in your application's Joy menu while running in InterfaceBuilder's test interface mode. In LengthConverter (see above) you can manually set an NSFormCell by typing

tcl> $inchesCell setDoubleValue: 2

Trigger the conversion by typing

tcl> $inchesCell action: $self

Check the result by typing

tcl> $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.