**** sections between {** and **} not yet implemented !! ****

Abstract:

TIP is a package built on top of Dan Swinehart's Inscript software that parses hardware-level actions from the keyboard, mouse, and keyset, into higher-level user actions.  The input to TIP is a Mesa-like program (called here a TIP table) describing the parsing algorithm. i.e. the set of events to be recognised, and the output to be passed through a client supplied procedure, which is called once per event parsed.  TIP runs as a separate process from the client and is reentrant, allowing several instances to run at once.  There are public interfaces to create a new TIP client and to change the parse table by which TIP recognises events.  TIP is used by CedarDocs, and potential users should be aware of the InputFocus interface that allows input events to arbitrarily directed to a single Cedar document.

Basic Overview:

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.

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 CHARACTER for normal keys, {**and the atom $Red, $Yellow, or $Blue for mouse clicks.  In addition, a REF RECORD [x, y: REAL] is passed along with the mouse click information that gives the screen coordinates of the mouse. {The atom $Abort is passed if the user types CONTROL DEL.**}

TIP Tables:

For a detailed example, see [IVY]<McGregor>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.

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

TIPTable ::= Options TriggerStmt .

Options ::= empty | "OPTIONS" OptionList ;
OptionList ::= SmallOrFast | SmallOrFast , PrintOrDefaultKeys | PrintOrDefaultKeys
SmallOrFast ::= "Small" | "Fast"
PrintOrDefaultKeys ::= "PrintKeys" | "DefaultKeys"

TriggerStmt ::= "SELECT" "TRIGGER" "FROM" TriggerChoiceSeries
EnableStmt  ::= "SELECT" "ENABLE" "FROM" EnableChoiceSeries

TriggerChoiceSeries ::= TriggerChoice ; TriggerChoiceSeries
                      | TriggerChoice "ENDCASE" FinalChoice
EnableChoiceSeries  ::= EnableChoice ; EnableChoiceSeries
                      | EnableChoice "ENDCASE" FinalChoice

TriggerChoice ::= TriggerTerm Expression
EnableChoice  ::= EnableTerm Expression
		  
TriggerTerm ::= Key TimeOut | "Mouse" TimeOut
EnableTerm  ::= Key | PredicateIdent

Key     ::= KeyIdent "Up" | KeyIdent "Down"
TimeOut ::= "BEFORE" Number | "AFTER" Number

Expression ::= "AND" TriggerChoice | "WHILE" EnableChoice
	     | => Statement
Results    ::= ResultItem | ResultItem , Results
	     | ResultItem Expression
ResultItem ::= "Coords" | "Char" | String | Number | ResultIdent
	     
FinalChoice ::= empty | => Statement
Statement   ::= TriggerStmt | EnableStmt | Results


Blanks, tabs and CRs are allowed between symbols, comments are handled as in Mesa. There are syntax diagrams available from [IVY]<McGregor>TIP>TIPsyntax.press reflecting the above.


The meaning of the options is as follows:

DefaultKeys	-	Adds all normal keyboard events {**, plus red, blue, and yellow down **}
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 LONG INTEGER, and strings as REF TEXT. Char comes as a REF CHARACTER 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:

SELECT TRIGGER FROM 
  A Down WHILE Ctrl Up => Char;
  ...

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:

SELECT TRIGGER FROM 
  Red Down =>
    SELECT TRIGGER FROM 
      Red Up BEFORE 200 AND Red Down BEFORE 200 =>
        SELECT ENABLE FROM
	  LeftShift Down => Coords, ShiftedDoubleClick
	  ENDCASE        => Coords, NormalDoubleClick;
      Blue Down BEFORE 300 => RedAndBlue
      ENDCASE => Coords, SimpleClick;
  ...

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.