gef/src/GEFClass.i3


Copyright (C) 1994, Digital Equipment Corp.

INTERFACE GEFClass;

<* PRAGMA LL *>

IMPORT Atom, Color, Font, FormsVBT, GEF, GEFError, RefList, PaintOp,
       SLisp, Thread;

VAR
  mu: MUTEX;

TYPE
  S_exp = REFANY;
  Elem = REFANY;
  Name = Atom.T;
  Names = REF ARRAY OF Name;

TYPE
  RInt = REF INTEGER;
  RReal = REF REAL;
  RBool = REF BOOLEAN;
  RefRGB = REF Color.T;

TYPE
  Ints = REF ARRAY OF INTEGER;
  Reals = REF ARRAY OF REAL;
  Bools = REF ARRAY OF BOOLEAN;
  Texts = REF ARRAY OF TEXT;
  Elems = REF ARRAY OF Elem;

PROCEDURE Parse (t              : T;
                 sx             : S_exp;
                 showAllElements: BOOLEAN     ) RAISES {Thread.Alerted};
<* LL < mu *>
Parse sx reporting any errors or successfully incorporating sx into t. If showAllElements then make sure all elements are visible.

PROCEDURE IncrementalParse (t: T; sx: S_exp)  RAISES {Thread.Alerted};
<* LL = mu *>
Parse sx reporting any errors or successfully adding sx in the current state of t.

TYPE
  T = GEF.T;

TYPE
  Interval = REF RECORD start, end: CARDINAL END;

TYPE
  TPublic =
    GEF.TPublic OBJECT
      <* LL = mu *>
      showAllElements: BOOLEAN;
      (* "showAllElements" gets passed to "finish" methods, all elements should be made
         visible if TRUE *)

      interp: SLisp.T;
      (* the interpreter for the GEF lisp language *)
    END;

REVEAL
  T <: TPublic;

