|
|
|
|
||
|
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.
|
||
|
|
|