(*
 * The IdrawInterface module supplies procedures for all of the user-level
 * operations available in the graphics tools palette and pull-down menu
 * commands.  The names of the proedures are derived directly from the
 * user-level command names, per the conventions described below.  There are a
 * few specialized procedures, such as SelectMultiple, where the user signals
 * the command on the screen via a specialized mouse action rather than by
 * selecting a specific panel item or pulldown menu item.
 *
 * The precise conventions for procedure naming are as follows:
 *
 *    (1) For the graphic editing tools (Select through Magnify), the
 *        procedures have exactly the same names as appear in the tools
 *        palette.  E.g., procedure Move performs the function of the 'Move'
 *	    item in the editing tools.
 *
 *    (2) For the graphics drawing tools (Text through Spline), the
 *        procedures have names of the form DrawXXX, where XXX is the
 *        mnemonic name of the graphic.  E.g., procedure DrawLine performs
 *	    ths function of the 'Line' item in the editing tools.

 *    (3) For the pull-down menu commands, the procedures are divided into
 *	    two categories: (a) those with menu items containing command names
 *	    and (b) those with menu items containing pattern or color icons.
 *	    For category (a), the procedure names are of the form "MMMIII",
 *	    where "MMM" is the name of the menu and "III" the name of an item
 *	    in that menu.  For example, FileOpen is the procedure that performs
 *	    the Open command in the File menu; AlignCenters is the procedure
 *	    for the Centers item in the Align menu.  For category (b), the
 *	    procedure names are of the form "SelectMMM", where "MMM" is the
 *	    name of the menu.  For example, SelectBrush is the procedure that
 *	    performs the function of the Brush selection menu.  As described
 *	    below, each of these Select procedures takes an integer parameter
 *	    between 1 and the number of items in the menu.
 *
 * [DESCRIBE SIGNATURE CONVENTIONS]
 *
 *)
