Chapter

TVList Object Reference

This chapter contains a listing of all the classes, procedures, and types included in the TVList Unit.
TList	Abstract Class	TVList


TObject -> TCollection -> TList

TList is an abstract Class that extends the functionality of the TCollection Class.  It can be used to implment Lists or Collections of TObject objects or descendant objects.  It provides a structure for implementing TObjects with any data structure, and yet use these with TListBoxer, TListDialog, and TListDialogInputField objects.  It is also extended to provide simple editing adding, and deleting of list items.
See also: TCollection
	Methods	-------------------------------------------
	CreateItem	function CreateItem(Corner:Tpoint):pointer; virtual;
	Override:Often	Used to create List items to be inserted into TList.  Can be done with user defined dialog box or any other means.  Returns a nil pointer if no item was created.  Need no be redefined for each descendant class.  Deafault will simply return a nil pointer.  Only needs to be defined if the Add option will be used with TListDialog.  Corner will be passed by TListDialog in Absolute coordinates.  This is the requested location for any TDialog used.  User must determine if a dialog can be located at Corner.  The procedure MakeTrect() can be used for this purpose.
See Also: MakeTrect(), TPointAssign()
	EditItem	procedure EditItem(Corner:TPoint; Item:pointer); virtual;
	Override:Often	Used to edit List items.  Item is a pointer to a List item, a PObject or descendant type.  Editing can be with a dialog or someother means.    Corner will be passed by TListDialog in Absolute coordinates.  This is the requested location for any TDialog used.  User must determine if a dialog can be located at Corner.  The procedure MakeTrect() can be used for this purpose.
See also: MakeRect(), TPointAssign()
	GetItemText	function GetItemText(Item:pointer; MaxLen:integer):string; virtual;
	Override:Always	This returns a string that will be used to display a List item's data in a ListBoxer object.  Item is a pointer to the List item, ussually a PObject or descendant object.  The string returned should be MaxLen or less in length.  Must be redefined for each new Class.  Uses the abstract method to halt the program if not redefined.
See also: Abstract, TListBoxer.GetText, TListBox.GetText
	AtAddNewItem	function AtAddNewItem(Corner:TPoint; Index:integer):pointer;
	Override:Never	Adds a List item to the TList at the Index location.  Calls AtInsert(Index,CreateItem(Corner)).  Use EndOf Collection to add to the end of the List and 0 to add to the beginning of the list.  Called by TlistDialog.
See also: TListDialog
	MaxTextLength	function MaxTextLength:word;
	Override:Never	Returns the length of the longest GetItemText() in the List.  Uses ForEach().  Used to determine how wide a ListBox will have to be, so TListDialog can dynamically allocate a dialog size.

TSortedList	Abstract Class	TVList

TObject -> TSortedCollection -> TSortedList

TSortedList is an abstract Class that extends the functionality of the TSortedCollection Class.  It can be used to implment Lists or Collections of TObject objects or descendant objects.  It provides a structure for implementing TObjects with any data structure, and yet use these with TSortedListBoxer, TSortedListDialog, and TListDialogInputField objects.  It is also extended to provide simple editing adding, and deleting of list items.  It will insert items in the list in a sorted fashion.  In addition to the methods below, the KeyOf() and Compare() methods must also be defined.
See also: TSortedCollection
	Methods	-------------------------------------------
	CreateItem	function CreateItem(Corner:Tpoint):pointer; virtual;
	Override:Often	Used to create List items to be inserted into TSortedList.  Can be done with user defined dialog box or any other means.  Returns a nil pointer if no item was created.  Need not be redefined for each descendant class.  Deafault will simply return a nil pointer.  Only needs to be defined if the Add option will be used with TListDialog.  Corner will be passed by TSortedListDialog in Absolute coordinates.  This is the requested location for any TDialog used.  User must determine if a dialog can be located at Corner.  The procedure MakeTrect() can be used for this purpose.
See Also: MakeTrect(), TPointAssign()
	EditItem	procedure EditItem(Corner:TPoint; Item:pointer); virtual;
	Override:Often	Used to edit List items.  Item is a pointer to a List item, a PObject or descendant type.  Editing can be with a dialog or someother means.    Corner will be passed by TSortedListDialog in Absolute coordinates.  This is the requested location for any TDialog used.  User must determine if a dialog can be located at Corner.  The procedure MakeTrect() can be used for this purpose.
