wabasoft how-to papers  
Products
Overview
Downloads
Fun and Games
More VMs
Dev Tools
Development
FAQ
Support
Specifications
How-to Papers
Company
Overview
Contact Us
Home Page
Writing a Simple Program

First, some prerequisites. You'll need a Java development tool such as Sun's JDK, Microsoft's SDK for Java, Microsoft's Visual J++, Symantec's Cafe, IBM's Visual Age or similar.

Next, you'll need to download the Waba SDK, available from this web site. It contains the bridge classes that allow you to run Waba programs under Java.

You don't need any tools other than a Java development tool and the WabaSDK to write Waba programs.

After downloading and extracting the files in the Waba SDK, you should find a "classes" subdirectory in the SDK distribution. This directory contains the Waba bridge classes that can be used to develop and debug Waba programs with standard Java development tools.

To get started, you should set your CLASSPATH to include the classes directory.

Here is an example CLASSPATH setting under Windows that includes the WabaSDK classes directory as well as the current directory. The CLASSPATH tells Java where to look for classes: 

> set CLASSPATH=\wabasdk.10\classes;.
This example assumes you are developing programs from the command line. If you are using a graphical development tool, you'll need to find the CLASSPATH setting in the development tool's options and set it to include the "classes" directory.

You should include the current directory (by using a . as in the above example) if you are going to be running Waba programs from the command line using Java. If you are running under UNIX, remember that the delimiter for the Java CLASSPATH setting is a colon and not a semi-colon as it is under Windows.

Starting Out

To get started, let's write a simple "HelloWorld" program. Every Waba program that has a user-interface has a main window. The class that defines the main window of a Waba program is called "MainWindow".

Here is a HelloWorld program that draws "Hello World" on the screen: 

import waba.ui.*;
import waba.fx.*;

public class HelloWorld extends MainWindow
{
public void onPaint(Graphics g)
  {
  g.setColor(0, 0, 0);
  g.drawText("Hello World", 0, 0);
  }
}
The first thing done in the above program is an import of the waba.ui and waba.fx packages. These packages contain the user-interface and effects classes required to create a program with a user-interface.

The onPaint() routine is called when the main window needs to paint its surface. The onPaint() routine is called with a Graphics object that can be used to draw in the window.

Methods that start with the prefix "on" are methods that you can override in a class to do things such as paint the surface and handle events. This prefix helps you to determine what methods you should implement vs. what methods you call to do things.

When the onPaint() method is called, the background has already been drawn so it is not necessary to clear the background before starting to draw.

The first thing in the onPaint() method is a call to set the current color to black. Colors are represented as red, green and blue color values, so the call to set the current color to black is g.setColor(0, 0, 0).

After setting the color, "Hello World" is drawn at coordinates (0, 0) which is the upper-left hand corner of the window.

Testing the Program

To run HelloWorld under Java you need to compile it: 

> javac HelloWorld.java

and then run it with: 

> java waba.applet.Applet HelloWorld

Notice that we can't simply execute HelloWorld directly since it is not a Java application. The waba.applet.Applet class provides an application main() that can start up a Waba app.

You can also run HelloWorld as a Java applet. Again, you use the Applet class to do this. The applet tag should look like: 

<applet code=waba/applet/Applet.class
 width=160 height=160>
<param name=appClass value="HelloWorld">
</applet>
With the code above in a .html file, you should be able to display the applet by executing: 
> appletviewer <filename>.html
Installing the Program on a PalmPilot

Once you've compiled and debugged your app under Java, you can move it over to a PalmPilot in just a couple of steps.

The programs you need to use to install your app on a PalmPilot are contained in the WabaSDK. They are called "exegen" and "warp". The exegen and warp programs in the WabaSDK only run under Windows (Windows95, 98 and NT).

Although the exegen and warp programs in the WabaSDK only run under Windows, there are versions available for other platforms. If you are using Sun Solaris or Linux for development, see the Waba FAQ for links to ported version of these programs.

The exegen program generates a small PalmPilot executable that launches your application. It also generates a .lnk file for Windows CE but if you're only developing for the PalmPilot you can ignore that file.

