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
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.
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.
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.
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:
For example, to make a command safe, we would write this:
SEQ[ DIE] 150 COMMAND[ Terminate] SAFE
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]
N/L
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 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:
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:
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.