See also: MakeRect(), TPointAssign()
	GetItemText	function GetItemText(Item:pointer; MaxLen:integer):string; virtual;
	Override:Always	This returns a string that will be used to display a List item's data in a ListBoxer object.  Item is a pointer to the List item, ussually a PObject or descendant object.  The string returned should be MaxLen or less in length.  Must be redefined for each new Class.  Uses the abstract method to halt the program if not redefined.
See also: Abstract, TListBoxer.GetText, TListBox.GetText
	AtAddNewItem	function AtAddNewItem(Corner:TPoint):pointer;
	Override:Never	Adds a List item to the TList at the Index location.  Will place it in the List in sorted position.  Calls Insert(CreateItem(Corner)).    Called by TSortedListDialog.
See also: TSortedListDialog, TSortedCollection.KeyOf, TSortedCollection.Compare.
	MaxTextLength	function MaxTextLength:word;
	Override:Never	Returns the length of the longest GetItemText() in the List.  Uses ForEach().  Used to determine how wide a ListBox will have to be, so TSortedListDialog can dynamically allocate a dialog size.

TListBoxer	Class	TVList

TObject -> TView -> TListViewer -> TListBox 
-> TListBoxer

TListBoxer is a simple descendant of TListBox.  It primarily wraps TlistBox.GetText around a call to TList.GetItemText.  It also passes control to its owner when the enter key or a double mouse click is used to select an item.
	Methods	-------------------------------------------
	GetText	function GetText(Item:Integer; MaxLen:integer):string; virtual;
	Override:Seldom	Calls PList(List)^.GetItemText(List^.At(Item),MaxLen);
See also: TListBox.GetText
HandleEvent		procedure HandleEvent(var Event:TEvent); virtual;
	Override:Seldom	Traps Enter key and cmListItemSelected before calling TListBox.HandleEvent.
See also: TListBox.HandleEvent


TSortedListBoxer	Class	TVList

TObject -> TView -> TListViewer -> TListBox 
-> TListBoxer -> TSortedListBoxer

TSortedListBoxer is a simple descendant of TListBox.  It primarily wraps TSortedlistBox.GetText around a call to TSortedList.GetItemText.  It also passes control to its owner when the enter key or a double mouse click is used to select an item.

	Methods	-------------------------------------------
	GetText	function GetText(Item:Integer; MaxLen:integer):string; virtual;
	Override:Seldom	Calls PList(List)^.GetItemText(List^.At(Item),MaxLen);
See also: TListBox.GetText

TListDialog	Class	TVList

TObject -> TView -> TGroup -> TWindow 
-> TDialog -> TListDialog

TListDialog is a highly tuned Dialog to be used with TList objects to display a TList in a ListBox.  It can serve a variety of functions.  It can be used to simply display the items in a Tlist object with a ListBox, it can be used to select items from a Tlist Object with a ListBox, it can be used to edit, add, and or delete items from a TList object using a ListBox.  The intent of this Class is to provide a well supported and flexible user interface for TList objects that requires little redefinition, and can be setup and executed with a minimal amount of code and support.

TListDialog inserts at a minimum a TListBoxer, an cmOK TButton, and a cmCancel TButton.  Based on the values passed in Behavior with Init, an Add TButton, Edit TButton, and/or Delete TButton are also provided.  The size and location of the TDialog object can be dynamically calculated by Init.

TlistDialog has the following properties:

o	Enter key is trapped and used to select a highlighted item in the listbox when the listbox is selected or select a button.
o	Up and Down Cursor keys can be used to scroll the List Box or move from Button to Button in the dialog box.
o	Esc key or Cancel button generates a cmCancel evCommand event.  Item Selected from List Box is not returned, BUT any items added, edited, or deleted will not be restored to their state when the dialog was executed.
o	Double Click of the mouse in the ListBox selects the item.
o	All other default properties of TDialog objects remain.
The behavior of the Dialog is controlled by the AB field which can set with the Behavior parameter with in init constructor.  The bits of the AB behavior field are defined as follows:

