(* Copyright (C) 1992, Digital Equipment Corporation                         *)
(* All rights reserved.                                                      *)
(* See the file COPYRIGHT for a full description.                            *)
(*                                                                           *)
(* Last modified on Mon Jan  4 16:35:46 PST 1993 by mhb    *)
(*      modified on Tue Aug 11 20:29:25 PDT 1992 by meehan *)
(*      modified on Tue Jun 16 13:08:50 PDT 1992 by muller *)

(* The "FlexVBT.T" is a filter whose shape is based on a {\em
   natural} size with some {\em stretch} and {\em shrink}.  If a
   natural amount is left unspecified, the stretch and shrink are
   applied relative to the "FlexVBT"'s child's size.  If a
   stretch or shrink is left unspecified, 0 is assumed.  All
   units are specified in points (see the "Pts" interface).

   More precisely, the shape of a "FlexVBT.T" is computed as

   follows:

|       preferred := natural,
|       lo        := natural - shrink
|       hi        := natural + stretch + 1

   However, if any of these values are left unspecified, a size
   range is computed consistent with its child's shape according
   to the following rules:

   \begin{itemize}

   \item if natural is missing, use child's preferred;

   \item if shrink is missing, use 0 if natural is set, or
   child's lo (but no more than v's preferred) otherwise;

   \item if stretch is missing, use 0 if natural is set, or
   child's hi (but no less than v's preferred) otherwise.

   \end{itemize}

   This interface is similar to "RigidVBT", but more powerful in
   that one can specify a size based on a child's size and can
   dynamically change the size specification.  Also, it presents
   a slightly different model to the client: In "RigidVBT", one
   thinks in terms of the low and high bounds of some range.
   Here, one thinks in terms of the amount the a value can
   stretch and shrink.  Finally, don't forget that values in this
   interface are specified in points, whereas "RigidVBT" uses
   millimeters. *)


INTERFACE FlexVBT;

IMPORT Axis, Filter, VBT;

(* The following types are used to specify the shape of a "FlexVBT.T": *)

CONST
  Large    = 99999.0;
  Missing  = -Large;
  Infinity = Large;

TYPE
  Points = REAL;
  SizeRange = RECORD natural, shrink, stretch: Points END;
  Shape = ARRAY Axis.T OF SizeRange;

(* Some useful shapes are defined at the end of this interface. *)

TYPE
  T <: Public;
  Public = Filter.T OBJECT
           METHODS
             init (ch: VBT.T; sh := Default): T
           END;

(* The call "v.init(...)" initializes "v" as a "FlexVBT" with
   child "ch" and shape specification "sh".  The default shape
   causes "v" to be a (costly) no-op: it will simply return the
   shape of its child as its own. *)

PROCEDURE New (ch: VBT.T; sh := Default): T;
(* "New(...)" is equivalent to "NEW(T).init(...)". *)

PROCEDURE FromAxis (ch: VBT.T;
                    ax: Axis.T;
                    sh           := DefaultRange): T;
(* Return a "FlexVBT" and whose shape specification in the "ax"
   dimension is "sh" and whose shape in the other dimension is
   that of "ch". *)

PROCEDURE Set (v: T; sh: Shape);
(* Change the shape of "v" to "sh", and notify "v"'s parent that
   "v"'s size has changed. *)

PROCEDURE SetRange (v: T; ax: Axis.T; sr: SizeRange);
(* Change the shape of "v" to "sr" along the "ax" axis, and
   notify "v"'s parent that "v"'s size has changed. *)

(* The rest of this inteface defines some useful shapes:
   "Default" uses child's size info. 
   "Fixed" uses child's preferred, removing all shrink and stretch.
   "Stretchy" uses child's preferred and shrink, giving infinite stretch. *)

CONST
  Default  = Shape{DefaultRange, DefaultRange};
  DefaultRange =
    SizeRange {natural := Missing,
               shrink  := Missing, 
               stretch := Missing};

  Fixed   = Shape{FixedRange, FixedRange};
  FixedRange =
    SizeRange {natural := Missing, 
               shrink  := 0.0, 
               stretch := 0.0};

  Stretchy = Shape{StretchyRange, StretchyRange};
  StretchyRange = 
    SizeRange {natural := Missing,
               shrink  := Missing, 
               stretch := Infinity};
               
PROCEDURE RigidRange (natural: Points): SizeRange;
(* Return a "SizeRange" with the specified natural amount and
   with no stretch or shrink.  Equivalent to
|  SizeRange {natural, 0.0, 0.0}
*)

END FlexVBT.