The XParam interface

The XParam interface provides utilities for handling X-style -display and -geometry command-line 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 argument:

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 argument 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 argument d.

Here are routines for manipulating the -geometry argument:

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 argument 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, 800}}

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 -geometry argument 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.

END XParam.

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 arguments given to the application. It relies on the Params interface, which provides the number of arguments passed to the program, Params.Count, and a procedure to retrieve the value of the nth argument, Params.Get(n).

  EXCEPTION Error (TEXT);
  VAR
    display, geometry: TEXT := NIL;
    d: XParam.DisplayRec;
    g: XParam.Geometry;
    i: CARDINAL := 1;
  BEGIN
    LOOP
      IF i >= Params.Count - 1 THEN EXIT END;
      WITH argument = Params.Get (i) DO
        IF Text.Equal (argument, "-display") THEN
          display := Params.Get (i + 1);
          TRY d := XParam.ParseDisplay (display)
          EXCEPT XParam.Error (info) =>
            RAISE Error ("Illegal -display argument: "
                          & info.spec)
          END;
          INC (i, 2)
        ELSIF Text.Equal (argument, "-geometry") THEN
          geometry := Params.Get (i + 1);
          TRY
            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
          EXCEPT XParam.Error (info) =>
            RAISE Error ("Illegal -geometry argument: "
                          & info.spec);
          END;
          INC (i, 2)
        ELSE INC (i)
        END          (* IF *)
      END            (* WITH *)
    END;             (* LOOP *)

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

Finally, we now process the display and geometry information:

    VAR
      trsl := Trestle.Connect (display);
      screen: CARDINAL;
    BEGIN
      TrestleImpl.SetDefault (trsl);
      Trestle.Attach (v, trsl);
      Trestle.Decorate (v, ...);
      IF geometry = NIL THEN
        Trestle.MoveNear (v, NIL)
      ELSE
        StableVBT.SetShape (v, g.size.h, g.size.v)
        IF d = NIL THEN
          screen := Trestle.ScreenOf (v, Point.Origin).id
        ELSE
          screen := d.screen
        END;
        Trestle.Overlap (
          v, screen, XParam.Position(trsl, screen, g))
      END      (* IF *)
    END        (* BEGIN *)
  END;         (* BEGIN *)

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