(*
 * The GuiBuilderInterface module supplies operations for all user-level   
 * operations available in the tools palette and pull-down menus of a     
 * GuiBuilderInterface-based drawing editor.  These operations can be used in     
 * scripts that programmatically manipulate GuiBuilderInterface screens.  For 
 * the most part, the names of operations are derived directly from user-level 
 * command names.  The specific naming conventions are as follows:
 *
 *      (1) For the graphic editing tools (Select through Magnify), there are
 *          operations that have exactly the same names as appear in the tools
 *          palette.  E.g., operation Move performs the function of the 'Move'
 *          item in the editing tools.
 *
 *      (2) For the graphics drawing tools (Text through Spline), the
 *          operations have names of the form DrawXXX, where XXX is the
 *          mnemonic name of the graphic.  E.g., operation DrawLine performs
 *          the function of the 'line' item in the editing tools.
 *
 *      (3) For the pull-down menu commands, the operations 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 operation 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 operation that performs
 *          the Open command in the File menu; AlignCenters is the operation
 *          for the Centers item in the Align menu.  For category (b), the
 *          operation names are of the form "MMMSelect", where "MMM" is the
 *          name of the menu.  For example, BrushSelect is the operation that
 *          performs the function of the Brush selection menu.  Each of these
 *          Select operations takes an integer parameter between 0 and the one
 *          less than number of items in the menu.  For example, SelectFont(3)
 *          select the fourth font listed in the Font menu.
 *
 *      (4) There are some additional specialized operations that are useful
 *          for advanced script development.  Further comments on these
 *          operations are given below.
 *     
 *      (5) For all sub-menu items without operation definitions, refer to Top  
 *		Level specification for descriptions.
 *)
