DEFINITION MODULE GKSInput;

(*
    Title: 	interface to input tools
    LastEdit:	"Tue Feb 26 15:47:21 1985"
    Author: 	pr
		Cambridge University Computer Laboratory
*)


FROM Context IMPORT Context;

FROM Vector IMPORT RVEC;

FROM GKSTypes IMPORT WS;


EXPORT QUALIFIED 
    BindCursorInput, BindCursorKeys,
    CursorInput, CursorGrid, CursorOutput, 
    SetCursor, GetCursor;


(*  Graphical input is handled using the Modula-2 command dispatcher.
    This allows command strings to be bound to procedures in two modes -
    delayed and immediate.  Immediate commands can be given in the middle
    of typing a delayed command and are not reflected;  they are used here
    to handle cursor position information volunteered by the workstation.
    It is necessary to enable cursor input in every immediate context
    being used (or to use the same one all the time).
    
    There are two available methods for obtaining graphical input from a
    workstation. The first uses CursorInput, and depends on the workstation
    being able to volunteer cursor positions in screen coordinates at 
    appropriate times. If this procedure returns TRUE for enable=TRUE, then
    the workstation is able and willing to do this.
    
    The second method simulates the above for workstations which will not
    volunteer the position of a graphics cursor, and uses the workstation's
    cursor movement keys (as defined by its termcap entry) to cause movements
    of a cursor over a grid on the screen. Pressing "cursor left", for 
    instance, will cause the visible cursor to jump one grid position to the
    left. The grid is user-defined in world coordinates using procedures in
    this interface, and can be redefined at any time.
*)

PROCEDURE BindCursorInput (ws: WS; immediate: Context; enabled: BOOLEAN): 
        BOOLEAN;
(*  If enabled binds suitable strings into the given immediate context to 
    handle cursor information from the given workstation and returns true,
    otherwise unbinds the strings.
    If the workstation does not have a free moving cursor, returns false. *)

PROCEDURE BindCursorKeys (ws: WS; immediate: Context; enabled: BOOLEAN): 
        BOOLEAN;
(*  If the previous routine returns false, then you could try using this.
    A cursor is simulated in response to cursor keys on the keyboard -
    if this can't be done then you will just have to think up which keys
    you would like to be considered as cursor keys (control-H, J, K & L
    spring to mind, but Z, X, : & / could be used!) and edit them into
    the termcap file so that they are found.				  *)

PROCEDURE CursorGrid (ws: WS; steps: RVEC);
(*  Used in conjunction with cursor keys, set the amount in world coordinates
    by which the cursor will move in response to each cursor key.	  *)

PROCEDURE CursorInput (ws: WS; enabled: BOOLEAN);
(*  enables and disables input on the particular workstation		  *)

PROCEDURE CursorOutput (ws: WS; enabled: BOOLEAN);
(*  turn the visible cursor on and off					  *)

(* The following two procedures use the current normalization transformation
   and the current workstation transformation to translate between the
   workstation's cursor position in screen coordinates and the world
   coordinate positions visible to the user
*)

PROCEDURE SetCursor (ws: WS; at: RVEC);
(*  set the position used for both input and output in world coordinates  *)

PROCEDURE GetCursor (ws: WS; VAR position: RVEC);
(*  return the cursor position in world coordinates                       *)


END GKSInput.
