ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE Lists;

  (*******************************************************************

    Module  Lists     (Version 1.0)

      Copyright (c) 1989-2006 by Olivier Roth, Andreas Fischlin and
      ETH Zurich.

    Purpose   Management of lists, interactive item selection.

    Remarks   --


    Programming

      o Design
        Olivier Roth              20/12/1989

      o Implementation
        Olivier Roth              07/01/1990
        Andreas Fischlin          04/08/1991


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  02/09/1991  AF

  *******************************************************************)


  FROM SYSTEM       IMPORT ADDRESS;
  FROM DMWindows    IMPORT Window, RectArea;


  TYPE
    List;

    SelectionMode = (single, multipleAdjacent, multipleDisconnected);
      (* how to select in the list item selector box:
       *    single               = only one or no item may be selected,
       *                           (click with shift key or drag),
       *    multipleAdjacent     = several sequential items may be selected
       *                           (click with shift key or drag),
       *    multipleDisconnected = several not adjacent items may be selected
       *                           (click and/or drag with shift key).
       *)

    DispListItemProc = PROCEDURE ( ADDRESS, INTEGER, INTEGER );
      (* the procedure is used to display one item in the list's item
       * selector box, the item is referenced by the first argument, the
       * other two arguments are the lower left coordinates of the item's
       * cell in the list item selector box. *)

    ItemSelection = ( selected, notSelected, all );

    ListItemProc = PROCEDURE ( ADDRESS );
                                                (* item *)

    ListItemWhileProc = PROCEDURE ( ADDRESS, VAR BOOLEAN );
                                                (* item,    continue *)

    IsSuccessorProc = PROCEDURE ( ADDRESS, ADDRESS  ): BOOLEAN;
                                                   (* item1,    item2,     item2 > item1 *)

    ConditionProc = PROCEDURE ( ADDRESS ): BOOLEAN;
                                                 (* item *)


  VAR
    noList: List;  (* read only variable! *)



(* List MAINTENANCE: *)
(* ----------------- *)

  PROCEDURE DeclList  ( VAR list: List;  listName: ARRAY OF CHAR );
    (* installs a new "list", ready to take an unlimited number of
     * items. *)

  PROCEDURE RemoveList( VAR list: List );
    (* deletes an installed "list" with all its inserted items and
     * frees the occupied memory. *)

  PROCEDURE ListExists( list: List ): BOOLEAN;
    (* returns TRUE if "list" has been installed. *)


  PROCEDURE InsertInList  ( list: List;  aListItem, beforeItem: ADDRESS );
    (* inserts "aListItem" before "beforeListItem" in "list". *)

  PROCEDURE DeleteFromList( list: List;  VAR aListItem: ADDRESS );
    (* deletes "aListItem" from "list" and frees the used memory. *)

  PROCEDURE ListItemExists( list: List;  listItem: ADDRESS ): BOOLEAN;
    (* returns TRUE if "listItem" exists in "list". *)



  PROCEDURE DoWithListItems( list: List;
                             doWith: ItemSelection;
                             doSomething: ListItemProc );
    (* the procedure "doSomething" is executed on all items which are
     * selected, not selected or all depending on "doWith" of "list". *)

  PROCEDURE DoWithListItemsWhile( list: List;
                                  doWith: ItemSelection;
                                  doSomething: ListItemWhileProc );
    (* similar to DoWithListItems; however the processing is only
     * done while the BOOLEAN input/output parameter passed as the
     * second argument of doSomething, i.e. the continue flag, stays
     * TRUE. As soon as doSomething sets this flag to FALSE, any
     * processing is immediately stopped.  Note that initially, i.e.
     * before processing the very first element in the list, this
     * procedure sets the continue flag to TRUE (given it is not also
     * the very last element) and when the last element in the list
     * is about to be processed, the continue flag has again the
     * value FALSE and indicates that there are no more elements
     * available in the list (looks ahead). *)



  PROCEDURE SortList( list: List;  isSuccessor: IsSuccessorProc );
    (* this procedure allows to sort the "list" by means of the comparison
     * procedure "isSuccessor" into any imaginable order inherent to the items
     * in the list.  isSuccessor should return true if according to
     * the ordering rules the second argument is a successor of the
     * first argument. *)