The exegen program has a number of parameters that specify the application name, icon and amount of memory that should be allocated for the program when it runs.

Let's give the program a name of "Hello". We'll generate a PalmPilot executable called "Hello.prc" to launch the program. In this example, we let the exegen program generate defaults for the program's icon (a black box) and memory: 

> exegen Hello HelloWorld Hello
As a note, you can execute the exegen program with no parameters to see the full list of defaults and parameters available.

The first parameter "Hello" is the name of the output file. A .prc will automatically be appended to it. The second parameter "HelloWorld" is the name of main window class.

The third Hello specifies the name of the warp file containing the program's classes (the .pdb is automatically appended). We'll create the warp file containing the program's classes a little later.

If you're familiar with PalmPilot development, you'll notice we did not specify a creator id. The id is automatically generated based on the program's name. If you run exegen without specifying the /q option, you can see the creator id it generates.

After you generate a Hello.prc file, you can install it on your PalmPilot with the Pilot install tool that comes as part of the Pilot desktop. You might want to try installing the Hello.prc right now and try to run it. It should give you a message stating that its classes were not found since we haven't installed the application's classes yet.

It could also give an error message saying that it couldn't find a WabaVM if one hasn't been installed on the machine. You'll need a WabaVM installed on the PalmPilot for your program to run. The VM does not come as part of the WabaSDK, it is available separately from the downloads on this web site. If you haven't done so already, you should download and install the WabaVM on your PalmPilot before continuing.

Next, we'll use the "warp" program to generate a file containing the application's classes. The classes are not modified by this program, they are simply packaged up into a PalmPilot PDB file. This is also known as a WARP (Waba Application Resource Package) file. Warp files can contain things other than classes, in fact they can contain files of any type.

Here we generate a warp file for the Hello program containing the HelloWorld class: 

> warp c Hello HelloWorld.class
The name we give the warp file must match the name of the warp file we specified when creating the launch program with exegen. If it does not match, the launch program will not be able to find the warp file containing the programs classes.

In the example above, we added a single class to the PDB file "HelloWorld.class". We could also have used: 

> warp c Hello *.class
to add all classes in the current directory to the PDB file. After creating the Hello.pdb file, you can install the PDB file on your PalmPilot using the install tool that came with your Pilot. When you click on the Hello icon, your program should run.

One note, the Pilot doesn't reload the list of applications displayed in the main menu by default. Many times, you'll need to switch to another program (such as Security) and then switch back to the main menu to get a new program to appear in the menu after installing it.

Also, to update an existing Waba program on the Pilot, you only need to reinstall the PDB file to install the new classes. You don't need to reinstall the PRC file. Unless, of course, you want to change the icon, name or memory to allocate for the program.

Installing the Program on a Windows CE Device

Now that we've built the HelloWorld program and installed it on a PalmPilot, we can try installing it on a Windows CE device. The process is very similar to what we did to install it on a PalmPilot.

For Windows CE, we need to generate two files; a launch program and a file containing the program's classes. We use the same programs we used for the PalmPilot, "exegen" and "warp" to create these files for Windows CE.

In fact, things are even easier because the exegen and warp programs automatically generate both the files for the PalmPilot and the files for Windows CE at the same time.

When we ran the exegen program to generate a launch executable for the PalmPilot, it also generated a .lnk launch file for Windows CE. A .lnk file is a Windows shortcut.

And when we ran warp to generate a .pdb for the PalmPilot, it also generated a .wrp file for Windows CE. A .wrp file is a Windows CE warp file.

So, if you've already created the .lnk and .wrp files by running the exegen and warp programs, you're ready to install the program on a Windows CE device. If you haven't yet run warp and exegen, you can execute the following: 

> exegen Hello HelloWorld Hello
> warp c Hello HelloWorld.class

These are the same commands we used to generate a launch and warp files for the PalmPilot.

To install the program on a CE device, you should create a Hello directory under "\Program Files" on the device and then copy the Hello.wrp file into it. Then you should copy the Hello.lnk file into the directory containing the Start menu.

By default, the generated .lnk file will look in the "\Program Files" directory for a directory with the same name as the program to find the program's .wrp file. If you want to the put .wrp file somewhere else, you can specify a different directory using the /p option with exegen.

