Here's a listing building on our hello word earlier:

To run this program, create the memo, then go into Quartus Forth and write "include helloworld." If you get an ok, then write "go". The screen should clear and "Hello World" should appear.

The "go" word definition consists of MainForm, a word which reloads a blank form, effectively clearing the screen. Next, it includes "hello", our Hello World printer routine we wrote earlier. Finally, the "go" definition includes a loop which reads events from the queue and simply drops the value from the stack (i.e., it does nothing but sit there).

As the state of the stack is so important, most words include a stack diagram which shows what's taken off the stack and anything that's put on, in the form ( off -- on ). The left bracket is a comment word terminated with the right bracket -- remember to leave a space. In a lot of cases you'll find no comments to a word, just the diagram, so it's worth getting used to reading them. As an example, here's the stack diagram for the DmCloseDatabase OS call:

The above line shows the call expects a double cell (i.e., a 32-bit pointer value, as input and leaves a numeric error flag as output). If you've installed Quartus Forth, you'll find the rest of the Palm OS calls and a key to the types in stackdia.txt file in the docs directory.

Handling the event loop
In our original program, we simply dropped any events we were sent. Events are things that happen on the Palm device, like a screen tap, while the programming is running. Now we'll do something with them. This time we'll pick up the penDown event and print our message at that location. For this we need some more words:

• The event names so we know to enter penDownEvent. These come from the Events collection;

• The current co-ordinates of the pen. This is in Events, too, as the word coords@ ( -- y x);

• A word to move the print position for the 's' word to the pen position. This needs the at ( y x --) word in the graphics collection.

Adding these pieces gives the following listing:

The "needs" word means the program uses the words from the library referenced. It's like #include in C. But what's all this "dup ... = if" stuff?

Let's take it one step at a time:

• ekey puts an event on the stack;

• handler needs to test it to see if the event is a key, but testing it will consume the event, so we need another copy, hence dup;