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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib