Before you jump to the conclusion that you think you understand the concept of "a key on the keyboard", let me suggest that it's a little more complicated than you would think, and that you should be wary of what you think you know.

To start, there are basically four different "things" that you have to worry about. First of all, there are the physical objects that you can stare at on your keyboard, let me call them "keycaps". Then there is the hardware associated with those keycaps, which is a bit vector indicating whether the switch underneath a keycap is depressed or not (down/up), we'll call each of these things a "bit position". Then there are the programmer names for the bit positions in the KeyName item of the TerminalDefs interface, which we'll call these "KeyName values", and finally there are the symbols which belong to the TIP vocabulary, which we'll call "TIP names".

Now lets throw in a few distractions; TerminalDefs includes some extra "constants" which can be used in place of Keyname values by programmers. This seems to be a dubious practice and should be discouraged, but is required for backward compatibility. It you happen do discover old code that uses constants, consider changing them to Keyname values instead.

The next distraction is that there are some "synonyms" added to the TIP vocabulary, also primarily for backward compatibility, but some seem to have been added for convienence. Currently, most of these convienence synonyms are not mapped to the keycaps you would think that they should be mapped to.

To confuse things even further, there are the "keyName ropes" which are available thru TIPPrivate.keyNames[KeyName] which contain names (in a derogatory sense) for the keys. Currently, these keyName ropes are not the same as the symbolic KeyName values, but are a mix of representations for values and constants. If you're interested, look in TIPTableBuilder.Mesa for the definition point of keyNames.

Now, to get to the nitty gritty, TIPTableBuilder.Mesa contains a procedure GetWord, which uses ATOMS (yes, ATOMS!) to identify whether tokens in tip tables refer to reserved words, or to names of keys (in the TIP name vocabulary sense). Currently there are problems with this mapping in that some synonyms which historically refered to constants now use the actual KeyName values instead (this isn't a new bug!), and you can discover obvious conflicts between interpretatons. For example, you might want to look at "Move", and "MOVE"

Luckily, all the problems seem to be constrained to keys which are unavailable on the Dorado keyboard (DLion keys?); so, unless you've done something special to your tip tables for DLions (or Daybreaks) none of this matters to you. Hopefully everything can get straightened out, but it is unlikely that the constants in TerminalDefs can be corrected (since it requires a major Cedar bounce/release), hence the suggestion that you avoid these. It should also be the case that the standard tip tables should use only TIP names corresponding to actual KeyName values. This could cause novice tip table hackers to get confused since the mapping between KeyName values and keycaps is not obvious, but judicious use of comments should help out here. Also documenting that mapping should help...

In order to get started, you need to create a TIP client. A user is expected to provide a procedure (a TIPNotifyProc) that TIP can call for recognised events. In your start code, you should call CreateClient, passing in your TIPNotifyProc. TIP will fork a process and begin looking for input events. You next need to give TIP a table from which to parse events. Most applications find the default table to be sufficient, but you can read the section on TIP Tables below in order to "roll your own". You can create your own TIPTable from its disk representation using InstantiateNewTIPTable, or simply pass NIL into InstantiateNewTIPTable. The "Compiled" versions of the TIP Table are stored in []<>TipC>*.tipC.

A Macro preprocessor has been added to the TIP language to improve its generality.

When TIP recognises an event, the TIPNotifyProc is called with the parameter 'results', which is a list of values collected from the TIP Table while parsing an event. The default table provides a REF CHAR for normal keys. In order to receive events from the keyboard you have to acquire first the "Input Focus" (see the InputFocus interface). If not you will only be notified for mouse events when the cursor is in your Viewer (Unless you use InputFocus.CaptureButtons).

For a detailed example, see [Cedar]<Cedar®>Tioga>Tioga.tip, and remember that you can always default the table by passing NIL to InstantiateTIPTable. In general, most people will want to use the default mechanisms.

A much simpler table can be found in [Cedar]<Cedar®>Viewers>MessageWindow.tip for instance.

Here is the BNF description for a valid TIP table: (terminals are the quoted symbols and the special characters besides the metasymbols ::= and | )

Blanks, tabs and CRs are allowed between symbols, comments are handled as in Mesa.

The meaning of the options is as follows:

DefaultKeys Adds all normal keyboard events
PrintKeys As above, but only printing keys (e.g. not 'Return' or mouse stuff)
Fast  Indicates to table builder that you favor lookup speed over storage
Small  Indicates you favor storage over lookup speed (default)

The whole match process is viewed as a SELECT statement, which is continuously executed reading key transitions, mouse movements, or key states from the input stream. A trigger statement has the effect of looking at the next action recorded in the input stream and branching to the appropriate choice. An enable statement implies selection between the different choices according to the 'current' state of the keyboard or the mouse keys. Trigger terms may appear in sequence, separated by AND. They might be mixed with enable terms which in turn are characterized by the keyword WHILE. A timeout following a trigger indicates a timing condition which has to hold between this trigger and its predecessor. The number associated with the timeout expresses a time intervall in msecs. An enable term consisting of a predicate identifier is interpreted by calling the 'TIPPredicate' with the same name, a boolean procedure registered in TIP by the user. Events starting with the same sequence of trigger and/or enable terms are expressed as nested statements. As result items you may specify names, numbers, strings, or the keywords Char or Coords. The results of a successfully parsed event are passed to the user as a LIST OF REF ANY. Where names appear as atoms, numbers as REF INT, and strings as REF TEXT. Char comes as a REF CHAR pointing to the ASCII interpretation of the key involved with the event, Coords results in a 'TIPScreenCoords' which is a REF to the RECORD [x, y: REAL]; x and y containing the mouse coordinates of the event.

For example, the DefaultKeys entry for the letter "A" might be represented as:

This event will be triggered when the A key goes down, only if the Ctrl key is up and will pass a REF to the character A as a result.

A more elaborate example may look like this:

This table produces the result NormalDoubleClick along with the mouse coordinates if the red mouse button goes down, remains there not longer than 200 ms, and goes down again before another 200 ms elapse.
The result will be ShiftedDoubleClick if the same actions occur but also the left shift key is down.
If less than 300 ms after the initial 'Red Down' the blue mouse button also goes down then we get the result RedAndBlue.
And finaly the table specifies the result SimpleClick (with coordinates) for the case of red going down but none of the above described succeeding actions occuring.

The macro package used in TIP is based on the "General Purpose Macrogenerator" described by Strachey in the October 1965 Computer Journal. The following summary is based on that article; see the real thing for more details.

A macro-call consists of a macro-name and a list of actual parameters, each separated by a comma. The name is preceded by a left square bracket ([) and the last parameter is followed by a right square bracket. A macro is defined by the special macro DEF which takes two arguments: the name of the macro to be defined and the defining string. The defining string may contain the special symbols ~1, ~2, etc., which stand for the first, second, etc., formal parameters. Enclosing any string in parentheses has the effect of preventing evaluation of any macro-calls inside; in place of evaluation, one "layer" of string quotes is removed. It is usual to enclose the defining string of a macro definition in string quotes in order to prevent any macro-calls or uses of formal parameters from being effective during the process of definition. The symbol  acts as a single character string quote (to enter this, type "d", then hit MakeControlCharacter). Use it in front of special macrogenerator characters in string literals. For example, if you want to insert "(", you need to write "(" to keep the macro scanner from treating the paren as a start of string quote.

Note that there are no names for shifted characters like left or right paren. Instead you must specify SHIFT plus the unshifted key name e.g.