msb          lsb
[][][][][][][][]    Constants
    | | | | | |
    | | | | | `---- sfAdd	= $01
    | | | | `------ sfDelete	= $02
    | | | `-------- sfEdit	= $04
    | | `---------- sfSearch	= $08
    | `------------ sfPromptDelete	= $10
    `-------------- SfPromptExit	= $20


Two general purpose constant masks are:
    sfFullEdit = sfAdd + sfDelete + sfEdit;
    sfDoall  = $FF;

With sfAdd bit set TListDialogs will insert a ADD button in the dialog.  Slection of this button will call TList.CreateItem.  If this has not be redefined, then nothing happens.

With sfDelete bit set TListDialogs will insert a DELETE button.  Selection of the button will delete the currently selected item in the list box.

With sfEdit bit set TListDialogs will insert an EDIT button in the dialog.  Selecting this button will call TList.EditItem.  If this is not defined then nothing happens.

If using a TSortedList with TSortedList (see Below), with the sfSearch bit set the Dialog will allow keystrokes to be used to do an incremental search of the Tlistbox when the listbox is selected.  As each key is pressed the search string is displayed on a search line and the TListbox moves the focus to the item that most closely matches the search string.  Using the backspace key will delete keys from the searchline.

With the sfPromptDelete bit set, the dialog will promote for approval before a Delete is preformed.

With the sfPromptExit bit set, the dialog will move to the OK button on a selection from the List box.  This provides a way to verify a selection before exiting the dialog.  With this bit unset, selecting an item in the list box (with the mouse or pressing enter) exits the dialog.

	Fields	-------------------------------------------
	AB	AB : byte;	Read only
This is used to determine what the behavior of the Dialog will be.  See definition of mask bits above.

See also: TListDialog.Init
	TLR	TLR:TListRec;	Read only
This is used to store the index and pointer of the focused item in ListBox when the dialog is closed after selecting an item from the ListBox.
	Max	Max:byte;	Read only
The is the Maximum width of the GetItemText with in the List being used.
	List	List:pointer;	Read only
This is a pointer to a Plist object that has been initialized.
	LB	LB:PlistBox;	Read only
This is a pointer to the ListBoxer being used to display the List.
	X,Y	X,Y:word;	Read only
This is the location of a status line used by the Dialog.  This is used to locate where the ListBox header will be located.  This is also used by TSortedListDialog to display the active search string.
	SearchString	SearchString:PString;	Read only
This is the current string being used to incrementally search through List.

	Methods	-------------------------------------------
	Init	constructor Init(var Bounds:Trect; ATitle:TTitleStr; Behavior:byte; TheList:PList; BoxHeader:TTitleStr);
	Override:Never	Bounds is the location and size of the desired dialog box.  This may be resized and reloacted if sufficient room is not provided.  If bounds is assigned with Bounds.assign(X,Y,0,0) then a dialog box is opened with upper left corner at XY and with a listbox of 4 lines and sized to accomodate all behavior buttons.  ATitle will be used for the Dialogs title.  Behavior is a set of flags that can be passed to activate certain functions in the Dialog box.  TheList is the list! This is a PLIST class instances that contians a list of data records.  BoxHeader is an optional string that will be used a Tlabel for the ListBox.  This can be useful if the GetItemText() string actually contains data from multiple fields.  BoxHeader can be used to label these fields.
See also: AB

	DataSize	function DataSize: word; virtual;
	OverRide:Never	Default is to return sizeof(TListRec). 
	GetData	procedure GetData(var rec); virtual;
	OverRide:Never	Default is to return a pointer to a TListRec data type.  Returns a TListRec datatype where TListRec.item is a pointer to the selected object in the List, if the Dialog concluded with a cmOk command.  Returns a nil pointer in TListRec.Item otherwise.  TListRec.Index provides the index to the item that was selected.
	SetData	procedure SetData(var rec); virtual;
	OverRide:Never	Default is to move a TListRec into Rec.
	HandleEvent	procedure HandleEvent(var Event:TEvent); virtual;
	Override:Seldom	Handles interaction between ListBox and Dialog 

TSortedListDialog  Class	TVList

TObject -> TView -> TGroup -> TWindow 
-> TDialog -> TListDialog 
-> TSortedListDialog

