(* Copyright (C) 1992, Digital Equipment Corporation *)
(* All rights reserved. *)
(* See the file COPYRIGHT for a full description. *)
(* *)
(* Last modified on Mon Jan  4 12:36:28 PST 1993 by mhb *)
(* modified on Sun Jul 19 23:05:43 PDT 1992 by meehan *)
(* modified on Tue Jun 16 21:55:35 PDT 1992 by muller *)
<* PRAGMA LL *>

(* The "XParam" interface provides utilities for handling X-style
   "-display" and "-geometry" arguments.  If your application
   installs a single top-level window, the "XTrestle" interface
   may be more appropriate than this interface. *)

INTERFACE XParam;

IMPORT Point, Rect, Trestle, TrestleComm;

(* Here are routines for manipulating the "-display" option: *)

TYPE
  Display = RECORD
              hostname: TEXT     := "";
              display : CARDINAL := 0;
              screen  : CARDINAL := 0;
              DECnet  : BOOLEAN  := FALSE
            END;

PROCEDURE ParseDisplay (spec: TEXT): Display RAISES {Error};
<* LL = arbitrary *>
(* Return a parsed version of the "-display" parameter in "spec".
   For example, if "spec" contains the string
   "myrtle.pa.dec.com:0.2", the record returned would be
|   Display{hostname := "myrtle.pa.dec.com",
|           display := 0, screen := 2, DECnet := FALSE}
   *)

PROCEDURE UnparseDisplay (READONLY d: Display): TEXT;
<* LL = arbitrary *>
(* Return the text-version of the "-display" parameter "d". *)


(* Here are routines for manipulating the "-geometry" option: *)

CONST Missing = Point.T{-1, -1};

TYPE
  Geometry =
    RECORD
      vertex := Rect.Vertex.NW;  (* corner for displacement *)
      dp     := Point.Origin;    (* displacement *)
      size   := Missing;         (* width, height *)
    END;

PROCEDURE ParseGeometry (spec: TEXT): Geometry RAISES {Error};
<* LL = arbitrary *>
(* Return a parsed version of the "-geometry" parameter in
   "spec".  For example, if "spec" contains the string
   "1024x800-0-10", the returned record would be
|     Geometry {Rect.Vertex.SE,
|             Point.T {0, 10},
|             Point.T {1024, 80}}
   The "size" field defaults to "Missing".  The horizontal and
   vertical displacements default to "Point.Origin" (no
   displacement).  The displacements are always positive values;
   use the "vertex" field to find out from which corner they are
   to be offset. *)

PROCEDURE UnparseGeometry (READONLY g: Geometry): TEXT;
<* LL = arbitrary *>
(* Return the text-version of the "-geomtry" switch "g". *)

PROCEDURE Position (         trsl: Trestle.T;
                             id  : Trestle.ScreenID;
                    READONLY g   : Geometry          ): Point.T
  RAISES {TrestleComm.Failure};
<* LL.sup = VBT.mu *>
(* Return the position specified by "g" in the screen coordinates
   for the screenID "id" on the window system connected to "trsl"
   (cf.  "Trestle.GetScreens").  The value of "g.size" must not
   be "Missing", unless "g.vertex" is the northwest corner. *)

(* Here is the definition of the "Error" exception: *)

TYPE
  Info = OBJECT
           spec : TEXT;
           index: CARDINAL
         END;
  GeometryInfo = Info BRANDED OBJECT END;
  DisplayInfo = Info BRANDED OBJECT END;

EXCEPTION Error(Info);
(* Parsing errors are reported with the text ("spec") and
   position ("index") of the first illegal character in the
   text. *)

(* \subsubsection{An example}

   Here is an example of how to use this interface to install a
   VBT "v" as a top level window, obeying the "-display" and
   "-geometry" switches given to the application.

   First, here are the variables we'll be using:

|  VAR
|    display, geometry: TEXT := NIL;
|    d: XParam.DisplayRec;
|    g: XParam.Geometry;
|    trsl: Trestle.T;
|  BEGIN

   Next, parse the command line arguments:

|    ParseParams.BeginParsing(Stdio.stderr);
|    TRY
|      IF ParseParams.KeywordPresent("-display") THEN
|        display := ParseParams.GetNext();
|        d := XParam.ParseDisplay(display);
|      END;
|    EXCEPT Scan.BadFormat, XParam.Error =>
|      display := NIL;
|      Wr.PutText(
|        Stdio.stderr, "Illegal -display argument ignored");
|    END;

|    TRY
|      IF ParseParams.KeywordPresent("-geometry") THEN
|        geometry := ParseParams.GetNext();
|        g := XParam.ParseGeometry(geometry)
|        IF g.size = XParam.Missing THEN
|          WITH shapes = VBTClass.GetShapes(v, FALSE) DO
|            g.size.h := shapes[Axis.T.Hor].pref;
|            g.size.v := shapes[Axis.T.Ver].pref;
|          END
|        END
|      END;
|    EXCEPT Scan.BadFormat, XParam.Error =>
|      geometry := NIL;
|      Wr.PutText(
|        Stdio.stderr, "Illegal -geometry argument ignored");
|    END;

   At this point, if "display" is non-"NIL", then "d" contains
   the information from the "-display" switch.  Similarly, if
   "geometry" is non-"NIL", then "g" contains the information
   from the "-geometry" switch.  If the window-size
   specificiation was missing, the preferred shape of the window
   is used.

   Finally, we now process the "display" and "geometry"
   information:

|    trsl := Trestle.Connect(display);
|    Trestle.Attach(v, trsl);
|    TrestleImpl.SetDefault(trsl);
|    Trestle.Decorate(v, ... );
|    IF geometry = NIL THEN
|      Trestle.MoveNear(v, NIL)
|    ELSE
|      StableVBT.SetShape(v, g.size.h, g.size.v)
|      Trestle.Overlap(
|        v, d.screen, XParam.Position(trsl, d.screen, g))
|    END;
|  END;

   The "TrestleImpl" and "StableVBT" interfaces are part of
   Trestle.  The call to "TrestleImpl.SetDefault" establishes the
   value of the "-display" switch as the default Trestle
   connection.  The call to "StableVBT.SetShape" is used to
   control the size of a top-level window. *)

END XParam.