module IdrawInterface;

    (*
     * GestureType enumerates the specific type of gestures the user may make
     * on a canvas.
     *)
    obj GestureType =
	LeftUpGesture |		(* Left mouse button up. *)
	LeftDownGesture |	(* Left mouse button down. *)
	MiddleUpGesture |	(* Middle mouse button up. *)
	MiddleDownGesture |	(* Middle mouse button down. *)
	RightUpGesture |	(* Right mouse button up. *)
	RightDownGesture |	(* Right mouse button down. *)
	EnterGesture |		(* Mouse enters a graphic. *)
	LeaveGesture |		(* Mouse leaves a graphic. *)
	MoveGesture |		(* The mouse moves on the canvas. *)
	KeyGesture;		(* A key on the keyboard is pressed. *)

    obj LeftUpGesture;
    obj LeftDownGesture;
    obj MiddleUpGesture;
    obj MiddleDownGesture;
    obj RightUpGesture;
    obj RightDownGesture;
    obj EnterGesture;
    obj LeaveGesture;
    obj MoveGesture;
    obj KeyGesture;

    (*
     * A Gesture is a record that corresponds to one of the entries in the
     * sensitize edit window.  Hence, a Gesture record contains a boolean flag
     * the corresponds to the on/off check box foreach gesture, and string that
     * records the interface procedure name for a gesture.
     *)
    obj Gesture =
	onoff: boolean,
	procname: string;

    (*
     * A GestureMap is an array of Gesture records, one for each type of
     * gesture.  Hence, a GestureMap is the datum that corresponds to the full
     * sensitize edit window.
     *)
    obj GestureMap = Gesture*;


    (*
     * Graphic is the opaque type for the graphical item drawn on a canvas.
     *)
    obj Graphic;



    (*
     * SelectionInfo is an enumeration of informational flags for different
     * types of selections.
     *)
    obj SelectionInfo =
	BeingTextEdited  (* On if in a text-edit loop for a given selection *)
    ;

    obj BeingTextEdited = boolean;

    (*
     * Selection is the data structure that corresponds an item on a canvas.
     *)
    obj Selection =
	graphic: Graphic,    (* Physical screen rendering of the selection. *)
	stype: string,	     (* General type of selection. *)
	map: GestureMapPtr,  (* Sensitive gestures and corresponding procs *)
	flags: SelectionInfo*;
			     (* Type-specific informational flags *)

    obj GestureMapPtr;

    op GetType(s: Selection) -> string;
    op SetType(s: Selection, stype: string);
    op GetMap(s: Selection) -> GestureMap;
    op SetMap(s: Selection, gm: GestureMap);

    obj Side =  TOP | BOTTOM | LEFT | RIGHT;
    obj TOP;
    obj BOTTOM;
    obj LEFT;
    obj RIGHT;

    op Select(s: Selection);
    op SelectMultiple(sl: Selection*);
    op Unselect(s: Selection);
    op UnselectMultiple(sl: Selection*);
    op Move(l: integer, b: integer);
    op MoveSelection(s:Selection, l: integer, b: integer);
    op Scale(factor: real);
    op ScaleSelection(s:Selection, factor: real);
    op Stretch(side: Side, amount: real);
    op StretchSelection(s:Selection, side: Side, amount: real);
    op Rotate(degrees: integer);
    op RotateSelection(s:Selection, degrees: integer);
    op Reshape(x0: integer, y0: integer, x1: integer, y1: integer);
    op ReshapeSelection(s:Selection, x0: integer, y0: integer, x1: integer, y1: integer);
    op Magnify(x0: integer, y0: integer, x1: integer, y1: integer);
    op MagnifySelection(s:Selection, x0: integer, y0: integer, x1: integer, y1: integer);
    op DrawText(l: integer, b: integer, text: string) -> Selection;
    op DrawLine(x0: integer, y0: integer, x1: integer, y1: integer) -> Selection;
    op DrawMultiLine(x0: integer*, y0: integer*, x1: integer*, y1: integer*) -> Selection;
    op DrawOpenSpline(x0: integer*, y0: integer*, x1: integer*, y1: integer*) -> Selection;
    op DrawEllipse(cx: integer, cy: integer, xr: integer, yr: integer) -> Selection;
    op DrawRect(l: integer, b: integer, r: integer, t: integer) -> Selection;
    op DrawPolygon(x0: integer*, y0: integer*, x1: integer*, y1: integer*) -> Selection;
    op DrawClosedSpline(x0: integer*, y0: integer*, x1: integer*, y1: integer*) -> Selection;

    op TextInsert(text: string);
    op TextSelect(starpos: integer, endpos: integer);
    op TextDelete();
    op TextForwardChar();
    op TextBackwardChar();
    op TextNextLine();
    op TextPreviousLine();
    op TextBeginningOfLine();
    op TextEndOfLine();
    op TextBeginningOfText();
    op TextEndOfText();
    op TextPutCursor(charpos: integer);

    op FileNew(width: integer, height: integer, x: integer, y: integer);
    op FileRevert();
    op FileOpen(filename: string);
    op FileOpenScript(filename: string);
    op FileSave();
    op FileSaveAs(filenname: string);
    op FileSaveAll();
    op FileSelectCanvas(canvasnum: integer);
    op FileRaiseCanvas(canvasnum: integer);
    op FileLowerCanvas(canvasnum: integer);
    op FileMoveCanvas(x: integer, y: integer);
    op FileResizeCanvas(width: integer, height: integer, x: integer, y: integer);
    op FileShowHideCanvas(canvasnum: integer, show: boolean);
    op FileShowHideMenus(show: boolean);
    op FileShowHideTools(show: boolean);
    op FilePrint(command: string);
    op FileQuit();

    op EditUndo();
    op EditRedo();
    op EditCut();
    op EditCopy();
    op EditPaste();
    op EditDuplicate();
    op EditDelete();
    op EditSelectAll();
    op EditUnselectAll();
    op EditShow(objt: Selection);
    op EditHide();
    op ShowAll();	(* Groups them, so they can be rehidden. *)
    op EditFlipHorizontal();
    op EditFlipVertical();
    op Edit90Clockwise();
    op Edit90CounterClockwise();
    op EditPreciseMove(x: integer, y: integer);
    op EditPreciseScale(factor: real);
    op EditPreciseRotate(degrees: integer);
    op EditInterpret(command: string);

    op StructureGroup() -> Selection;
    op StructureUngroup() -> Selection;
    op StructureBringToFront();
    op StructureSendToBack();
    op StructureNumberOfGraphics() -> integer;

    op FontSelect(fontnumber: integer);

    op BrushSelect(brushnumber: integer);

    op PatternSelect(patternnumber: integer);

    op FgColorSelect(colornnumber: integer);

    op BgColorSelect(colornnumber: integer);

    op AlignLeftSides();
    op AlignRightSides();
    op AlignBottoms();
    op AlignTops();
    op AlignVertCenters();
    op AlignHorizCenters();
    op AlignCenters();
    op AlignLeftToRight();
    op AlignRightToLeft();
    op AlignBottomToTop();
    op AlignTopToBottom();
    op AlignToGrid();

    op OptionReduce();
    op OptionEnlarge();
    op OptionNormalSize();
    op OptionReduceToFit();
    op OptionShrinkWrap();
    op OptionCenterPage();
    op OptionRedrawPage();
    op OptionGriddingOnOff(on: boolean);
    op OptionGridVisibleInvisible(visible: boolean);
    op OptionGridSpacing(gridsize: integer);
    op OptionOrientation();
    op OptionNameObject(name: string);
    op OptionFindObject(name: string) -> Selection;
    op OptionShowObjectName(objt: Selection) -> string;
    op OptionPrintWinNum() -> integer;
    op OptionShowVersion() -> string;


    (*
     * Event is the record of single interactive event occurring on a canvas.
     *)
    obj Event =
	target: Selection,	 (* selection on which event occurred *)
	timestamp: integer,	 (* a relative time *)
	gesture: GestureType,	 (* type of gesture (see above) *)
	x: integer, y: integer,	 (* mouse position relative to full canvas *)
	controlkey: boolean,     (* true if control key down *)
	metakey: boolean,	 (* true if meta (diamond) key down *)
	shiftkey: boolean,	 (* true if shift key down *)
	shiftlock: boolean,	 (* true if shift-lock on *)
	len: integer,		 (* length of ASCII string *)
	keystring: string;       (* ASCII interpretation of event, if any *)


    (*
     * Procedure ReadEvent gets the next available event.  An event queue is
     * maintained internally by the system, storing all user-driven events.  A
     * program can gain control over event processing using an event read loop
     * of the form:
     *
     *		var e: Event;
     *
     *		set e = ReadEvent();
     *		while EventIsOfInterest(e) do
     *		    ProcessEvent(e);
     *		    set e = ReadEvent();
     *		end;
     *		UnreadEvent(e);
     *
     * where EventIsOfInterest is some boolean function that checks event
     * properties to determine if it is of interest, and ProcessEvent is a
     * op to perform appropriate even processing.  For example, the
     * following ... FINISH
     *)
    op ReadEvent() -> Event;

    (*
     * UnReadEvent puts an event back on the event queue.  It is typically used
     * to restore a read event that was not of interest.
     *)
    op UnreadEvent(e: Event);

    (*
     * GetLastEvent gets the most recently read event (i.e., the last event
     * taken off the event queue).  GetLastEvent is particularly useful in an
     * interface op that wants to know the particular event that lead to
     * its invocation.
     *)
    op GetLastEvent() -> Event;


    (*
     * Type InterfaceProc is the type for all ops that are mapped to a
     * user-performed gesture.
     *)
    obj InterfaceProc =  op(e: Event);


    (*
     * The next three ops a conveniences to set fields of a gesture.
     * Hence, Gesture may be treated as an opaque type if desired.
     *)
    op SetMapping(gm: GestureMap, gt: GestureType, ip: InterfaceProc);
    op EnableGesture(gm: GestureMap, gt: GestureType);
    op DisableGesture(gm: GestureMap, gt: GestureType);

end IdrawInterface;