You will also need a WabaVM installed on the CE device for the program to run. A WabaVM for Windows CE is available from the download section of this web site.

If you are running the Windows CE emulator from the "Microsoft CE Platform SDK", you should use the "empfile" program to copy the .lnk and .wrp file to the emulator for testing.

User Input

Our first sample program simply printed some output to the screen. In this example, we'll show how to handle events such as pen and key input.

Let's write a program called Scribble that lets a user scribble on the screen. We'll start out by subclassing MainWindow like we did before: 

import waba.fx.*;
import waba.ui.*;

public class Scribble extends MainWindow
{
public void onPaint(Graphics g)
  {
  g.setColor(0, 0, 0);
  g.drawText("Scribble 1.0", 0, 0);
  }
}
Next we'll add some variables. We'll want to remember the x and y position when a user puts the pen down so we can draw from that location when they move the pen. So, we'll keep the last position in variables lastX and lastY.

We'll also need a Graphics object to draw with. Since we need to draw "outside" of the onPaint() method, we'll need to create our own Graphics object to draw with. 

public class Scribble extends MainWindow
{
Graphics g;
int lastX, lastY;

public Scribble()
  {
  g = new Graphics(this);
  }
Next, we'll add an event handler that is called when the user presses the pen down and when the user drags the pen. The onEvent() method is called with a PenEvent when a user presses or drags the pen (or mouse).

It is also called for key events but in this example we are only concerned with PEN_DOWN and PEN_DRAG events. 

public void onEvent(Event event)
  {
  if (event.type == PenEvent.PEN_DOWN)
    {
    PenEvent pe = (PenEvent)event;
    lastX = pe.x;
    lastY = pe.y;
    }
  else if (event.type == PenEvent.PEN_DRAG)
    {
    PenEvent pe = (PenEvent)event;
    g.drawLine(lastX, lastY, pe.x, pe.y);
    lastX = pe.x;
    lastY = pe.y
    }
That's it! You can now scribble on the screen.

A simple feature we could add is a button to clear the screen. The following code adds a button to clear the screen: 

public class Scribble extends MainWindow
{
Graphics g;
int lastX, lastY;
Button clearB;

public Scribble()
  {
  g = new Graphics(this);

  clearB = new Button("Clear");
  clearB.setRect(0, this.height - 15, 40, 15);
  add(clearB);
  }

public void onEvent(Event event)
  {
  if (event.type == ControlEvent.PRESSED)
    {
    if (event.target == clearB)
      repaint();
    }
  else if (event.type == PenEvent.PEN_DOWN)
...
In this code, we simply call repaint() to clear and repaint the application window. This will repaint everything in the window including the clear button itself.

If we had a more complex user-interface, we might not want to redraw the whole window. It would be better to create a control for the user to draw in and then have the clear button just repaint that control.

The Scribble example that is part of the WabaSDK takes that approach. A custom "DrawArea" control is created that the user scribbles in and the clear button only repaints that control, not the entire application window.

If you run this program under PalmOS and Windows CE, you'll notice that the button looks different between the two. The Waba user-interface classes have a different look for black & white and color (or greyscale) screens.

Under PalmOS, the black & white look is used and under Windows CE, the color look is used.

When you're developing a program and running it under Java, it will display with the black & white look. To see what it looks like in color, you can specify a /color option on the "java" command line.

You can also specify a width and height with /w and /h to see how it would look under different window sizes: 

> java waba.applet.Applet /color /w 200 /h 300 Scribble
Final Thoughts

It's important to note that you can't use long or double datatypes, threads or exceptions or your Waba program will not run under a native WabaVM.

It's also important to note that Waba doesn't prevent you from writing programs that use up large amounts of memory or that run slowly. If you are writing programs for a small device, you still need to keep in mind the limits of the device.

It's best to create and use as few classes and objects as possible to save memory while still keeping the code simple and easy to read.

Think small and simple!

Copyright (c) 1999 - 2001 Wabasoft. Waba, WabaVM and WabaSDK are trademarks of Wabasoft Inc.