Chapter 9

Creating Presentations and
Channels with Bongo

Have you ever tried building a user interface for a Java application using raw Abstract Windowing Toolkit (AWT) code? Not a lot of fun, is it? Just designing the layout of a window and making sure all the widgets are in the right place can be incredibly time-consuming, particularly with the edit-compile-test cycle of working with Java code. Visual interface builders can help quite a bit, but you still have to deal with a lot of actual code, particularly if you want to create really sophisticated interfaces with dynamic layouts and complicated interactions between different windows and different elements on each window.

That's where Bongo comes in. Using Bongo, you can add and arrange user-interface elements (they're called widgets in Bongo-speak) on the screen by dragging them with the mouse, dynamically change their size and properties, and combine them into different kinds of containers. But Bongo isn't just an interface builder for Java applications, similar to what you would get with a Java development environment. Each Bongo widget can also have a script, which is an embedded bit of Java code that can determine the behavior of the object and allows it to interact with other objects in the same presentation. You create the scripts inside Bongo, and you can save and test and run them inside Bongo as well–no compiler needed. In this respect, Bongo is more like HyperCard or Director than it is a simple user-interface builder for Java; it's a tool you can use to create simple applications and presentations without needing to know a lot about actually programming in Java. If you're unfamiliar with Java or with programming, you can most likely do quite a lot with Bongo, or you can even create interfaces to be used by a Java programmer later on. Even if you do know Java, you can use Bongo for quick prototyping or building simple interfaces for your applications.