module GuiBuilderInterface;

  from TopLevel import CurrentPhase;
  from ToolEnvir import Canvas;
  from Sbd import Sensitize, Run;
  export Selection, SelectionList, GestureMap, Gesture, GestureName;

  (*
   * Before the operation definitions are some data types that are used by
   * the operations.
   *)


  (*
   * GestureType enumerates the specific type of gestures the user may make
   * on a canvas.  These are the same gesture types that appear in the
   * sensitize edit window (i.e, the window that appears when the 'Sensitize'
   * item is selected in the tools palette).
   *)
  object GestureType is
    LeftUpGesture or        (* Left mouse button up. *)
    LeftDownGesture or      (* Left mouse button down. *)
    MiddleUpGesture or      (* Middle mouse button up. *)
    MiddleDownGesture or    (* Middle mouse button down. *)
    RightUpGesture or       (* Right mouse button up. *)
    RightDownGesture or     (* Right mouse button down. *)
    EnterGesture or         (* Mouse enters a graphic. *)
    LeaveGesture or         (* Mouse leaves a graphic. *)
    MoveGesture or          (* The mouse moves on the canvas. *)
    KeyGesture;             (* A key on the keyboard is pressed. *)

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

  object Gesture is name:GestureName and onoff:boolean and
        procname:string and wason:boolean
    description: (*
        A Gesture is a record that corresponds to one of the entries in the
        sensitize edit window.  It contains a boolean flag that corresponds to
        the on/off check box foreach gesture, and string that records the
        interface operation name for a gesture.  The wason component is used
        when an object is grouped and ungrouped to maintain proper
        sensitization (see the specs of the Group and Ungroup ops below).
    *); 
  end;

  object GestureName is string;
        
  object GestureMap is list of Gesture
    operations: 
	  gtype: GestureType;
    description: (*
        A GestureMap is a list of Gestures, one for each type of gesture.  A
        GestureMap is the type that corresponds to the full sensitize edit
        window.    *); 
  end;


  object Graphic
    description: (*
        Graphic is the opaque type for a graphical item drawn on a canvas.
    *); 
  end;

  object SelectionInfo is
        BeingTextEdited: boolean;  (* On if in a text-edit loop for a given selection *)
	  EditEnabled: boolean; (* On if selection properties are editable *)
    description: (*
        SelectionInfo is an enumeration of informational flags for different
        types of selections.
    *); 
  end;

  object BeingTextEdited is boolean;

  object Selection is
	  name: String,        (* name of selection *)
        pict:Graphic,        (* Physical screen rendering of the selection. *)
        stype: string,       (* General type of selection. *)
        sID: integer,	     (* Unique ID of selection object *)
        map: GestureMap,     (* Sensitive gestures and corresponding procs *)        
	  x:integer,y:integer, (* x,y coords of the Selection *)
        l:integer,b:integer, (* InterViews-style l,b,r,t original coords *) 
        r:integer,t:integer, (* NOTE: Use functions GetCoords or GetCoordsBox
                             (* to obtain current coordinates. *)
        flags:SelectionInfo  (* Type-specific informational flags *)
	  layer: integer	     (* Unique integer represents layering this selection with *)
				     (* respect to other selections. *)
    description: (*
        Selection is the data structure that corresponds a selectable item on a
        canvas.
    *); 
  end;

  object SelectionList is Selection*;

  (*
   * The following four operations can be used to access and modify the
   * type and map fields of a Selection.
   *)
  operation GetType(s:Selection) -> string;
  operation SetType(s:Selection, stype: string);
  operation GetMap(s:Selection) -> GestureMap;
  operation SetMap(s:Selection, gm:GestureMap);

  (*
   * The following are used to obtain the current screen position of a
   * selection -- they've been moved to demo.rsl.
   *
  operation GetCoords(s:Selection) -> Coords;
  operation GetCoordsBox(s:Selection) -> CoordsBox;
   *
   *)

  object Side is TOP or BOTTOM or LEFT or RIGHT
    description: (*
        Side is an enumeration of the four sides of an object, It's used as a
        parameter type in some of the graphic operations below.
    *); 
  end;
  object TOP;
  object BOTTOM;
  object LEFT;
  object RIGHT;


    (*
     * Coord is just a simple little type that defines a screen coordinate as
     * an integer.
     *)
    object Coord is integer;


    (*
     *
     * The editing and drawing operations follow.  They are organized into the
     * major categories described above.
     *
     *)


    (*
     * Graphic editing ops.  Note that editing operations (Move through
     * Magnify) work on the current selection(s).  Hence, to Move an object, it
     * must first be selected via the Select operation (or have been selected
     * by the user).  To remain functional, these operations take a Canvas as
     * input and output.  This models the user-level of functionality of these
     * operations more accurately than if they took a Selection of
     * SelectionList as input.  The programmatically invocable versions of
     * these basic editing ops do in fact take Selection(s) as input.  See
     * there definitions further below.
     *)
    operation Select(c:Canvas, sl:Selections)->c':Canvas
      description: (*
        Output a canvas with the same propeties as the input canvas except that
        the currently selected selections of the output are the given
        selections.
      *);
        
      post: c'.lc.cl.ssl = sl
        (* and all other (sub)components of c' are the same as c *);
   end;

  operation Move(c:Canvas, l:Coord, b:Coord)->c':Canvas
    post: 
        (*
         * For each selected selection in the input canvas, that selection is
         * moved relative to its initial location by l pixels horizontally and
         * b pixels vertically.
         *)
        forall (s in c.ls)
            if (s in c.lc.cl.ssl) then
                exists (s' in c'.ls) (s'.x = s.x + l) and (s'.y = s.x + b)
            else
                s in c'.ls;
  end;

  operation Scale(c:Canvas, factor:real)->c':Canvas;
  operation Stretch(c:Canvas, side:Side, amount:real)->c':Canvas;
  operation Rotate(c:Canvas, degrees:real)->c':Canvas;
  operation Reshape(c:Canvas, x0:Coord, y0:Coord, x1:Coord, y1:Coord)->
      c':Canvas;
  operation Magnify(c:Canvas, x0:Coord, y0:Coord, x1:Coord, y1:Coord)->
      c':Canvas;
 
  obj CanvasNavigator is
	  components: CanvasNameList, LayerNameList, ObjectNameList, SelectedName;
	  description:  (*
		The CanvasNavigator is used by the user to navigate through all the canvases, layers, and objects that exist in the current open project
				*)
  end CanvasNavigator;

  obj CanvasNameList is list of CanvasName;
  obj LayerNameList is list of LayerName;
  obj ObjectNameList is list of ObjectName;
  obj CanvasName is string, Isexpanded;
  obj LayerName is string, Isexpanded;
  obj ObjectName is string, Isexpanded;
  obj SelectedName is CanvasName OR LayerName OR ObjectName;
  obj Isexpanded is boolean;

  obj GuiToolMenuBar is 
        components: FileMenu, EditMenu, FormatMenu, ArrangeMenu, RunMenu, 
               ToolsMenu, ViewMenu, OptionsMenu, HelpMenu;
        description: (* This is the floating menu bar for the Gui Spec Tool.*);
  end GuiToolMenuBar;
   
   (*
   * File menu objects.
   *)
  obj FileMenu is 
	operations:   
		FileImportDrawing(filename:string);  
   end FileMenu;

  (*
   * Edit menu commands.
   *)
  obj EditMenu is 
	operations:   
  	  EditSelectAll(s: SelectionList)->(s': SelectionList);
  end EditMenu;

  obj FormatMenu is
	operations:
	 
  end FormatMenu;

  obj ArrangeMenu is
	operations:
	 
  end ArrangeMenu;

  obj RunMenu is
	operations:
	 
  end RunMenu;

  obj ToolsMenu is
		(* Environment preferences are contained in project properties *)
	component: ColorFunctions, DrawingFunctions, StatusFunctions, 	WidgetFunctions;
 	operations:
	  CallTextEditor(p: Project);
	  CallGraphicsEditor(p: Project);	 
  end ToolsMenu;

  obj ViewMenu is
	operations:
	  ZoomIn(c:Canvas; zf:integer)->(c': Canvas);
	  ZoomOut(c:Canvas; zf:integer)->(c': Canvas);
	   ScrollLeft(c:Canvas, l:Coord, b:Coord)->c':Canvas
    		post: 
        		(*For each selected selection in the input canvas, that selection is moved relative to its initial location by l pixels horizontally and b pixels vertically.*)
        		forall (s in c.ls)
            		if (s in c.lc.cl.ssl) then
                		exists (s' in c'.ls) (s'.x = s.x - l) 
            		else
               		 s in c'.ls;
  		end;

  	 ScrollRight(c:Canvas, l:Coord, b:Coord)->c':Canvas
    		post: 
        		(*For each selected selection in the input canvas, that selection is moved relative to its initial location by l pixels horizontally and b pixels vertically.*)
        		forall (s in c.ls)
            		if (s in c.lc.cl.ssl) then
               		 exists (s' in c'.ls) (s'.x = s.x + l) 
            		else
              		  s in c'.ls;
  		end;

 	 ScrollUp(c:Canvas, l:Coord, b:Coord)->c':Canvas
    		post: 
       		 (*For each selected selection in the input canvas, that selection is moved relative to its initial location by l pixels horizontally and b pixels vertically.*)
        		forall (s in c.ls)
            		if (s in c.lc.cl.ssl) then
                		exists (s' in c'.ls) (s'.y = s.y - l) 
            		else
               		 s in c'.ls;
  		end;

  	ScrollDown(c:Canvas, l:Coord, b:Coord)->c':Canvas
    		post: 
(*For each selected selection in the input canvas, that selection is moved relative to its initial location by l pixels horizontally and b pixels vertically.*)
        		forall (s in c.ls)
            		if (s in c.lc.cl.ssl) then
               		 exists (s' in c'.ls) (s'.y = s.y + l) 
            		else
                		s in c'.ls;
  		end;
	 
  end ViewMenu;

  obj OptionsMenu is
	operations:
	  EditOnOff(c: Canvas; s: Selection)->(c': Canvas; s': Selection)
	    (* Toggles Selection.SelectionInfo.EditEnabled boolean property *)
	    (* Environment preferences are contained in project properties *)
	  LoadPreferences(p: Project)->(p': Project);
	  SavePreferences(p: Project)->(p': Project);
	 
  end OptionsMenu;

  obj HelpMenu is 
  	operation OptionShowVersion() -> string;
  end HelpMenu;

(*
  obj WindowsMenu is
	operation:
	  Projects(pl: ProjectList; p: ProjectNumber)->(pl':ProjectList);
	  Canvasses(cl: CanvasList);
	  ShowCanvasses(cl: CanvasList;canvasnumber: integer)->(c: CanvasList);
	  HideCanvas(cl: CanvasList; canvasnumber: integer)->(c: CanvasList);
	  Palettes(pal: PaletteList; p: PalletteNumber)->(pal': PaletteList);
	  ShowDesriptionBox(c: Canvas)->(c':Canvas);
	  HideDesriptionBox(c: Canvas)->(c':Canvas);
  end WindowsMenu
*)
(*  obj ObjectsMenu is
	operations:
	  FirstCanvas(cl: CanvasList)->(c: Canvas);
 	  LastCanvas(cl: CanvasList)->(c: Canvas);
 	  NextCanvas(cl: CanvasList)->(c: Canvas);
 	  PreviousCanvas(cl: CanvasList)->(c: Canvas);
 	  GotoCanvas(cl: CanvasList; canvasnumber: integer)->(c: Canvas);
 	  Recents(cl: CanvasList; canvasnumber: integer)->(c: Canvas);
 	  Group(sl: SelectionList; c: Canvas; canvasnumber: integer)->
		(s: Selection; sl': SelectionList; c': Canvas);
	     post:
      	(*
             * The currently selected selections in c are turned into a single
         	 * composite selection in c'.  The onoff gesturemap flag for all
         	 * grouped selections is off, and the wason flag is on if it was on
         	 * before grouping.  In this way, the ungroup op can properly restore
         	 * the sensitzed state of the objects when they are ungrouped.
         	 *);
 	  UnGroup(s: Selection; c: Canvas; canvasnumber: integer)->
		(sl': SelectionList; c: Canvas);
   	  StructureBringToFront();
   	  StructureSendToBack();
        (* Sensitize is imported from Sbd module *)
  end ObjectsMenu;
*)	  

  obj ColorFunctions is
	operations:
	  ColorPalette(p: Project)->(p': Project);
 	  ShowColorPaletteForm(pe: Project.Environment)->(pe': Project.Environment) 
	  ShowSelectedColor(pe: Project.Environment)->(pe': Project.Environment);
	  ColorBoxClick(p: Project,c: colornumber)->(p':Project);
	  (* This operation shall call the ColorMap function in Project methods *)
	  ColorWheelClick(p: Project,c: colornumber)->(p':Project);
	  (* This operation shall call the ColorMap function in Project methods *)
	  EnterColorParam(r: integer, g: integer, b: integer, p: Project)->(p':Project);
	  (* This operation shall call the ColorMap function in Project methods *)
  end ColorFunctions;

  obj DrawingFunctions is
	components: BrushStyle, BrushSize;
	operations:
	  DrawingPalette(p: Project)->(p': Project); 
        OptionGriddingOnOff(on: boolean);
        OptionGridVisibleInvisible(visible: boolean);
        OptionGridSpacing(gridsize: integer);        ScaleSelection(s:Selection, factor: real);
        RotateSelection(s:Selection, degrees:real);
        ExpandSelection(s:Selection)->(s': Selection);
        CollapseSelection(s:Selection)->(s': Selection);
        DrawText(c: Canvas,l:Coord, b:Coord, text:string) -> (s: Selection, c': Canvas);
        DrawLine(c: Canvas,x0:Coord, y0:Coord, x1:Coord, y1:Coord) -> 
			(s: Selection,  c': Canvas);
        DrawArchedLine(c: Canvas,x:Coord*, y:Coord*) ->  (s: Selection, c': Canvas;
        DrawEllipse(c: Canvas,cx:Coord, cy:Coord, xr:Coord, yr:Coord) -> 
			(s: Selection, c': Canvas);
        DrawRect(c: Canvas,l:Coord, b:Coord, r:Coord, t:Coord) ->  
			(s: Selection, c': Canvas);
        DrawPolygon(c: Canvas,x:Coord*, y:Coord*) ->  (s: Selection, c': Canvas);
	  (* This operation shall call the getFGColor function in Project obj *)
	  AddFill(s:Selection, p': Project)->(s': Selection,p': Project);
	  FGColor(p: Project)->(p':Project);
	  BGColor(p: Project)->(p':Project);
  end DrawingFunctions;

  obj StatusFunctions is
	operations:
	  StatusBar(p: Project)->(p': Project);
	  StatusDisplay(p: Project, c: Canvas, s: Selection, cdp: CurrentDevelopmentPhase); 
  end StatusFunctions;
	  
  obj WidgetFunctions is
	operations:
	  
  end WidgetFunctions;

  (*
   * Specialized operations.  These include:
   *
   *   (1) specialized forms of Select
   *   (2) parameterized versions of the edit operations; these operate on a
   *       given selection rather than the current selection
   *   (3) operations for text editing; these correspond to the operations
   *       the user can perform after selecting 'Reshape' on a text object
   *   (4) Specialized file-related operations; these are performed by the
   *       user by manipulating X Windows
   *   (5) Specialized edit-related operations.
   *)
  operation SelectMultiple(sl:SelectionList);
  operation Unselect(s:Selection);
  operation UnselectMultiple(sl:SelectionList);

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

  operation EditUnselectAll();
  operation EditShow(ob:Selection);
  operation EditHide();
  operation ShowAll();        (* Groups them, so they can be rehidden. *)

  operation FileSelectCanvas(canvasnum:integer);
  operation FileRaiseCanvas(canvasnum:integer);
  operation FileLowerCanvas(canvasnum:integer);
  operation FileMoveCanvas(x:integer, y:integer);
  operation FileResizeCanvas(width:integer, height:integer,x:integer, y:integer);
  operation FileShowHideCanvas(canvasnum:integer, show:boolean);
  operation FileShowHideMenus(show:boolean);
  operation FileShowHideTools(show:boolean);

  (*
   * Event is the record of single interactive event occurring on a canvas.
   *)
  object Event is
        target: Selection,       (* selection on which event occurred *)
        timestamp: integer,      (* a relative time *)
        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 *)

    (*
     * Operation 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;
     *
     *          e := ReadEvent();
     *          while EventIsOfInterest(e) do
     *              ProcessEvent(e);
     *              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
     * operation to perform appropriate even processing.  (Note that
     * EventIsOfInterest and ProcessEvent are *not* built-in -- they are
     * assumed to have been written by a developer.)
     *)
    operation 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.
     *)
    operation 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 operation that wants to know the particular event that lead to
     * its invocation.
     *)
    operation GetLastEvent() -> Event;


    (*
     * Type InterfaceProc is the type of all operations that are mapped to a
     * user-performed gesture.  Note that an interface procecure takes no
     * parameters and returns no values.  The effect of an interface operation
     * is produced by the built-in interface operations that it calls (and/or
     * the global module variables that it manipulates).
     *)
    object InterfaceProc is op()->();


    (*
     * The next three operations are conveniences to set fields of a gesture.
     * Hence, Gesture may be treated as an opaque type if desired.
     *)
    operation SetMapping(s: Selection, ip:InterfaceProc);
    operation EnableGesture(s: Selection);
    operation DisableGesture(s: Selection);
    operation CallEditGesture(s: Selection; e: Event, ip:InterfaceProc);

    (*
     * The following operations define standard graphical predicates that may
     * be useful in advanced interface programming.
     *)
    operation Intersects(s1:Selection, s2:Selection) ->boolean;
    operation Contains(s1:Selection, s2:Selection) ->boolean;
    operation LeftOf(s1:Selection, s2:Selection) ->boolean;
    operation RightOf(s1:Selection, s2:Selection) ->boolean;
    operation Above(s1:Selection, s2:Selection) ->boolean;
    operation Below(s1:Selection, s2:Selection) ->boolean;
    operation ContainsLeftEndPoint(s1:Selection, s2:Selection) ->boolean;
    operation ContainsRightEndPoint(s1:Selection, s2:Selection) ->boolean;
    operation LeftEndPointContainedIn(s1:Selection, s2:Selection) ->boolean;
    operation RightEndPointContainedIn(s1:Selection, s2:Selection) ->boolean;
    operation DistanceFrom(s1:Selection, s2:Selection, d:integer) ->boolean;
    operation DirectionFrom(s1:Selection, s2:Selection, d:integer) ->boolean;
    operation SameInstanceAs(s1:Selection, s2:Selection) ->boolean;
    operation MoveSelection(s:Selection, l:integer, b:integer);


    op OpenWindow;
    op CloseWindow;
    op MoveWindow;
    op ResizeWindow;
    op IconifyWindow;   (* Alias Minimize *)
    op DeiconifyWindow; (* Alias Restore *)
    op MaximizeWindow;
    op MinimizeWindow;
    op RaiseWindow;
    op LowerWindow;
    op FocusOnWindow;
    op UnFocusOnWindow;
    op ListWindows;


    (* Plus whatever else a window manager may do that we need access to. *)
  	operation EditFlipHorizontal();
  	operation EditFlipVertical();
  	operation Edit90Clockwise();
  	operation Edit90CounterClockwise();
  	operation EditPreciseScale(factor:real);
  	operation EditPreciseRotate(degrees:real);
  	operation EditInterpret(command:string);

end GuiBuilderInterface;