TYPE
  ParseObject <: POPublic;
  POPublic =
    OBJECT
      args: TEXT;
      (* "args" is an s-expression describing the fields and types of an
         object defined by self.

         Every args list must include a "Name" field giving the name of the
         object The args list may include any number of entries of the
         following form:

         (Field <index value of field> <name of field> <type> <number of
         values> <(list of field values names)> <(list of field value defaults)>)

         Every "Field" must have some value for all entries.

         <index value of field> is an integer.

         <name of field> is a text or symbol.

         <type> is one of: "Boolean", "Integer", "Real", "Text",
         "Elem", "Sx", "ColorSpec", "FontSpec" or it can be a list of
         enumerated values e.g. "(Rectangle Ellipse)".

         <number of values> is an integer or "Infinity"
         NOTE: There can not be an infinite number of "Boolean", "Integer",
         "Real" or enumerated values.

         "<(list of field value names)>" may be "NIL" (empty list: "()")
         or it is a list of names of the components of the field (say
         x and y components of a position).  If the number of values is
         "Infinity" then "<(list of field values names)>" must be "NIL".

         a "Sx" value is any Sx expression passed as an uninterpreted Sx.T

         a "FontSpec" is the name of a font (for X, a full "Stars and Bars"
         font name is recommended, or it is the special value "BuiltIn"
         for the builtin font, or it is a list of font properties (a
         "*" for a text matches anything for that property):

         (Foundry <text>) - default "*"
         (Family <text>) - default "Helvetica"
         (Weight <text>) - default "Medium"
         (Slant  <one of "R", "I", "O", "RI", "RO", "OT">) - default "R"
         (Size <real>) - default 0.0353 (10pt in default world and size)

         Examples of font specs:

         "BuiltIn"
         "-Adobe-Symbol-Medium-R-Normal--*-0.05-*-*-*-*-ISO8859-1"
         (Family "Helvetica") (Slant "R") (Size 0.05)

         A "FontSpec" is converted to a Text when the SetText
         method is called.

         A "ColorSpec" is the name of a color, the special values "Bg" and
         "Fg" for the builtin PaintOp.Bg and PaintOp.Fg or it can be
         3 real numbers in the range 0.0 .. 1.0 giving the red, green
         and blue values of the color.  "0 0 0" is black, "1 1 1" is white.

         Examples of color specs:

         "Bg"
         "Fg"
         "Red"
         0.3 0.3 0.7

         Every args list implicitly includes a specification
         "(Field xxx Name Text 1 () ())".  The setText/getText methods
         of the object are not called for the "Name" field.  GEFClass
         maintains the mapping between names and objects.  Objects that
         have no name given in the sx expression, get unique generated names.
         *)

      fv: TEXT;
      (* "fv" is the text string describing a formsvbt form for displaying
         and editing the properties of this parse object.  If "fv" is not
         set when "RegisterParseObject" is called, it will be generated from "args". *)
    METHODS
      <* LL = mu *>
      create (t: T; id: INTEGER): Elem;
      (* Create and return a default object associated with t.  Return "id"
         from the "getId" method  *)

      delete (t: T; elem: Elem);
      (* Clean up and delete "elem" *)

      setInt (t: T; elem: Elem; field: INTEGER; value: Ints) RAISES {GEFError.T};
      setReal (t: T; elem: Elem; field: INTEGER; value: Reals) RAISES {GEFError.T};
      setBool (t: T; elem: Elem; field: INTEGER; value: Bools) RAISES {GEFError.T};
      setText (t: T; elem: Elem; field: INTEGER; value: Texts) RAISES {GEFError.T};
      setElem (t: T; elem: Elem; field: INTEGER; value: Elems) RAISES {GEFError.T};
      (*| Set "field" in "obj" to "value".

          "field" comes from the index value given for the field when the element was
          registered.

         "value" is a REF ARRAY OF <valueType> where the number of elements
         in the array comes from the field descriptor.

         The value types are the expected ones except for Colors, Fonts and Enums.

         Sx's are passed as Elems (REFANY) to the setElem method and are Sx.T.

         Colors are Texts and are either the name of the color or the 3 reals
         giving the RGB of the color.  Call "PaintOpFromColor" or "RGBFromColor"
         to convert the text to the desired form (includes caching to reduce
         resource use).

         Fonts are a text giving the name of the font.  Call "FontFromName"
         to convert the text name to a font (includes caching to reduce resource
         use).

         Enums are INTEGERs where each element is the ORD value
         of the associated enumerated value.
      *)

      getId(t: T; elem: Elem): INTEGER;
      (* return the id of "elem" *)

      finish (t: T; elem: Elem) RAISES {GEFError.T, Thread.Alerted};
      (* finish any work involved in creating "obj", installing,
         initializing, consistency checks, etc...

         should also check t.showAllVisible.  If TRUE then try to
         make object visible.
      *)

      isType (elem: Elem): BOOLEAN;
      (* returns TRUE is "obj" is a subtype of the type "create" returns *)
    END;
      Examples of s-expressions for "args":
((Name Graph) (Field 0 World Real 4 (west east north south) (0.0 1.0 0.0 1.0)) (Field 1 Margin Real 1 () (0.0)) (Field 2 PixelSizeDivisor Integer 2 (x y) (1 1)) (Field 3 Aspect Real 1 () (0.0)) (Field 4 ClientProps Sx 1 () ()) (Field 5 Contents Elem Infinity () ()))

((Name Vertex) (Field 0 Shape (Rectangle Ellipse) 1 () (Rectangle)) (Field 1 Pos Real 2 (x y) (0.0 0.0)) (Field 2 Size Real 2 (width height) (0.0 0.0)) (Field 3 Color ColorSpec 1 () (Fg)) (Field 4 Label Text 1 () ()) (Field 5 Font Text 1 () (BuiltIn)) (Field 6 FontColor ColorSpec 1 () (Fg)) (Field 7 BorderWidth Real 1 () (0.0)) (Field 8 BorderColor ColorSpec 1 () (Fg)))

Note: It is not necessary for the field indices to be either 0 based, sequential or small. They only have to be unique.

PROCEDURE RegisterParseObject (po: ParseObject);
<* LL < mu *>
Register a parsing object
 ------------------ General utilities -------------------- 

<* LL < mu *>
PROCEDURE ReportError (fv: FormsVBT.T; msg: TEXT);

<* LL = mu *>
PROCEDURE FontFromName (name: TEXT): Font.T RAISES {GEFError.T};
PROCEDURE NameFromFont (font: Font.T): TEXT RAISES {GEFError.T};
PROCEDURE PaintOpFromColor (color: TEXT): PaintOp.T RAISES {GEFError.T, Thread.Alerted};
PROCEDURE ColorFromPaintOp (op: PaintOp.T): TEXT RAISES {GEFError.T};
PROCEDURE RGBFromColor (color: TEXT): Color.T RAISES {GEFError.T, Thread.Alerted};
PROCEDURE ColorFromRGB (rgb: Color.T): TEXT RAISES {GEFError.T};

<* LL < mu *>
PROCEDURE ParseObjectFromElem(elem: Elem): ParseObject;
returns the parse object that created elem

<* LL = mu *>
PROCEDURE GenName (): TEXT;
Generate a unique name for an element

<* LL < mu *>
PROCEDURE ElemFromName (t: T; name: TEXT): Elem RAISES {GEFError.T};
PROCEDURE NameFromElem (t: T; elem: Elem): TEXT;
----------------- GEVClass utilities ---------------------
<* LL < mu *>
PROCEDURE GetElemField(t: T; elem: Elem; field: TEXT): REFANY RAISES {GEFError.T};
returns the values associated with field in elem. The values returned are READONLY.

<* LL < mu *>
PROCEDURE SetElemField(t: T; elem: Elem; field: TEXT; values: REFANY)
  RAISES {GEFError.T};
set field in elem to values

<* LL < mu *>
PROCEDURE GetRange (t: T; obj: REFANY; VAR (* OUT *) start, end: CARDINAL);
get the range of characters describing obj in t'<s editor display

<* LL < mu *>
PROCEDURE UpdateRange (t: T; obj: REFANY; start, end, length: CARDINAL);
Adjust all character ranges after start by (end - start) - length.

<* LL < mu *>
PROCEDURE GetFV (t: T; elem: REFANY): FormsVBT.T;
Get the form (uninstalled) displaying the value of elem

<* LL < mu *>
PROCEDURE SetElemFromFV(t: T; elem: Elem; fv: FormsVBT.T) RAISES {GEFError.T};
Set properties of elem from the values in fv.

<* LL < mu *>
PROCEDURE CreateElemFromFV (t: T; fv: FormsVBT.T): Elem
  RAISES {GEFError.T, Thread.Alerted};
Create an element from the values in fv.

<* LL < mu *>
PROCEDURE SetFVFromElem(t: T; elem: Elem; fv: FormsVBT.T) RAISES {GEFError.T};
Set values of fv from the properties in elem.

TYPE InstallClosure = OBJECT METHODS install (fv: FormsVBT.T) END;

<* LL < mu *>
PROCEDURE AddParseObjectsToMenu (fv     : FormsVBT.T;
                                 menu   : TEXT;
                                 closure: InstallClosure     );
Add a menu button item for each registered parse object to menu in fv. Call closure.install with the new fv file for the selected parse object type when the item is selected by the user.

<* LL < mu *>
PROCEDURE SxFromElem (t: T; elem: Elem): S_exp;
Return the s_exp describing elem

TYPE
  ElementList = REF ARRAY OF
                      RECORD
                        type : TEXT;
                        names: REF ARRAY OF TEXT;
                      END;

<* LL < mu *>
PROCEDURE AllElements (t: T): ElementList;
--------------------- GEFLisp utilities --------------------------

<* LL < mu *>
PROCEDURE CreateElemFromPO (t: T; po: ParseObject): Elem
  RAISES {GEFError.T, Thread.Alerted};
Create an element using po in the current environment of t.

<* LL < mu *>
PROCEDURE GetProp (t: T; elem: Elem; prop: S_exp): RefList.T
  RAISES {GEFError.T, Thread.Alerted};
Returns a READONLY list of the value(s) of field prop of elem. prop should be a name of a property of elem.

<* LL < mu *>
PROCEDURE SetProp (t: T; elem: Elem; prop: S_exp; value: RefList.T)
  RAISES {GEFError.T, Thread.Alerted};
Set elems field prop to value. prop should be a name of a property of elem.

<* LL < mu *>
PROCEDURE Delete(t: T; elem: Elem) RAISES {GEFError.T, Thread.Alerted};
Delete elem
 ------------------------ GEFA Utilities ------------------- 

<* LL < mu *>
PROCEDURE UpdateElemField(t: T; elem: Elem; field: TEXT; values: REFANY)
  RAISES {GEFError.T};
update field in elem to values. Doesn't actually set elem's elem's value, but updates the value stored by GEF. Used for when an vertex moves to update the position.

END GEFClass.