(* List Item Selector Box MAINTENANCE: *)
(* ----------------------------------- *)

  PROCEDURE InstallLISBox( list         : List;
                           window       : Window;
                           scrBFrame    : RectArea;
                           title        : ARRAY OF CHAR;
                           dispListItem : DispListItemProc;
                           cellW, cellH : INTEGER;
                           selMode      : SelectionMode  );
    (* installs a scrollable List Item Selector box" with the installed
     * "list" in the existent "window" at location "scrBFrame". On top
     * of this rectarea the "title" will be written in the currently
     * active font. At the right edge (outside) of the "scrBFrame" a
     * scroll bar is added (16 pixels wide). The list's content will be
     * drawn with the user defined procedure "dispListItem" one item after
     * the other. The area for the display for each item may be "cellW"
     * pixels wide and "cellH" high, other output is clipped.
     * "selMode" refers to one of the above defined selection modes, i.e.
     * (single, multiple adjacent, multiple disconnected).
     *
     * Implementation restriction:
     * only one list item selector box per list is allowed simultaneously.
     *
     * CAUTION:
     * do NOT overwrite the MouseHandler of type WindowContent, instead
     * append to it!
     *)

  PROCEDURE RemoveLISBox( list : List );
    (* clears the area in the window with the installed scrollable list
     * item selector box of "list". *)

  PROCEDURE RedrawLISBox( list : List );
    (* redraws the whole list item selector box for "list" in its current
     * state. *)


  PROCEDURE DeclLISBox     ( list         : List;
                           window       : Window;
                           scrBFrame    : RectArea;
                           title        : ARRAY OF CHAR;
                           dispListItem : DispListItemProc;
                           cellW, cellH : INTEGER;
                           selMode      : SelectionMode  );
    (* same as InstallLISBox but no drawing takes place.  Typically
     * used when SetScrollBarPlace, and SetLISBoxFraming etc. are used
     * to customize the list box. Call DrawLISBox afterwards to
     * actually draw the box.*)

  PROCEDURE SetLISBoxAttr( list: List;
                           title        : ARRAY OF CHAR;
                           dispListItem : DispListItemProc;
                           selMode      : SelectionMode  );

  PROCEDURE GetLISBoxAttr( list: List;
                           VAR title        : ARRAY OF CHAR;
                           VAR dispListItem : DispListItemProc;
                           VAR selMode      : SelectionMode  );
    (* these procedures allow to change some attributes of an already
         * installed LISBox. For argument's description see InstalllLISBox. *)

  PROCEDURE SetLISBoxFraming( li: List;     boxFramed: BOOLEAN );
  PROCEDURE GetLISBoxFraming( li: List; VAR boxFramed: BOOLEAN );
    (* Lets override the drawing of the frame around the list box
     * of an already installed LISBox. Note that this procedure will
     * also redraw the frame accordingly to the new settings. *)

  PROCEDURE SetScrollBarPlace( li: List; dx,dy,h: INTEGER );
  PROCEDURE GetScrollBarPlace( li: List; VAR dx,dy,h: INTEGER );
    (* these procedures allow to override the default positioning
     * of the scroll bar of an already installed LISBox. The values dx
     * dy denote an offset of the scrollbar relative to the lower
     * right corner of the scrBFrame. The default used by
     * InstallLISBox is dx = 0, dy = 0, and h = scrBFrame.h.
     * Note, the scrollbar will be redrawn at the new place, in case
     * it is already visible. *)


  PROCEDURE ScrollLISBox( li: List;  by: INTEGER );
    (* scrolls the list "li" forwards "by" lines if "by" is positive,
         * and backwards if "by" is negative". *)


  PROCEDURE FlipLISBox( li: List;  direction: BOOLEAN );
    (* scrolls the list "li" forwards pagewise if "direction" is TRUE,
         * and backwards if "direction" is FALSE". *)


  PROCEDURE EnableLISBox ( list: List );
  PROCEDURE DisableLISBox( list: List );
    (* no comment…, not implemented yet…for now *)



(* OPERATIONS on Items (of a List Item Selector Box): *)
(* -------------------------------------------------- *)

  PROCEDURE ToggleLISBoxItem( li: List;  item: ADDRESS;  shifted: BOOLEAN );
    (* toggles the selection status of the "item" of list "li" depending on
         * the list's SelectionMode, i.e. this procedure is the equivalent to
         * the interactive (un)shifted mouse click. *)

  PROCEDURE SetSelectionForAllIf (li: List; ifp: ConditionProc; isSelected: BOOLEAN);
    (* Sets for all items in the list li as the new selection status the value
     * of isSelected if and only if the procedure ifp returns TRUE.  The argument
     * of type ADDRESS passed to ifp is a pointer to the current item. *)
  PROCEDURE SetSelectionForAll (li: List; isSelected: BOOLEAN);
    (* Sets for all items in the list li as the new selection status the value
     * of isSelected unconditionally.  Typically this routine is used
     * to deselect or select all items in the list. *)


  PROCEDURE JumpToLISBoxItem( list: List;  item: ADDRESS );
    (* scrolls the list item selector box so that "item" of "list" becomes
         * the current top item. *)


  PROCEDURE TopLISBoxItem( list: List ): ADDRESS;
  PROCEDURE BotLISBoxItem( list: List ): ADDRESS;
    (* returns the item currently standing on top or at the bottom resp.
         * of the visible part of the "list"'s LISBox. *)


  PROCEDURE NextLISBoxItem( list: List;  item: ADDRESS ): ADDRESS;
  PROCEDURE PrevLISBoxItem( list: List;  item: ADDRESS ): ADDRESS;
    (* returns the item next/previous to "item" in the "list"'s LISBox.
         * NOTE: if the list has been sorted the next/previous item must'nt
         * be the next/previous of the installed order. If there is no other
         * item after/before the "item" then NIL is returned. *)


  PROCEDURE IsSelected( list: List;  item: ADDRESS ): BOOLEAN;
    (* returns TRUE if "item" in "list" is selected, otherwise FALSE.
         * If "item" and/or "list" are not valid FALSE is returned as well. *)


  PROCEDURE GetListItemSelection( list: List;
                                  VAR lis: ARRAY OF ADDRESS;
                                  VAR nSelected: INTEGER  );
    (* produces an array "lis" containing all items of "list" which are
     * currently selected (nSelected returns the number of selected
     * items). Make sure that HIGH(lis) suffices for all items! *)

  PROCEDURE SetListItemSelection( list: List;
                                  VAR lis: ARRAY OF ADDRESS;
                                  nSelected: INTEGER      );
    (* compares each item [0..nSelected] of "lis" (VAR parameter only for
     * efficiency) with the installed "list" and notifies items as selected
     * if found. If a list item selector box is currently installed for
     * that list then the visible part is updated.
     * If the installed list is in SelectionMode
     *  - single: only the first element of lis is selected
     *  - multipleAdjacent: only adjacent elements of lis starting with
     *    the first element are selected
     *  - multipleDisconnected: all elements of lis are selected as long
     *    as they are found in the installed list.
     *)


END Lists.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]