ui/src/split/Split.i3

 Copyright (C) 1992, Digital Equipment Corporation                         
 All rights reserved.                                                      
 See the file COPYRIGHT for a full description.                            
                                                                           
 Last modified on Tue Mar 10 18:59:47 1992 by steveg     
      modified on Mon Feb 24 13:54:29 PST 1992 by muller     
      modified on Sat Dec 21 16:13:22 PST 1991 by gnelson    


<*PRAGMA LL*>

 The Split interface provides the functionality that is common
   to all splits; for example, enumerating and deleting children.


   This interface is for clients of splits; see the VBTClass and
   ProperSplit interfaces for information about implementing your own
   split classes.  


INTERFACE Split;

IMPORT VBT, Point;

TYPE T = VBT.Split;

EXCEPTION NotAChild;

 A Split.T is a VBT that divides its screen up between one or more
   child VBTs.
   The children of a split are ordered; they can be enumerated
   with the Succ and Pred procedures: 


PROCEDURE Succ(v: T; ch: VBT.T): VBT.T
RAISES {NotAChild}; <* LL >= {VBT.mu} *>

 Return the child of v that follows the child ch. 
 The successor of NIL is the first child; the successor of the last
   child is NIL; the successor of NIL is NIL if there are no
   children.  The exception NotAChild is raised if ch is not a child
   of v.  




PROCEDURE Pred(v: T; ch: VBT.T): VBT.T
RAISES {NotAChild}; <* LL >= {VBT.mu} *>

 Return the child of v that precedes the child ch. 
 More precisely, Pred(v,ch) = x iff Succ(v,x) = ch.  All of
  Trestle's standard splits implement Succ and Pred in constant
  time.  


PROCEDURE NumChildren(v: T): CARDINAL;
<* LL >= {VBT.mu} *>

 Return the number of children of v. 

PROCEDURE Nth(v: T; n: CARDINAL): VBT.T;
<* LL >= {VBT.mu} *>

 Return the child of v with index n. 
 More precisely, Nth(v, n) is the child of v with n
   predecessors, or NIL if v has at most n children.  Warning:
   for Trestle's standard splits, Nth requires time proportional to
   n, so it would be wasteful to enumerate the children by calling
   it repeatedly; use Succ instead.  




PROCEDURE Index(v: T; ch: VBT.T): CARDINAL
RAISES {NotAChild}; <* LL >= {VBT.mu} *>

 Return the index of v's child ch. 
 Index(v, ch) is the value n such that Nth(v, n) = ch.
   Index(v, NIL) equals NumChildren(v).  




PROCEDURE Locate(v: T; READONLY pt: Point.T): VBT.T;
<* LL.sup = VBT.mu *>

 Return the child of v that controls the point pt,
   or NIL if there is no such child. 

PROCEDURE Delete(v: T; ch: VBT.T) RAISES {NotAChild};
<* LL.sup = VBT.mu *>

 Delete the child ch of the split v, detach ch, and mark v
   for redisplay.  

PROCEDURE Replace(v: T; ch, new: VBT.T)
RAISES {NotAChild}; <* LL.sup = VBT.mu *>

 Replace child ch of v with new, detach ch (which must not be NIL),
   and mark v for redisplay.  

PROCEDURE Insert(v: T; pred, new: VBT.T)
RAISES {NotAChild}; <* LL.sup = VBT.mu *>

 Add new as a child of v following pred. 
 Some split classes can accomodate only a bounded number of children
  (for example, filters).  If Insert(v, pred, new) is applied to
  a split v that cannot accomodate an additional child, then pred
  (or the original first child, if pred = NIL) is deleted from the
  split and discarded.  The precise semantics are defined by the
  individual splits.  Insert raises NotAChild if pred isn't a
  child of v, and is a checked run-time error if new isn't detached.
  


PROCEDURE Move(v: T; pred, ch: VBT.T)
RAISES {NotAChild}; <* LL.sup = VBT.mu *>

 Move child ch of v to follow pred.  Both ch and (if non-NIL)
   pred must be children of v.  

PROCEDURE AddChildArray(v: T;
  READONLY new: ARRAY OF VBT.T);
<* LL.sup = VBT.mu *>

 Insert the non-NIL elements of new at the end of the v's
   list of children.  
 AddChildArray is equivalent to



       pred := Pred(v, NIL);
       FOR i := 0 TO LAST(new) DO
         IF new[i] # NIL THEN
           InsertAfter(v, pred, new[i]);
           pred := new[i]
         END
       END
 


PROCEDURE AddChild(v: T;
  v0, v1, v2, v3, v4, v5, v6, v7, v8, v9: VBT.T := NIL);
<* LL.sup = VBT.mu *>

 Add the given children to v. 
 AddChild is equivalent to

       AddChildArray(v,
         ARRAY OF VBT.T{v0, v1, ..., v9})



END Split.