Template directives are special escape sequences resembling terminal directives. They are, of course, not handled by any terminal in existence. Within the BBS, they are interpreted only where data entry templates are specified, i.e. only the dialog_run() function.Although the same directives work on both visual dialogue boxes and conventional menu-driven data entry, they perform differently in either case. The following list will describe each behaviour.
All directives start with the sequence `ESC @', or ASCII codes 27 64 (in decimal). Directives need one or more arguments, depending on their type. Arguments may be of two types:
- int
- Denotes an integer argument.
- str
- Denotes a string argument, enclosed in double quotes.
All arguments are separated with semicolons. The directive is terminated by a single character which identifies the type of directive. The following types of directives are currently available, listed here with their expected argument types (spaces aren't included for clarity, and are not to be used in the directives):
- ESC int ; int ; int s
- Specifies a string input field. The first argument is the maximum allowed length of the string. The second argument is the maximum length of the screen that will be visible, that is the physical length of the input field. The third argument represents a set of flags (ORred together), as follows:
- 0
- Normal operation.
- 1
- Characters are converted to upper case.
- 2
- Password: asterisks are echoed.
- 4
- Date input: formatted as a DD/MM/YY-style date.
In full-screen mode, this directive inserts an input field at the current position of the cursor, and the current character attributes (colour et cetera). The length is that of the second argument plus 2 (the field is space-padded on either side). Once the field is active, it interprets editing commands such as the arrow keys, backspace, delete, et cetera. Characters are inserted properly, and, if the string is longer than its visible part, the field scrolls to accommodate it. If the string extends past the left edge of the field, a less-than sign (<) is displayed at the left padding space. Likewise, the right padding space will display a greater-than (>) if the string extends past the right edge of the field.
In menu-driven mode, this directive simply prints the string, date, or whatever. The string is padded to the length specified by the second argument, but is not space-padded (little use for the scrolling arrows here). If the string is longer than the length of the field, the beginning of the string is displayed. An ellipsis (...) is displayed at the rightmost three characters of the field to denote that the entire string could not fit on-screen.
Here are a few examples:
- ESC@80;40;s specifies a string field holding up to 80 characters, of which up to 40 will be visible. The field occupies 42 characters in visual mode, and 40 in text mode.
- ESC@40;40;1s A non-scrolling, string field that automatically converts characters to upper case.
- ESC@8;8;2s A non-scrolling, password entry field. Any characters typed will echo as asterisks.
- ESC int ; int ; int ; int n
- Specifies a number input field. The first argument is the maximum allowed length of the number. The second and arguments hold the minimum and maximum values the number is allowed to have. Invalid values cause the number to be changed to the nearest valid number. The fourth argument is, as usual, a set of flags (ORred together), as follows:
- 0
- Normal number.
- 1
- Right-flush number when displaying. The default is to left-flush it.
In full-screen mode, this directive works just like a string field (see the above documentation for details), but it automatically validates its input. Only digits may be typed inside a field (other characters are ignored). Leaving the field with a number off-limits will cause the number to change to the nearest valid integer.
In menu-driven mode, this directive behaves exactly like a string field. The number limits are imposed when entering the number. The user will keep getting the question (along with the valid range of numbers) until they respect the limits.
- ESC int ; str l
- Specifies a list of values, a multiple choice selection. The first argument defines the visible length of this field. The second argument is a string containing the possible choices. The string is enclosed in double quotes and choices are delimited with pipes (|).
In full-screen mode, this directive uses the specified space to print as much of one of the choices as will fit. The arrow keys, the space bar and other keys change the active option.
In menu-driven mode, the user is presented with a submenu of the choices specified in the second argument.
Here are a few examples:
- ESC@5;"Yes|No|Maybe"l denotes a multiple-choice list providing three obvious options. All options are padded to 5 characters, except `Maybe', which is already 5 characters long.
- ESC@5;"Yessirree|Nope, thank you|Maybe"l chops off excess characters, transforming the visible choices to `Yessi', `Nope,', and leaving `Maybe' as it is.
- ESC str t
- Specifies a toggle field, holding a boolean value. The first and only argument is a two-character string (any less cause undefined behaviour, any more are ignored), denoting the two characters used to display the off/on states of the toggle (or yes/no, or true/false, or whatever else you use it for). The first character is the off/no/false state, the second is on/yes/true.
In full-screen mode, this directive uses a single character to display the state of the toggle field. Space or the arrow keys toggle the value.
In menu-driven mode, the system prints the corresponding character where the field is specified.
Here's a simple example:
- [ESC@" X"t] Specifies a toggle drawn inside a pair of brackets. The toggle displays a space for the off state, rendering into [ ]. The on state is [X]. This is the style I personally prefer, because it looks a bit like Borland's Turbovision (which I was programming on before I got into Megistos --- the are definite influences in the default visual design of the dialog boxes).
- ESC int ; str b
- Specifies a button. Buttons terminate the data entry session. All dialog boxes have at least two buttons, whether you define them or not: OK and Cancel. These are associated with hot-keys in full-screen mode, and with the OK and X commands in menu-driven mode. The first argument of the directive specifies the width of the button in characters. The second is the button label.
In full-screen mode, labels are centred within the available space. Focusing or `going into' the button draws greater-than and less-than signs as arrows to point to the label. The makeshift arrows are drawn at the edges of the button's area, so always specify at least two characters more than the width of the label.
In menu-driven mode, there is no visual component for this control. However, the user may select it by number, exiting the current dialogue.
Here's a simple example:
- ESC@8;"OK"b Specifies an `OK' button, centred in an 8-character space. Focusing will put makeshift arrows in the first and eighth position, effectively decreasing the padding.