Easy Application DORs with CamelForth

A set of tools is now available for Z88 CamelForth that make creating DORs for applications and popdowns extremely quick and easy. They are suitable for making DORs for applications generated with any language, not just CamelForth, and you don't need any knowledge of the Forth language to use them.

Once in CamelForth, load the source file with S" appgen.fth" INCLUDED. You are now ready to use the tools, either by typing in a DOR definition interactively, or by loading a source file containing a prepared DOR definition

DOR Basics

The main constituents of application DORs are menus (known as topics), commands and help. In addition, you will need to specify an application name and key, as well as a few optional settings.

The start of a DOR definition defines the application name and key, in the following manner:

     CHAR E  APPLICATION[ Example]

This shows several important things about the way we define DORs:

As long as you follow these rules, you should have no problems designing your DORs.

One additional thing to note is that you can use either square brackets or curly brackets to enclose your text (this lets you include brackets of the other type within the text if you wish). For example, we could have written the start of our definition as:

     CHAR E  APPLICATION{ Example}

Throughout this discussion, I will always use square brackets, but don't forget that curly brackets can be used at any time instead.

We have now created the very simplest DOR possible, but most DORs need topics, commands and help text as well.

Topics and commands

In Z88 menus, commands are grouped together into up to eight topics, which are cycled through when pressing the MENU key. Defining commands and grouping them into topics is easy. Here's an example:

     TOPIC[ Commands]
       SEQ[ Q]  128  COMMAND[ Quit]
       SEQ[ C]  129  COMMAND[ Cold]
     TOPIC[ Options]
       SEQ[ OE] 131  COMMAND[ Escape ON]
       SEQ[ OO] 132  COMMAND[ Escape OFF]

In this example, we have defined two topics, each containing two commands. In the command definitions, we first write the key sequence that activates the command (for example, <>OE will be used to activate the "Escape OFF" command). Next is a value representing the command code; this is passed to the application when the command is selected. Finally, we have the command name itself.

Special key sequences

Commands that use conventional diamond key sequences, such as <>BSE can be written using SEQ[ ], but it is also possible to assign command codes to keys such as TAB and the cursor keys. These are given special sequence codes, written as follows:

     IN_LFT  145 COMMAND[ Cursor Left]

which defines the left cursor key to command code 145.

You can use the following link to download a text file containing the full list of special command sequences.

Special menu features

The Z88 provides several special features that can be used with topics and commands. With the DOR-creation tools, these are written as a word directly following the topic or command name to be affected. They are:

Used to describe topics as (for example) "An Edit Topic" instead of "A Edit Topic", which would be the default.
Used to specify an info topic (see later section for more details).
Stops a command from being selected by pressing ENTER on the menu screen (instead a beep will sound). For example, <>PURGE in the Index is defined as a safe command.
Prevents a command from being displayed in the menu altogether. It can still be activated with its defined key sequence, however.
Forces this command to start a new column in the menu listing. This is automatically done if the previous column is full.

For example, to make a command safe, we would write this:

     SEQ[ DIE] 150  COMMAND[ Terminate]  SAFE

Help text

An important feature of the Z88's application system is the online help facility. You can add help text pages to any command or topic, or to the application itself (usually used for copyright and version information).

Lines of help text are written as HELP[ text]; this includes the text and a newline code. You can enter a blank line with the word N/L.

Additionally, you can include text only (without starting a new line) with HELP-TEXT[ text], and single characters with code HELP-CHAR. This enables you to include special characters that can't be entered from the keyboard.

Help pages are added to a topic, command or the application itself simply by listing the help text after the item you wish to attach it to. For example, the following provides help for a topic and its commands:

     TOPIC[ Commands]
       HELP[ This is the help text for the commands topic]
       SEQ[ B] 140 COMMAND[ Bell]
         HELP[ This is the help for the bell command]
         HELP-TEXT[ Use this command to sound a ]
         1 HELP-CHAR  33 HELP-CHAR  N/L
         HELP[ (Obvious, innit!)]
       SEQ[ Q] 141 COMMAND[ Quit]
         HELP[ I'm sure you can work this one out!]

Info Topics

Info topics are a special kind of topic that provide only help, but no actual commands. An info topic must be the first topic listed, or the Z88 will ignore it.

These topics contain no COMMAND[ ] entries; instead there are simpler INFO[ ] entries. Here's an example:

     TOPIC[ Stuff] INFO
       INFO[ Some Stuff]
         HELP[ This is some information about some stuff]
       INFO[ More Stuff]
         HELP[ This is some information about some more stuff]


There are several settings that you can change to alter the behaviour of your application. These take their defaults from CamelForth, so unless you are creating a DOR for a different language, you will probably not need to change many of them. It is best to set them before beginning a DOR definition.

A setting is changed with a phrase like value TO setting-name. The settings available are:

If your application is bad, this is the amount of RAM required, and should be set to 0 (default size) or a number from 32 to 160, representing the number of 256-byte pages required. To make things easier, you can just write the number of bytes required followed by the word BYTES, which will do the conversion for you (for example, 12000 BYTES TO RAM-SIZE). This is the most important setting to make for CamelForth applications.
You should set this to a unique 16-bit value for the card you are creating. It is only relevant for creation of CamelForth application cards.
This represents the type of your application. You should add together the required combination from GOOD, BAD, UGLY, POPDOWN, SINGLE (only a single instantiation allowed) and SCREEN (preserve screen on pre-emption). For example, UGLY POPDOWN + TO APPTYPE defines an ugly popdown.
This is the setting of caps-lock on entry to your application, and can be set to CAPS-OFF, CAPS-ON or CAPS-INV
This is the most important setting, and is the address in memory where you are going to place the DOR in your application. It is set automatically for CamelForth applications.
The number of the bank that the DOR will be loaded to. It is set automatically for CamelForth applications.
These are the amounts of safe and unsafe workspace your application requires (in bytes). CamelForth applications do not usually use these.
This is the entry address for your application, and is set automatically for CamelForth applications.
SEG0, SEG1, SEG2 and SEG3
These are the initial bank bindings required for your application for each memory segment. They are set automatically for CamelForth applications.

Using the tools

Once you have written your source file containing the DOR, load the tools into CamelForth with S" appgen.fth" INCLUDED, and then load your source file with S" yourapp.dor" INCLUDED. Your DOR has now been created!

You can now save it as a binary file, with the phrase:

    S" yourdor.bin" SAVE-DOR

After saving, the load address and size of the DOR will be confirmed, together with the bank it has been configured for, and the actual start address of the DOR; it is this start address that you need to place in the ROM front DOR at the top of your application's bank 63.

When creating CamelForth applications, there is no need to use SAVE-DOR; instead, the DOR is automatically installed into the correct position in the application. For full details of how to do this, see the example application tutorial.

Here is a full example source file, which could be used to replace the standard DOR in CamelForth. It includes full comments, and examples of everything you're likely to need in creating DORs:

Example DOR source file

Future enhancements

At the moment, there is no support for tokenisation, so the DORs created are not quite as compact as they could be (although other tricks are used to ensure no bytes are wasted in the actual topic and command definitions). These may be added at some point in the future.

More on CamelForth

Other ROMs

Back to the Z88 home page