So what does building interfaces have to do with channels and with Marimba Castanet? Quite a lot, actually. Bongo presentations can be used directly as channels, with or without scripts behind their widgets. You can also create a Java application channel that uses a Bongo presentation as its interface. In fact, creating a channel that uses a Bongo interface is easier than creating one with a more standard AWT interface (as you'll learn in the next chapter). So even if you do intend to create heavy-duty Java-based channels, you might want to learn Bongo anyhow.

In this chapter, then, you'll get a general-purpose overview of how to use Bongo to create simple presentations and how to turn those presentations into channels. In Chapter 10, "Creating Application Channels," you'll learn how to use Bongo presentations in application channels (and finish up covering the four kinds of channels you can create with Castanet).



Note

A single chapter in this book isn't nearly enough to cover the use of Bongo in all its glory. For that reason, another book with plenty more details is available. The Official Marimba Guide to Bongo, by Danny Goodman and published by Sams.net, is the companion book to this one and should be available at the same place you bought this book. Collect both! Win valuable prizes! Impress your friends!


Getting, Installing, and Starting Bongo

Bongo is a separate tool from Castanet itself; you have to acquire and install it separately from the tuner and transmitter software.

An evaluation version of Bongo is available on the CD that comes with this book. You can also download the latest version from Marimba's Web site at http://www.marimba.com/ if you don't have access to a CD-ROM drive, or you can purchase the full version of Bongo (see Marimba's Web site for details).

Installing Bongo

If you're using the CD-ROM version, you must install the software onto your hard drive; it will not run directly from the CD. For Windows, you need to be running Windows 95 or Windows NT 4.0, have at least 8MB of RAM and 4MB of free disk space. For Solaris, you need Solaris 2.4 or higher, 15MB of RAM and 4MB of free disk space.



Note

Bongo is also available on some other platforms. An alpha version is available from Marimba for the Macintosh/PowerPC but is not stable enough to be included with this book. See also the page at http://www.marimba.com/products/unsupported.html for information about versions of Bongo available for Linux, FreeBSD, and SolarisX86.


For Windows, the transmitter is an executable file called Trans1_0.EXE. On Solaris, it's a compressed tar archive called bongo1_0_tar.Z.



Note

If you're using the transmitter installer from the CD-ROM that came with this book, you can find the transmitter installer in the directory Marimba and then in the subdirectory for your platform (Win95, WinNT, or Solaris)–for example, Marimba\Win95\Bongo1_0.EXE.


To install Bongo for Windows, simply double-click the installer application. You are prompted for an installation location (C:\Marimba is the default), and after you enter it, all the files are installed.

To install Bongo for Solaris, pick a common location (such as home or /usr/local/). Copy the Bongo installer file to that location and decompress it, as follows:

cp bongo1_0_tar.Z /usr/local

uncompress bongo1_0_tar.Z

Finally, use the following tar command to install the files:

tar xvf bongo1_0_tar

The Bongo software is installed into a directory called bongo. The actual bongo program is in the bongo/bin/ directory; you might want to add that directory to your execution path so that you can easily start bongo later.

After installing Bongo, you can delete the tar file:

rm bongo1_0_tar

Starting Bongo

To start Bongo for Windows, navigate through the Start menu to the Castanet Bongo application. (See Figure 9.1.)

Figure 9.1. Starting Bongo.

To start Bongo for Solaris, use the full pathname bongo command at a system prompt, like this (substituting the actual location of the Bongo software):

/usr/local/bongo/bin/bongo

If you put the bongo/bin directory into your execution path, you should be able to type bongo to start it.

The first Bongo screen, shown in Figure 9.2, then appears on your desktop.

Figure 9.2. Welcome to Bongo.

Quick Start: Creating a Simple Presentation

Although I could sit here and explain to you in detail for a couple pages how Bongo works, you would probably fall asleep on me, and we would never get anything done. So let's jump right in and create a really simple presentation so that you can get a feel for what it's like to work with Bongo.

Choose File | New Presentation. A new, blank, Official Marimba Guide to Castanet Bongo presentation appears in its own window. (See Figure 9.3.)

Figure 9.3. A new, blank presentation.

When the new presentation appears, the main Bongo screen turns into a window with two panels: one for properties and one for scripts. Click the Properties tab to see the properties of this main presentation; the default properties are shown in Figure 9.4.

Figure 9.4. Presentation properties.

The values of the properties in this panel (and the number and type of properties) change depending on the element you have selected in the presentation window. Right now the entire presentation is selected, so its properties appear in the Properties panel.

First, change the size of the presentation. The values of the Bounds fields in the Properties page determine the size and position of the presentation (or of any widget inside the presentation). Here, the default size of the presentation is 500 by 300 pixels; if you change these values to 345 and 100 and click Apply, the presentation changes size.

Now, add some widgets to the presentation. A Bongo widget is a user-interface element that you can create, move around, and resize; you also can change its properties and add scripts to it. To create a new widget, select a menu item from the New menu in the presentation window. You can choose from lots of default widgets; for this example, start with a static text box. (See Figure 9.5.)

Figure 9.5. Creating a new static text box.

A static text box is one in which the text cannot be edited. Static text boxes make great labels for other user-interface elements. Choosing New | Static Text causes a new static text box to appear in the presentation. (See Figure 9.6.)

Figure 9.6. A new static text box.

The text box is selected, and the properties for that text box appear in the Properties page. Go to the Properties page, and change the font of the text box to Helvetica and the size to 24. Move down to the style property pull-down list box, and choose boxed. Then click Apply to set all the properties. (You must always click Apply for any property changes you make to take effect.) The text box you created then changes in style to reflect your property changes.

The default size, however, is most likely too small to fit the text. You can use the mouse to resize the text box by clicking and dragging the resize boxes. Stretch the text box to fit the full width of the window. Note that the size properties for the text box automatically change to reflect the new size of the text box.

Now, add some more widgets. Choose New | Button | CommandButton in the presentation window. A new button then appears on top of the text box. Using the mouse, drag it just below the text box to the bottom-left corner of the window. Note that you can use the arrow keys to "nudge" it one pixel in any direction to get it placed properly.

You can also move or resize the button using the Properties page. The Bounds field contain values for the x and y position of the widget (with 0,0 in the top-left corner and positive y downward) and for the width and height of the widget. Resize the button to be just a little smaller using these values so that the button is located at an x of 10 and a y of 65, and is 100 by 30 pixels big.

The other property to set for this button is the label, which is an editable field in the properties list. Change it to Some Text and click Apply. Figure 9.7 shows both the properties of the button and its result.

Figure 9.7. The new button widget.

Now, add two more buttons next to this one. Although you could choose more buttons from the New menu and then change their properties to match the first one, j it's easier to just copy and paste the button you've got. Select the button, choose Edit | Copy, and then choose Paste. The new button appears on top of the old one, so drag the new button to the right to make both buttons appear. Choose Paste again, and a third button appears. You can then arrange all three buttons in a row underneath the text box.

Now you have three buttons, all with the same label. Select the middle button and change its label to More Text (don't forget to click Apply to make the change). Choose the third button and change its label to Still More Text.

Got all that? You've now built a simple user-interface presentation, like the one shown in Figure 9.8. At this point, you might want to take a couple minutes and experiment with the various properties you can set in the presentation, such as the styles of the widgets or the background and foreground colors. (You can set the colors using the three squares in the top-right corner of the screen.) Don't forget to save the presentation file so that the inevitable system crash doesn't wipe out all your work. Bongo presentation files should usually have an extension of .gui.



Note

This example is included on the CD that comes with this book, in the folder Examples and in the folder BongoQuickStart below that. I've saved this presentation file as quickstart.gui.


Figure 9.8. The final presentation.

When you add new widgets to a presentation and modify their properties, you're in Edit mode for that presentation. To actually make the presentation work, you have to switch to Browse mode. You can choose both of these modes from the File menu in the presentation window. (See Figure 9.9.)

Figure 9.9. Browse and Edit modes.

If you switch to Browse mode, you'll find that your buttons are now clickable, although they don't do anything. Later in this chapter, you'll add scripts to make them do things.

Working with Presentations

You use Bongo to create Java presentations. The term presentation refers to a window and the user-interface elements, called widgets, that window contains. Presentations can also contain scripts to control the behavior of the widgets. Using scripts, you can create not just a user interface, but also a fully functioning program entirely inside Bongo.

In this section, I'll give you a quick overview of the basic Bongo features for creating presentations and using widgets.

Basics

To create a new presentation, choose File | New Presentation. A new presentation then appears, and the Bongo screen changes to the Properties and Scripts panels. Both of these panels dynamically change to reflect the properties and scripts of the current selected widget. When you first create a new presentation, the properties of that presentation are shown in the Properties panel. (See Figure 9.10.)

Figure 9.10. Presentation properties.

While working with presentations, you can choose from two modes of operation. The default is Edit mode, in which you can add widgets, move or resize them, change their properties, or edit their scripts. The other is Browse mode, in which you can test the behavior of the presentation. When you switch to Browse mode (by choosing File | Browse in the presentation window), the Properties and Scripts panels change to the initial Bongo screen. Switch back to Edit mode by choosing File | Edit.

Choosing and Modifying Widgets

To add a widget to a presentation, choose its type from the New menu in the presentation window. The standard Marimba widgets give you most basic user-interface elements to choose from, or you can also import custom widgets that you or other Bongo programmers have created. (You'll find a summary of the default widgets in "A Short Overview of Bongo Widgets," later in this chapter.)

The new widget appears in its default state in the top-left corner of the presentation. You can then move or resize it with the mouse, or modify its properties in the Properties panel.

The following are some other features of Bongo relating to widgets:

Presentation and Widget Properties

Each widget has a set of properties, including properties common to all widgets and properties for that specific type of widget. For example, text box widgets have different properties from button widgets. When you select a widget in Bongo's Edit mode, its properties appear in the Properties panel. (See Figure 9.11.)

Figure 9.11. Various widget properties.

The upper part of the panel contains properties common to all widgets, including its name, bounds, font, and colors. Note also that the Widget field shows the Java class name for the currently selected widget–for example, marimba.gui.CommandButtonWidget or marimba.gui.Presentation.

The bottom half of the panel contains properties specific to this kind of widget–for example, button labels, check box states, text inside a text box, or the maximum and minimum values of a scrollbar. The properties in this panel change depending on which widget you currently have selected.

Each time you change a widget's properties, you must then click Apply to apply the changes to the widget; you can also press the Return or Enter key to apply the changes. Click Reset to change the properties back to their current values.

For the most part, using Bongo to create simple presentations should be easy if you've ever used a user-interface builder or even a drawing tool. After you have the basic presentation in place, you can then add scripts to make the presentation have behaviors.

Adding Scripts to Widgets

Scripts make Bongo different from a standard user-interface builder. By adding scripts to a presentation, you can create simple applications wholly in Bongo. You don't need to drop out of the interface to work in raw Java code (although, as you'll learn in the next chapter, you can also use a Bongo presentation as the interface to a Java application).

Before you get too excited about Bongo scripting, however, you should know that Bongo scripts are written in Java code and require that you have at least a basic understanding of how Java and AWT events work. If you don't have this background, you may find scripting rough going.

In this section, I'll give you a general overview for creating simple Java scripts. For more details, check out The Official Marimba Guide to Bongo (Sams.net Publishing).

The Script Panel

Just as each widget has its own set of properties, it also can have its own script. To edit the script for a widget, select that widget in Edit mode and then choose the Script panel. By default, all scripts are blank. Figure 9.12 shows a blank Script panel.

Figure 9.12. The Script panel.

The Bongo scripts that you create inside these panels are most always reactions to events in the presentation. For example, you can add a script to do something when a button is clicked or when a menu item is selected. Different widgets can respond to different script events.

The actual Bongo scripts, which are written in Java, are based on standard Java event mechanisms such as the handleEvent() and action() methods. For example, for a button widget, the standard template for a script is the action() method, which looks like this:

public void action() {

...

}

Inside that action() method, you can get and set the values of other widgets in the presentations, do calculations, load or play media files, or do anything else to the presentation that you need, using standard Java code. The action() method is called each time the button that contains it is clicked.

Different widgets can take different kinds of scripts. Although it would be nice for Bongo to provide templates for each kind of script a widget can accept, unfortunately, the 1.0 version of Bongo doesn't provide that behavior. You have to look up the possibilities for each kind of widget and add the code yourself. (A future version of Bongo will give you templates for the kinds of scripts you can add.)

After you edit the script for a widget, don't forget to click the Apply button. In addition to saving the script for that widget, Bongo also compiles the script into Java bytecode for you.

Example: Adding a Script to the Text Presentation

Puzzled yet? Bongo scripting can be very confusing, particularly if you haven't seen Java before. An example should help make things at least a little bit clearer.

Let's go back to that presentation you created in the "Quick Start" section of this chapter. Right now, all you have are a few buttons and text fields; no scripts are attached, so the presentation doesn't do anything. You're going to add scripts to each of the buttons so that when you click a button, the text field changes to reflect the label of the button. For example, clicking the Some Text button changes the text field to Some Text, and similarly with the other buttons.

Note that you need to add a script only to the widget that triggers the action. In this case, the three buttons have three separate scripts, but the text field doesn't need a script at all.

Make sure that you're in Edit mode in Bongo, and select the first button (Some Text). The properties then appear in the Properties panel; click the Script tab to switch to the Script panel.

For buttons, the script you usually want to add is the action() script, which is called when the button is clicked and released. The action method looks like this (don't add it yet; I'm just showing it to you here so that you know what it looks like):

public void action() {

...

}

Inside the action method, you add the code to change the value of the text box. First, however, you need to name the text box so that you can get ahold of its values. Choose the text box in the presentation window; then switch to the Properties panel. In the Name field, add a name for the text box widget; for this example, enter theText. Figure 9.13 shows the result.

Figure 9.13. TextBox properties.

Click Apply. Then go back to the Some Text button and the script for that button. (Make sure that you select the button before turning to the Script panel; otherwise, you'll edit the script for the text box.) Add the action() method, as shown previously, to that box.

Inside the script, change the text box's value to be the text inside the button. To do so, you need to get a reference to the text box. You can make this reference in a couple ways. One way is to use the getWidget() method with the name of the text box, as follows:

StaticTextBox tbox = (StaticTextBox) getWidget("theText");

This line actually does three things:

Make sure that you include the name of the text box exactly as you typed it in that widget's properties, using the same upper- and lowercase.

Now that you have a reference to the text box, you just need to stuff the right text into it. Although you could just duplicate the label of the button here, a most elegant (and reusable) solution is to use the getText() method, which returns the label of the button. Use the setText() method to change the value of the text box, like this:

tbox.setText(getText());

Although this script works just fine, it's actually the longer way of changing the text inside a text box. There's actually an easier way: The setText() method is defined on all widgets and has a form that lets you specify the name of the widget to change. So you can do precisely the same thing with only one line, like this:

setText("theText",getText());

With this form, you don't need to store the handle to the text box; this one line works just as well. Figure 9.14 shows the Script panel with the final script (the one-line version) in place.

Figure 9.14. The final button script.

When you're done editing the script, don't forget to click Apply. Clicking this button compiles the script so that the presentation will work (it also lets you know if you have any errors in your script).

Switch to Browse mode in the presentation. Now when you click the Some Text button, the text of the text box should change to Some Text. If it doesn't, make sure that the name of the text box in the properties matches exactly the name of the text box in your script. Make sure also that the Some Text button still has its script. (If you don't click Apply, the button reverts to its previous state–without the script.)

After you've got the one button working, all you have to do is copy the script to the other two buttons. Because the script is generic enough to work with a button of any label, you don't have to modify the script from button to button. Just copy and paste the contents of the script from one Script panel to another.



Note

You could also just copy and paste the entire button, and the script will go along with it. In this example however, because we've already created the buttons, we'll copy the scripts instead.


Despite the fact that this particular script doesn't do anything very exciting, it does give you a basic idea of how scripts work. By adding different methods to the Script panel, you can react to different events for different widgets and have your program act accordingly. Much of scripting is simply understanding the neat things you can do to the different widgets. For more details, check out the documentation that comes with Bongo or pick up the Bongo book I mentioned earlier.

A Short Overview of Bongo Widgets

Bongo comes with a rich set of basic widgets that you can use to create various forms of presentations, and each of these widgets has properties and scriptable values that you can change and modify in the Properties panels or dynamically through scripting. Although I don't have the space to go over all the features of all the Bongo widgets, I can provide a basic overview of the widgets themselves. For further details, you should consult the Widget online documentation or the Official Marimba Guide to Bongo.

To get a good visual overview of the kinds of widgets you can use in Bongo, take a look at the demo presentation called widgets.gui (contained in the bongo/demo/examples folder). It shows many of the default widgets with various properties set. Also, I've included many very simple examples (mostly for the screen shots in this chapter) in the folder called Presentations as part of the examples on the CD for this book.

Buttons

Bongo provides five different kinds of button widgets, all of which are subclasses of the class ButtonWidget:

Figure 9.15 shows examples of many these buttons. (The URL button is not shown.) The different buttons in each group show different properties including disabled, filled, and boxed.

Figure 9.15. Button widgets.

The first three kinds of buttons provide standard button-like behavior: clicking the button triggers some action. For MenuButtons, several options are arranged in a pull-down menu; you can choose different options based on which menu item you select.



Note

MenuButtons are not like combo boxes or selection menus, where you can choose an item and then do something later. MenuButton widgets produce actions immediately, just as menus in menu bars might.


URLButtons are similar to regular buttons, except that they have only one action: they switch control to the user's Web browser to load a Web page (the URL for the URLButton is one of its properties).

Finally, Checkbox and Option are special forms of buttons that allow you to set true or false states for options. They do not generally trigger actions themselves; rather their state is tested when some other action occurs. Check boxes can be individually checked or unchecked; Options (also called radio buttons) are generally arranged in groups so that only one can be selected at any time.

Text Boxes

Text widgets, all of them subclasses of the TextWidget class, allow you to display text either as static labels or as editable text boxes. Bongo has four text widgets:

Figure 9.16 shows examples of all these widgets.

Figure 9.16. Text field widgets.

You can script text box widgets to keep track of either mouse or keyboard events, as well as mouse and keyboard focus.

Choices

Choices are widgets for choosing one item out of a list of items. Except where noted, these widgets are subclasses of ChoiceWidget:



Note

At the time of this writing, a ComboBox widget is also promised but not yet implemented. Future versions of Bongo will include it.


Figure 9.17 shows some examples of Choice widgets.

Figure 9.17. Choice widgets.

Choice widgets, unlike pull-down menus, generally do not trigger actions. Like check boxes and options, their state is generally tested in response to some other action–for example, a button being clicked.

Containers

Container widgets are simply widgets that can contain other widgets. They include simple widgets to group together other widgets all the way up to very sophisticated layout widgets that include a visual appearance as well as container behavior. Except where noted, all the following container widgets are subclasses of ContainerWidget:

Figure 9.18. Groups and GroupBoxes.

Figure 9.19. ScrollingContainer and List widgets.

Figure 9.20. Trees and TreeNodes.

Figure 9.21. A Folder widget.

Values

You use value widgets to show numeric positions along some scale. Value widgets can either be display only (for example, to show that 50 percent of an operation has occurred), or they can be adjusted by the user (for example, to choose a value between 1 and 10). All the following value widgets are subclasses of the ValueWidget class:

Figure 9.22 shows the various Value widgets.

Figure 9.22. Value widgets.

Animation

Bongo provides two widgets for creating simple animation inside your presentation. Both of them are subclasses of the class AnimatedWidget:

Shapes

The shape widgets provide simple decorative elements for presentations; no actions are associated with these elements. All the following are subclasses of the class ShapeWidget:

Media (Resources)

Media or resource widgets allow you to import external image, audio, and other presentation files into the current presentation and play them. The following media widgets are generally subclasses of ResourceWidget:

Figure 9.23 shows some sample resources.

Figure 9.23. Resource widgets.

AWT

Finally, AWT widgets (subclasses of AWTWidget) are the last group of widgets I'll cover in this chapter. They allow you to mix AWT components and user interface elements as well as entire applets into your Bongo presentation.

Figure 9.24 shows both some basic AWT elements (note that they appear very much like widgets) and an embedded applet.

Figure 9.24. AWT widgets.

Converting Bongo Presentations to Channels

Just when you thought you were reading the wrong book, at the end of this chapter, I finally get back to the original point: creating Castanet channels. Bongo presentations can be used as channels almost as easily as HTML Web sites and applets can. If you do all your development scripting inside Bongo, and your presentation works happily inside Bongo, then you're all set. All you need to do is to publish the presentation with the right set of channel properties.

To publish a presentation as a channel, first collect your .gui files and any other media (images, audio, Java classes, or other files) that the presentation uses into a single channel directory. In addition to your own channel files, there's one other file you'll need: bongo.zip. This is the Marimba library that contains all the classes that make Bongo work; you'll need to include it with each channel you create that uses Bongo presentations. But don't panic; keep in mind that because the tuner can share files between channels, often the users of your presentation channel will already have the bongo.zip library. If that's the case, the tuner won't bother downloading your copy. But, because you cannot guarantee that your users will have it, you should include it just to make sure.

You can get the bongo.zip library from the lib directory in your Bongo installation. Copy it to your channel directory, fire up Castanet Publish and add that directory to the list of Channels Under Development.

The properties for presentations are identical to all other channels, with the exception of the General properties. In the General Properties panel, you should make sure that the type of channel is Presentation, that you've included the name of the presentation file in the GUI File field, and that bongo.zip is listed in the class path field.. Figure 9.25 shows the General properties for the sample presentation (called quickstart.gui) created earlier in this chapter.

Figure 9.25. General properties for presentations.

Other than making sure that the general properties are correct and that you've included bongo.zip with every presentation, you don't need to do anything else to get a channel to work as a presentation. After you publish the presentation channel, you're done. You can subscribe to and run that presentation from a tuner just as if you were running it inside Bongo itself.

Summary

Marimba's Bongo is a terrific tool for creating presentations–graphical user interface-based applications with any number of elements (widgets) and scripts to control their behavior. In this chapter, you learned the basics of how to use Bongo to create these kinds of presentations and how to convert these presentations into Castanet channels.

If you haven't had enough of Bongo from this chapter, you should definitely check out The Official Marimba Guide to Bongo, the companion volume to this book, which contains just about everything you could ever want to know about Bongo.

Three down and one to go! In the next chapter, we'll dive into the last kinds of channels we have left to discuss: application channels.