Provides same functions of TListDialog, but is used with TSortedList object.  TSortedListDialog can provide incremental scrolling of the list box based on a search string.  While the ListBox is active, a string can be entered from the key board.  As each key is detected, the ListBox is searched for the closest matching string.  When this search feature is active, the spacebar can not be used to select from th ListBox.
	Methods	-------------------------------------------
	Init	constructor init(var Bounds:Trect; ATitle:TTitleStr;Behavior:byte; TheList:PSortedList; BoxHeader:TTitleStr);
		Same as PListDialog.init except TheList is a PSortedList class.
See also: TListDialog.init
	HandleEvent	procedure HandleEvent(var Event:TEvent); virtual;
	Override:Seldom	Handles interaction between ListBox and Dialog  similar to TlistDialog, but also provides for an incremental search of ListBox based on a searchstring entered from the keyboard.
See also: TListDialog.HandleEvent


TListDialogInputField  Class

TObject -> TView -> TInputLine 
-> TListDialogInputField

This class is a descendant of TInputline, however it does no allow entry of data.  It is used to execute a TListDialog or TSortedListDialog from within another dialog.  It is inserted into a dialog just like anyother TInputLine object.  When the dialog is executed this field displays the string value of item at the position set by setdata.  When this field is selected, pressing the Ins key or the right or left arrow keys will execute a Tlist dialog.  After this TList dialog is closed, this field will display the item selected in the TList Dialog.  IT provides a convient way to insert ListBoxes in dialogs with out taking up a lot of screen space.

	Fields	-------------------------------------------
	TD	TD:pointer;   	Read Only
Pointer to TListDialog
	TL	TL:pointer;	Read Only
Pointer to TList
	Max	Max:byte;	Read Only
Maximum string value returned by TL^.GetItemText
	Index	Index:word;	Read Only
Index of Listbox, Set by SetData
	Sorted	Sorted:boolean;	Read Only
Indicates that TL is a TSortedList object pointer.
	Methods	-------------------------------------------
	Init	constructor init (Field:TPoint; ListLocation:Tpoint; ListHeight:word; Title:String; Behavior:byte; AList:Pointer; BoxHeader:string; SortedList:boolean);
	Override:Seldom	Field is the left X,Y of the location in the dialog.  ListLocation is the X,Y location relative to the Field location where the TlistDialog should be located.
	DataSize	function  DataSize:word; virtual;
	Override:Seldom	Default returns a value of 2
	GetData	procedure GetData(Var Rec); virtual;
	Override:Seldom	Default moves a word size value into Rec from the Index field.
	SetData	procedure SetData(Var Rec); virtual;
	Override:Seldom	Deafault moves a word size value from Rec into the Index field.
	HandleEvent	procedure HandleEvent(var Event:TEvent); virtual;
	Override:Seldom	Handles user input.  kbEnter is translated to a kbTab.  kbIns, kbRight, and kbLeft and mouse double click executes the TListDialog.

RegisterTVList	procedure
	Declaration	procedure RegisterTVList;
	Function 	Registers TList and TSortedList objects.  ObjType codes are TList, 2000 and TSortedList 2001

The IDs used to register TV objects are
  TList 	200
  TSortedList	201

MakeRect	procedure
	Declaration	procedure  MakeRect(Corner:Tpoint; Xsize,YSize:integer; var Bounds:Trect);
	Function 	This procedure takes Corner, which should be in global coordinates, and trys to create a Rectangle with an upper left Corner and is XSize wide and YSize high.  If this is not possible, it will try and adjust Corner to a location where such a rectangle can be displayed.  Failing that it will create the Largest Rectangle that can be displayed.
TPointAssign	procedure
	Declaration	Procedure TPointAssign(var P:TPoint; X,Y:integer);
	Function 	This procedure simply assigns X,Y to the Tpoint object, easier than P.X := X; P.Y:=Y;

TListRec	type

	Declaration	TListRec = record
   Item:pointer;
   Index:integer;
   end;
	Function	Data type used with TListDialog and TSortedListDialog methods GetData and Setdata.  Item points to the item which was selected from the dialogs list box on exit.  Index is its index into the list.

TVList	

TVList