ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/PASCAL/TOTDOC.ZIP/CHAPT9.TXT

Text File | 1991-02-10 | 83.6 KB | 2,168 lines

                                                                        Managing
                                                                           Lists


         "Three questions are essential... What is the author's object? How far
         has he accomplished it? How far is that object worthy of approbation?

                                                              Nathanial P Willis



Introduction
         Lists, lists, lists. Our lives and our software are often dominated by
         lists. The Toolkit provides three powerful units to help you manage
         software lists. (Your lives are your own responsibility!)

         In this chapter, the totLINK and totLIST units are discussed in detail.
         totLINK provides objects to help you maintain and sort large lists, and
         totLIST provides objects for displaying lists and arrays in windows.
         A common form of software list is a file directory list. The Toolkit
         provides two flexible directory displaying objects, and these are dis-
         cussed in the next chapter.



Array and Linked List Theory
         One-dimensional arrays provide a very quick and convenient way of
         managing lists. An array is a data structure designed to store data
         about a fixed number of identical elements. For example, the following
         variable could be used to store the address of my two sisters' and
         three brothers' addresses:

                  Addresses: array [1..5] of string;
         Data in the array is accessed by specifying the element number. For
         example, the following statement would update my second sister's
         address:

                  Addresses[2] := "38 The Ridgeway, Friern Barnet, London"

         Arrays are very easy to create, but suffer from two major weaknesses:

         q     The size of an array is fixed at compile time. In other words, in
               your source code you must explicitly state the size (or bounds)
               of the array. In our simple example, this was not a problem
               because I have only five siblings. Imagine, however, that you
               need to write a generic name and address program. You don't know
               how many names and addresses will be required, but you must spec-
               ify the number in your program. The typical solution is to choose
               a large number of elements (e.g. 200) and hope that the user
               doesn't need more. Not only does this set a limit on the pro-
               gram's capacity, it also wastes memory if the maximum number of

9-2                                                                 User's Guide
--------------------------------------------------------------------------------

               elements are not used. Turbo Pascal automatically allocates the
               memory for the entire array regardless of how many elements are
               actually used. Which leads us to the second shortcoming.

         q     The maximum size of a program's data segment in Turbo Pascal is
               64k. This means that the sum of all the program's global vari-
               ables cannot exceed 64k, and, therefore, no individual data
               structure can exceed 64k. In our example, each element of the
               array consumed 256 bytes, so 256 of these elements would consume
               the entire data segment leaving no room for other global vari-
               ables.


         Linked lists do not suffer from these shortcomings. With a linked list,
         each element is stored independently. The first element in the list
         includes a pointer indicating where the second element in the list is
         stored. The second element in the list includes a pointer to the loca-
         tion of the third element in the list, and so on. When you reach an
         element in the list that points to NIL, you know you have reached the
         end of the list. You do not need to fix the maximum number of elements
         in the list at compile time. Furthermore, the data is stored on the
         heap (not in the data segment) and so is not limited to 64k. The list
         can use all of the available memory.
         Although linked lists are very flexible, they can prove complicated to
         program and manage. Fortunately, the Toolkit provides a very powerful
         object which makes managing linked lists a breeze.



Managing Linked Lists
         The totLINK unit includes the object DLLOBJ. This object provides a
         variety of methods for creating and managing linked lists. If you are
         interested, DLLOBJ actually maintains a doubly-linked list. Each ele-
         ment in the list points to the next element and the previous element.
         This is more efficient when you need to move up and down the list.

         The DLLOBJ object is designed to store raw data, i.e. untyped vari-
         ables. This allows you to store literally any data in a DLLOBJ object.
         It is important to note that DLLOBJ is an abstract object and you
         should not create any instances of type DLLOBJ.
         In this chapter, we will concentrate on a descendant object, StrDLLOBJ,
         designed specifically to manage lists of strings. If you want to create
         objects which manage other data types, all you have to do is create an
         object descended from DLLOBJ. In part 2: Extending the Toolkit, there
         is a chapter describing how to create other descendants of DLLOBJ to
         manage specific data types. By way of an example, it describes how to
         create a linked list object for managing records.



Managing Lists                                                               9-3
--------------------------------------------------------------------------------

         Before exploring the StrDLLOBJ methods, you need to understand some
         doubly-linked-list jargon. Each element in the list is referred to as a
         node. Behind the scenes, the Toolkit keeps track of the location of the
         first node in the list, the last node in the list, and the node that
         was last accessed. The last-accessed node is referred to as the active
         node.


Creating a List

         To create a linked list, you must declare an instance of type StrDLLOBJ
         and then call the Init and Add methods. The syntax of these methods is
         as follows:

         Init;

         This method initializes the object and must be called before the other
         methods.

         Add(Str:string): integer;

         This function method creates a new node in the linked list and stores
         it in the string Str. The node is actually created immediately follow-
         ing the active node. Once the node has been added, the active node is
         moved to point to it. The function returns an integer code - a 0
         indicates success, a 1 indicates there was insufficient memory to
         create the node, and a 2 indicates there was enough memory to create
         the node, but too little memory to store the string.

         Ordinarily, to populate a list, all you have to do is call Init, and
         then make multiple calls to Add. Listed below is an extract of the demo
         program, DEMLK1.PAS, which stores a list of names in a linked list.

         var
           GirlFriends: StrDLLOBJ;
           Retcode: integer;
         begin
            with GirlFriends do
            begin
               Init;
               Retcode := Add('Erica');
               if Retcode <> 0 then exit;
               Retcode := Add('Theresa');
               if Retcode <> 0 then exit;
               Retcode := Add('Lynn');
               if Retcode <> 0 then exit;
               Retcode := Add('Donna');
               if Retcode <> 0 then exit;




9-4                                                                 User's Guide
--------------------------------------------------------------------------------

               Retcode := Add('Godzilla');
               if Retcode <> 0 then exit;
               {....}
            end;
         end.


         To save checking the value of Retcode every time you add a node, you
         might check that there is enough memory available for all the nodes,
         and ignore the return code, as follows:
         var
            GirlFriends: StrDLLOBJ;
            Retcode: integer;

         begin
            with GirlFriends do
            begin
               Init;
               if maxavail > 200 then
               begin
                  Retcode := Add('Erica');
                  Retcode := Add('Theresa');
                  Retcode := Add('Lynn');
                  Retcode := Add('Donna');
                  Retcode := Add('Godzilla');
                  {...}
               end;
            end;
         end.

         In fact, if you are using Turbo Pascal 6.0 and the extended compiler
         directive {$X+} has been set, you can ignore the function return value,
         as follows:

         {$X+}
         var
            GirlFriends: StrDLLOBJ;
         begin
            with GirlFriends do
            begin
               Init;
               if maxavail > 200 then
               begin
                  Add('Erica');
                  Add('Theresa');
                  Add('Lynn');
                  Add('Donna');
                  Add('Godzilla');



Managing Lists                                                               9-5
--------------------------------------------------------------------------------

                  {...}
               end;
            end;
         end.


Maintaining a List

         Once you have created a list, the following methods can be used to
         navigate the list:

         TotalNodes: longint;

         This function method returns a longint identifying the total number of
         nodes in the list.

         ActiveNodeNumber: longint;

         Returns the position of the active node.

         Jump(NodeNumber: longint)

         This method moves the ActiveNodePtr to the specified node number. Add
         inserts a node after the active node pointer. So, to insert a node
         anywhere in the list, call the method Jump to move the active node
         pointer and then call Add.

         Advance(Amount: longint);

         Moves the active node down the list the specified number of nodes. If
         there are insufficient nodes, the active node pointer is moved to the
         end of the list.

         Retreat(Amount: longint);

         Moves the active node up the list the specified number of nodes. If
         there are too few nodes, the active node pointer is moved to the begin-
         ning of the list.



Advanced List Management

         In many programs, all you'll need to do is create a list, add items to
         the list, and then display the list using one of the browse or list
         displaying objects (discussed later). However, if you want to delete
         items from the list, swap the positions of two items in the list, or
         change an item in the list, you will need to access the nodes in the
         list directly.


9-6                                                                 User's Guide
--------------------------------------------------------------------------------

         Each node in the list is actually a DLLNodeOBJ object, and many of the
         list manipulation methods access a pointer to the node known as a
         DLLNodePtr.

         Without worrying about the details, all you need to know is how to
         determine the value of DLLNodePtr for any given node. The following
         four function methods serve this purpose:

         NodePtr(NodeNumber:longint): DLLNodePtr;

         Pass this function a node number, and it will return a pointer to the
         node.

         ActiveNodePtr: DLLNodePtr;

         Returns a pointer to the active node.

         StartNodePtr: DLLNodePtr;

         Returns a pointer to the first node in the list.

         EndNodePtr: DLLNodePtr;

         Returns a pointer to the last node in the list.

         Having established the DLLNodePtr value, the following methods can be
         used to manipulate the node data:


         Change(Node:DLLNodePtr;Str:string):integer;
         Changes the value at the node to Str. This function method returns an
         integer to indicate whether the change was a success: 0 indicates suc-
         cess, 2 indicates insufficient memory for the data, and 3 indicates an
         invalid node pointer.


         DelNode(Node:DLLNodePtr);
         Deletes the node.


         SwapNodes(Node1,Node2:DLLNodePtr);
         Swaps the data assigned to the two nodes.


         InsertBefore(Node:DLLNodePtr; Str:string);




Managing Lists                                                               9-7
--------------------------------------------------------------------------------

         Inserts a new node immediately before the specified node. (The Add
         method inserts the data after the active node.) This method provides a
         way of inserting a node at the very beginning of the list. After this
         method has been called, the active node pointer is set to the first
         node in the list.


         GetStr(Node:DLLNodePtr; Start,Finish:longint): string;
         This function returns a sub-string of the data stored at the specified
         node. The parameters Start and Finish indicate the starting and ending
         characters to be extracted in the string. For example, values of 6 and
         10 will return five characters commencing with the character in posi-
         tion 6 of the string. Pass values of zero for the Start and Finish
         parameters, if you want the entire string.


         Sort(SortID: shortint; Ascending: boolean);
         This powerful method rearranges the order of all the nodes in a list,
         i.e. it sorts the list. The sort routine is generic and can be utilized
         by any descendant of the DLLOBJ object. In the case of StrDLLOBJ, the
         first parameter has no meaning, and should be set to one. If you want
         the list sorted in ascending order (i.e. lowest first), pass TRUE as
         the second parameter, otherwise pass FALSE.


         Listed below is the demo program DEMLK2.PAS which illustrates many of
         the methods discussed thus far. Figure 9.1 shows the generated output.
         Program DemoLinkTwo;
         {DEMLK2 - creating a linked list}

         Uses CRT,
              totLink;
         var
            GirlFriends: StrDLLOBJ;
            Retcode: integer;
            I : integer;

         begin
            ClrScr;
            with GirlFriends do
            begin
               Init;
               if maxavail > 200 then
               begin
                  Retcode := Add('Erica');
                  Retcode := Add('Theresa');
                  Retcode := Add('Lynn');
                  Retcode := Add('Donna');
                  Retcode := Add('Godzilla');


9-8                                                                 User's Guide
--------------------------------------------------------------------------------

                  writeln('Total nodes: ',TotalNodes);
                  writeln('Active node number: ',ActiveNodeNumber);
                  for I := 1 to TotalNodes do
                      writeln(GetStr(NodePtr(I),0,0));
                  writeln;
                  RetCode := InsertBefore(NodePtr(4),'Joyce');
                  writeln('Total nodes: ',TotalNodes);
                  writeln('Active node number: ',ActiveNodeNumber);
                  SwapNodes(NodePtr(5),NodePtr(2));
                  Retcode := Change(StartNodePtr,'Ekka');
                  for I := 1 to TotalNodes do
                      writeln(GetStr(NodePtr(I),0,0));
                  writeln;
                  writeln('Sorted:');
                  Sort(1,true);
                  for I := 1 to TotalNodes do
                      writeln(GetStr(NodePtr(I),0,0));
               end;
            end;
         end.


Figure 9.1                                                              [SCREEN]
Using
StrDLLOBJ



Removing a List
         Calling the method Done will always dispose of all the memory consumed
         by a list. A list can also be emptied with the following method:


         EmptyList;
         Removes all the memory allocated on the heap by chaining back through
         the list and disposing of each node. The ActiveNodePtr, StartNodePtr
         and EndNodePtr are set to nil, and TotalNodes is set to nil.



Comparing StrDLLOBJ to Arrays
         If you have never used linked lists before, but you have used arrays,
         you might be interested in comparing array commands with StrDLLOBJ com-
         mands. Table 9.1 compares the command syntax by manipulating a list of
         5 names.


                        StrDLLOBJ                        String Array



Managing Lists                                                               9-9
--------------------------------------------------------------------------------

           Declaring the Variable or Instance
           var NameList: StrDLLOBJ;            var NameList: array[1..5] of
                                               string;

           Initializing the List
           NameList.Init;                      fillchar(NameList,sizeof(NameLis
                                               t),#0);
           Populating the List
           with NameList do                    NameList[1] := 'Mark';
           begin                               NameList[2] := 'Kirk';
              Retcode := Add('Mark');          NameList[3] := 'Lloyd';
              Retcode := Add('Kirk');          NameList[4] := 'Charles';
              Retcode := Add('LLoyd');         NameList[5] := 'Keith';
              Retcode := Add('Charles');
              Retcode := Add('Keith');
           end;

           Writing an item to the display
           with NameList do                    writeln(NameList[3]);
            writeln(GetStr(NodePtr(3),0,0));

           Swapping two items
           with NameList do                    Temp := NameList[4];
            SwapNodes(NodePtr(4),NodePtr(5));  NameList[4] := NameList[5];
                                               NameList[5] := Temp;

           Sorting the List
           NameList.Sort(1,true);              Ugh!

           Erasing the Entries
           NameList.EmptyList;                 fillchar(NameList,sizeof(NameLis
                                               t),#0);



         Don't forget that the StrDLLOBJ is much more memory efficient, and is
         not limited to a set number of elements.

         Much of the power of DLLOBJ is not realized until you create descendant
         objects, customized for your specific needs. Refer to Part 2: Extending
         The Toolkit for further details.


Browse Lists

         Whether your data is in a DLLOBJ (or descendant) object, or in a string
         array, you will want to take advantage of the Toolkit's objects for



9-10                                                                User's Guide
--------------------------------------------------------------------------------

         automatically displaying lists in windows. In this section, the Brow-
         seOBJ family of objects will be discussed. These objects display lists
         in a scrollable window.


           Note that a browse window does not include a highlight bar. The
           user browses the contents of the list, but does not select an
           individual element. The ListOBJ family (discussed in the next sec-
           tion) provides objects for highlighting individual elements in a
           list.



         Figure 9.2 shows the object hierarchy for the BrowseOBJ family. The
         base object BrowseOBJ is abstract, and you should not create any
         instances of this type. The BrowseArrayOBJ object displays the contents
         of a string array, and the BrowseLinkOBJ displays the contents of an
         object in the DLLOBJ family. Many programs need to display the contents
         of ASCII files, and the object BrowseFileOBJ makes this a snap.

Figure 9.2                                                             [PICTURE]
BrowseOBJ
Object Hierarchy




Common Methods
         The totLOOK unit includes an object LookTOT which is used to control
         the overall look and feel of applications developed with the Toolkit.
         Call the method LookTOT^.SetListKeys to change the keys which the user
         can press to close the browse window. The defaults are [KEYCAP] and
         [KEYCAP]. Refer to page 3-12 for further details.

         Because all the objects are derived from the BrowseOBJ, they share a
         set of common methods. The following methods can be used with any of
         the browse objects:

         SetTopPick(TopPick: longint);

         This method identifies the node number of the first node that will be
         displayed in the list window.

         SetStartCol(Column: longint);

         This method identifies the character position of the first character of
         the string which is visible in the list window.




Managing Lists                                                              9-11
--------------------------------------------------------------------------------

         SetEndCol(Column: longint);

         This method sets the maximum lateral scrolling by identifying the last
         column which will be displayed when the window is scrolled to the right
         maximum. All lateral scrolling can be disabled by calling the Stretch-
         WinOBJ method SetScrollable (discussed later).

         Show;

         This method displays the list and immediately returns control back to
         the calling procedure, i.e. the Toolkit does not wait for user input.
         This option is useful if you want to display the list on the screen,
         but not activate it.

         Go;

         This method is the main "do it" method. If the list is not on display,
         it is drawn. The Toolkit then processes user input until an end key is
         pressed.

         LastKey:word;

         LastKey returns the key code of the key the user pressed to end the
         browse session. This is used if you need to know whether the user
         escaped or pressed the finish key.

         Done;

         As always, Done disposes of the Browse window object, and should always
         be called when the object is no longer required.


Modifying the Window Characteristics

         The list data is displayed in a window of type StretchWinOBJ. You can
         modify any window attribute by directly calling the StretchWinOBJ meth-
         ods. BrowseOBJ includes a function method, Win, which returns a pointer
         to the StretchWinOBJ instance. To modify the window, call the
         appropriate StretchWinOBJ method using the following syntax:
                  [BrowseOBJInstance].Win^.method

         For example, the following statements would change the default window
         size, style and title:
                  var MyBrowser: BrowseLinkOBJ;

                  begin
                     with MyBrowser do
                     begin


9-12                                                                User's Guide
--------------------------------------------------------------------------------

                        Init;
                        Win^.SetSize(1,1,50,20,3);
                        Win^.SetTitle('My Browser');
                     end;
                  end.


         All the display colors used by the browse objects are controlled by the
         underlying window attributes. To change the browse display colors call
         the window method SetColors, e.g.
                  Win^.SetColors(23,23,31,30);


         Call Win^ methods to set all the browse window characteristics, e.g.
         colors, title, remove status, boundaries, etc. Refer to chapter 7:
         Using Windows for a thorough discussion of the StretchWinOBJ methods.


Browsing Arrays

         The BrowseArrayOBJ object provides a very simple way to browse the
         contents of a string array. In addition to the common methods just
         described, there is another method as follows:

         AssignList(var StrArray; Total:longint; StrLength:byte);

         AssignList identifies the string array that will be displayed. The
         three parameters are the string array, the total number of elements in
         the array, and the length of each string in the array. The string
         length parameter must reflect the string length of the array when it
         was declared, not the maximum length of any string assigned to the
         array.

         For example, if a string array was declared as follows:

                  MyGirls: array[1..54] of string;
         then the list is assigned with the following calls:

                  with MyBrowser do
                  begin
                     Init;
                     AssignList(MyGirls,54,255);
                     {...}
                  end;



Managing Lists                                                              9-13
--------------------------------------------------------------------------------

         Having assigned the list, all you need to do is call Show and the
         browse window will pop onto the display. Listed below is a the demo
         program DEMBR1, followed by figure 9.3 illustrating the resultant dis-
         play.

         Program DemoBrowseArrayOne;
         {SEMBR1}
         Uses DOS,CRT,
              totINPUT, totFAST,totLIST, totSTR;

         var
            BWin: BrowseArrayOBJ;
            StringList: array[1..26] of string[100];
            I : integer;
         begin
            for I := 1 to 26 do  {first assign something to the string array}
               StringList[I] := 'Line '+
                                IntToStr(I)+': '+
                                replicate(80,char(I+64));
            Screen.Clear(white,'░'); {paint the screen}
            Key.SetFast;
            Key.SetClick(true);
            with BWin do
            begin
               Init;
               AssignList(StringList,26,100);
               Go;
               Done;
            end;
         end.


Figure 9.3                                                              [SCREEN]
Browsing an
Array


         The demo program DEMBR2.PAS, listed below, is very similar to
         DEMBR1.PAS. The only difference is that two Win^ methods are called to
         modify the default window settings. Figure 9.4 shows the impact on the
         display.
         Program DemoBrowseArray;

         Uses DOS,CRT,
              totFAST,totLIST, totSTR;



9-14                                                                User's Guide
--------------------------------------------------------------------------------

         var
            BWin: BrowseArrayOBJ;
            StringList: array[1..26] of string[100];
            I : integer;
         begin
            for I := 1 to 26 do  {first assign something to the string array}
               StringList[I] := 'Line '+
                                IntToStr(I)+': '
                                +replicate(80,char(I+64));
            Screen.Clear(white,'░'); {paint the screen}
            with BWin do
            begin
               Init;
               AssignList(StringList,26,100);
               Win^.SetSize(30,5,50,15,2);
               Win^.SetTitle('Array Browse Demo');
               Go;
               Done;
            end;
         end.


Figure 9.4                                                              [SCREEN]
Modifying the
Browse Window

Browsing Linked Lists
         The BrowseLinkOBJ is very similar to the BrowseArrayOBJ, the primary
         difference being that BrowseLinkOBJ displays the data stored in a
         DLLOBJ object rather than in an array.

         In addition to the common methods described, there are two additional
         methods as follows:

         AssignList(Var LinkList: DLLOBJ);

         This method is passed a DLLOBJ instance, or any instance of an object
         derived from DLLOBJ, e.g. StrDLLOBJ.

         ListPtr: DLLPtr;

         This method returns a pointer to the DLLOBJ used to create the list.
         You can access the linked list by using the syntax MyBrow-
         ser.ListPtr^.method.

         Listed below is the program DEMBR3.PAS, which illustrates how to build
         a large list of 500 items and display it in a browse window. Figure 9.5
         shows the browse display.



Managing Lists                                                              9-15
--------------------------------------------------------------------------------

         Program DemoBrowseList;

         Uses DOS,CRT,
              totFAST, totLINK, totLIST, totSTR;
         var
            BWin: BrowseLinkOBJ;
            LL : StrDLLOBJ;

         procedure CreateLinkedList;
         {}
         var
           I, Retcode : integer;
         begin
            with LL do
            begin
               Init;
               for I := 1 to 500 do
                  Retcode := Add('This is line '+IntToStr(I)+
                             ': '+replicate(200,char(random(255))));
            end; {with}
         end; {CreateLinkedList}
         begin
            Screen.Clear(white,'░'); {paint the screen}
            CreateLinkedList;
            with BWin do
            begin
               Init;
               AssignList(LL);
               Win^.SetTitle('List Browse Demo');
               Go;
               Done;
            end;
            LL.Done
         end.


Figure 9.5                                                              [SCREEN]
Browsing a
StrDLLOBJ


Browsing Files

         The BrowseFileOBJ object makes browsing ASCII text files easy. Browse-
         FileOBJ is descended from BrowseOBJ and inherits all the associated
         methods. In addition, the following method AssignFile is used to
         instruct the object on which file to display:



9-16                                                                User's Guide
--------------------------------------------------------------------------------

         AssignFile(Filename:string): integer;

         This function method is passed a string indicating the name of the file
         to be browsed. Behind the scenes, this function loads the file from
         disk into a temporary StrDLLOBJ object. The function will return a 0 if
         the file was successfully loaded. A return value of 1 indicates that
         the file was not found, and so cannot be displayed. A return value of 2
         indicates that there wasn't enough memory to load the entire file. In
         such an instance you may want to use a MessageOBJ to advise the user
         that only part of the file can be browsed.

         That's all there is to it! Just declare a BrowseFileOBJ instance and
         call the methods Init, AssignFile and Go:

                  var FileWin: BrowseFileOBJ;
                  begin
                     with FileWin do
                     begin
                        Init;
                        if AssignFile('Help.TXT') = 0 then
                           Go;
                        Done;
                     end;
                  end.

         The following method can be used to directly access the linked list
         created by the BrowseFileOBJ instance:


         ListPtr: StrDLLPtr;
         This method returns a pointer to the StrDLLOBJ used to create the list.
         You can access the linked list by using the syntax MyFile.ListPtr^.me-
         thod.


         Listed below is the example program, DEMBR4.PAS. This small program
         will display the contents of either a file specified on the command
         line when the program was executed, or (if no parameters were speci-
         fied) the contents of c:\autoexec.bat.


         Program DemoBrowseFile;
         Uses DOS,CRT,
              totFAST, totINPUT, totLINK, totLIST, totSTR;
         const
            DefaultFile = '\autoexec.bat';
         var



Managing Lists                                                              9-17
--------------------------------------------------------------------------------

            BWin: BrowseFileOBJ;
            RetCode: integer;
            Filename: string;

         begin
            Screen.Clear(white,'░'); {paint the screen}
            if ParamCount = 0 then
               FileName := DefaultFile
            else
               FileName := ParamStr(1);
            with BWin do
            begin
               Init;
               Retcode := AssignFile(Filename);
               if Retcode in [0,2] then
                  Go
               else
                  Writeln('Unable to load file: ',Filename,'.');
                  Key.DelayKey(2000);
               Done;
            end;
         end.



9-18                                                                User's Guide
--------------------------------------------------------------------------------

Selection Lists

         So far, this chapter has focused on browse windows, where the user can
         simply scroll data vertically and horizontally. By contrast, a list
         window is designed to display selectable items, much like a menu. One
         of the items within the list window is always highlighted, and the list
         may be organized into single or multiple columns. The scroll bars are
         used to move the item highlight bar. The list is removed when the user
         presses an end key such as [KEYCAP] or [KEYCAP], when the user presses
         [KEYCAP], or when the user double-clicks the mouse on an item.
         When appropriate, users may even select, or tag, multiple items from
         the list, and each selected item is marked with a special character.
         The tag status of the highlighted option can be toggled by hitting the
         [KEYCAP]. All items can be tagged or untagged at once by pressing [KEY-
         CAP] and [KEYCAP], respectively.

         Figure 9.6 shows a typical list window.

Figure 9.6                                                              [SCREEN]
A Typical List
Window


         By default, a list window is stretchable, and if the user changes the
         dimensions, the Toolkit adjusts the displayed columns and rows. Figure
         9.7 is the same List window as shown in figure 9.6, after the user has
         stretched the window.

Figure 9.7                                                              [SCREEN]
A Stretched List
Window


         The primary Toolkit object for displaying lists in a window is ListOBJ,
         but this is an abstract object which should not be instanciated. Lis-
         tOBJ has a number of descendants designed to display different data
         types in lists. Figure 9.8 illustrates the ListOBJ object hierarchy.

         The object hierarchy is similar in principle to the BrowseOBJ hierar-
         chy, with the following main objects:
         ListArrayOBJ    Displays a list derived from a string array.

         ListLinkOBJ     Displays a list derived from any DLLOBJ object or
                         descendant.
         ListDirOBJ &    These two objects are used for displaying directories
         ListDirSortOBJ  in a list window and are discussed in the next chapter.



Managing Lists                                                              9-19
--------------------------------------------------------------------------------

Figure 9.8                                                             [PICTURE]
ListOBJ
Object Hierarchy


Common Methods

         LookTOT (in the unit totLook) is used to control the overall look and
         feel of applications developed with the Toolkit. As well as the window-
         related methods, the following two LookTOT methods impact all list
         objects:
         SetListKeys     Identifies the keys to globally tag or untag windows,
                         and close the list display.

         SetListChars    Identifies the characters which will highlight the
                         active item, as well as the characters which identify
                         the tagged and non-tagged items.
         Refer to page 3-12 for further details.


         Because all the list objects are derived from the ListOBJ, they share a
         set of common methods. The following methods can be used with any of
         the list objects:

         SetTopPick(TopPick: longint);

         This method identifies the node number of the first node that will be
         displayed in the list window, i.e. the first visible item in the list.
         By default, this is the first item in the list.

         SetActivePick(ThePick:longint);

         The highlighted item is referred to as the active pick. This procedure
         is used to set which item (or pick) will be highlighted when the list
         is first displayed. The passed parameter represents the number of the
         item in the visible window, with the top left item having a value of
         one. For example, if the top pick (the first visible pick) was item
         number 12 and you wanted to highlight the 15th item, pass a value of
         four. This will instruct the Toolkit to highlight the fourth visible
         pick. The default is the top pick. If an invalid value is used, e.g.
         the value is greater than the number of visible picks, the value is set
         to the top pick.

         SetTagging(On:boolean);

         This method is used to identify whether the user will be allowed to tag
         and untag items. Pass true to enable item tagging.




9-20                                                                User's Guide
--------------------------------------------------------------------------------

         SetColWidth(Wid:byte);

         This sets the width of each column in characters. If the column width
         is set to zero, the list will be displayed in a single column only, and
         the column width will be as wide as the window. When setting the column
         width, remember to allow for the additional characters used to high-
         light the active pick, and to signify tagged and non-tagged items.

         Show;

         This method displays the list and immediately returns control to the
         calling procedure, i.e. the Toolkit does not wait for user input. This
         option is useful if you want to display the list on the screen, but not
         activate it.

         Go;

         This method is the main "do it" method. If the list is not on display,
         it is drawn. The Toolkit then processes user input until an end key is
         pressed.

         GetHiString:string;

         This function returns a string representing the highlighted item's
         data.

         LastKey:word;

         LastKey returns the key code of the key the user pressed to end the
         browse session. This is used if you need to know whether the user
         escaped or pressed the done key.

         Done;

         As always, Done disposes of the Browse window object, and should always
         be called when the object is no longer required.


Modifying Window Characteristics

         Like BrowseOBJ, the list data is displayed in a window of type Stretch-
         WinOBJ. You can modify any window attribute by directly calling the
         StretchWinOBJ methods.  ListOBJ includes a function method, Win, which
         returns a pointer to the StretchWinOBJ instance. To modify the window,
         call the appropriate StretchWinOBJ method using the following syntax:
                  [ListOBJInstance].Win^.method

         For example, the following statements would change the default window
         size, style and title:

Managing Lists                                                              9-21
--------------------------------------------------------------------------------

                  var MyLister: ListLinkOBJ;

                  begin
                     with MyList do
                     begin
                        Init;
                        Win^.SetSize(1,1,50,20,3);
                        Win^.SetTitle('My Lister');
                     end;
                  end.


         Call Win^ methods to set the list window characteristics, e.g. colors,
         title, remove status, boundaries, etc. Refer to chapter 7: Using Win-
         dows for a thorough discussion of the StretchWinOBJ methods.



           Note: the display colors used in list objects are controlled by
           two different methods. The attributes of the list window perime-
           ter, i.e. box, title, scroll bars and icons, are set using the
           method:
                            Win^.SetColors.
           The display attributes for the body of the window, i.e. the items
           in the list, are controlled using the ListOBJ method SetColors,
           which is discussed later in this section.



Listing Arrays

         The ListArrayOBJ object provides an easy way to display a list based on
         the contents of a string array. In addition to the common methods just
         described, there is the following method:

         AssignList(var StrArray;Total:longint;
                    StrLength:byte;Taggable:boolean);

         AssignList identifies the string array that will be displayed. The four
         parameters are the string array, the total number of elements in the
         array, the length of each string in the array, and a boolean to indi-
         cate whether individual items can be tagged. The string length parame-
         ter must reflect the string length of the array when it was declared,
         not the maximum length of any string assigned to the array.

         Having assigned the list, all you need to do is call Show, and the
         browse window will pop onto the display. Listed below is the demo pro-
         gram DEMLS1.PAS.



9-22                                                                User's Guide
--------------------------------------------------------------------------------

         program DemoList1;
         {demls1}

         Uses DOS, CRT,
              totFAST, totLIST;
         Var
            Items : array [1..20] of string[30];
            ListWin:  ListArrayObj;

         procedure FillArray;
         {}
         begin
            Items[1] := 'One';
            Items[2] := 'Two';
            Items[3] := 'Three';
            Items[4] := 'Four';
            Items[5] := 'Five';
            Items[6] := 'Six';
            Items[7] := 'Seven';
            Items[8] := 'Eight';
            Items[9] := 'Nine';
            Items[10] := 'Ten';
            Items[11] := 'Eleven';
            Items[12] := 'Twelve';
            Items[13] := 'Thirteen';
            Items[14] := 'Fourteen';
            Items[15] := 'Fifteen';
            Items[16] := 'Sixteen';
            Items[17] := 'Seventeen';
            Items[18] := 'Eighteen';
            Items[19] := 'Nineteen';
            Items[20] := 'Twenty';
         end; {FillArray}
         begin
            Screen.Clear(white,'░'); {paint the screen}
            FillArray;
            with ListWin do
            begin
               Init;
               AssignList(Items,20,30,true);
               Go;
               Done;
            end;
         end.


         This is a very basic list which uses all the default settings. Figure
         9.9 illustrates the resultant display.



Managing Lists                                                              9-23
--------------------------------------------------------------------------------

Figure 9.9                                                              [SCREEN]
A Basic List
Window

         The following few statements are an extract from the demo file
         DEMLS2.PAS which is very similar to the previous demo, except that the
         list window has been customized somewhat:
            with ListWin do
            begin
               Init;
               AssignList(Items,20,30,true);
               SetColWidth(15);
               Win^.SetTitle(' Pick a number! ');
               Win^.SetSize(24,7,55,18,2);
               Go;
               Done;
            end;


         By calling the SetColWidth method, the list has been transformed from a
         single list to a multi-column list. Refer back to figure 9.7 to see the
         output generated from DEMLS2.PAS.
         The program DEMLS3.PAS is yet another refinement of the array list
         demo. In this on-disk file, the following statement is added to change
         the list tagging and highlighting characters:

               LookTOT^.SetListChars(chr(16),chr(17),chr(14),chr(32));


Listing Linked Lists

         The ListLinkOBJ is very similar to the ListArrayOBJ. The primary dif-
         ference is that ListLinkOBJ displays the data stored in a DLLOBJ object
         rather than in an array.
         In addition to the common methods described earlier, there are the
         following two methods:


         AssignList(var LinkList: DLLOBJ);
         This method is passed a DLLOBJ instance, or any instance of an object
         derived from DLLOBJ, e.g. StrDLLOBJ.


         ListPtr: DLLPtr;
         This method returns a pointer to the DLLOBJ used to create the list.
         You can access the linked list by using the syntax MyList.ListPtr^.me-
         thod.




9-24                                                                User's Guide
--------------------------------------------------------------------------------

         The demo program DEMLS4.PAS (listed below) shows how well StrDLLOBJ and
         ListLinkOBJ work together. This small demo program creates an StrDLLOBJ
         instance called ItemList. The list is populated by reading the contents
         of an ASCII file. The ListLinkOBJ instance ListWin is then used to
         display the file contents in a window. Figure 9.10 shows the generated
         screen display.

         program DemoList4;
         {demls4 - reading a list from a text file}
         Uses DOS, CRT,
              totFAST, totLINK, totLIST;

         Var
            ListWin:  ListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;
         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do
            begin
               Init;
               {$I-}
               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);
               end;
            end;
         end; {LoadLinkedList}



Managing Lists                                                              9-25
--------------------------------------------------------------------------------

         begin
            Screen.Clear(white,'░'); {paint the screen}
            LoadLinkedList;
            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               Win^.SetTitle(' Items from file DEMLS4.TXT ');
               Win^.SetSize(20,5,60,20,1);
               if not FileOk then
                  SetTagging(false);
               Go;
               Done;
            end;
            ItemList.Done;
         end.


Figure 9.10                                                             [SCREEN]
Display a List
From a File


Determining Which Items are Tagged

         Earlier you learned that by calling the method SetTagging(true), you
         could allow the user to tag and untag items. The Toolkit provides the
         method SetStatus to allow you to pre-tag (or, indeed, pre-untag!) items
         before the list is displayed. Similarly, the method GetStatus is used
         to determine the status of any item in the list.
         Before explaining the syntax of these methods, we need to take a little
         peek behind the scenes. The Toolkit stores eight different flags for
         each item in the list. These flags are numbered 0 through 7.  Flag 0 is
         used to determine whether the user has tagged the item. Flag 1 indi-
         cates which color to use in dual color mode (discussed later). The
         remaining flags are not used and can be customized for descendant
         objects. Refer to Part 2: Extending the Toolkit for more information.

         The syntax of the SetStatus method is as follows:

         SetStatus(Pick:longint; BitPos: byte; On:boolean);

         To pre-tag an item, call the SetStatus method and pass three parame-
         ters. The first parameter specifies the item to be modified, the second
         parameter is the flag number (and this should be set to 0 (zero) to
         modify the tag flag), and the third boolean parameter should be set to
         True to tag the item, or False to un-tag it.



9-26                                                                User's Guide
--------------------------------------------------------------------------------

         After the user has removed the list window, and before the Done method
         is called, the GetStatus method can be called to see which selections
         the user made. The syntax of GetStatus is as follows:


         GetStatus(Pick:longint; BitPos: byte): boolean;
         This function method returns true if the identified item flag is set
         on. The first parameter identifies the item number, and the second
         parameter should be set to 0 (zero) to get the status of the tag flag.


         The following demo program, DEMLS5.PAS, shows how to check for all the
         tagged items. The program writes a list of all the tagged items.
         program DemoList5;
         {demls5 - selecting all tagged items}

         Uses DOS, CRT,
              totFAST, totLINK, totLIST;
         Var
            ListWin:  ListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;
            L,Total: longint;

         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do
            begin
               Init;
               {$I-}
               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);


Managing Lists                                                              9-27
--------------------------------------------------------------------------------

               end;
            end;
         end; {LoadLinkedList}

         begin
            Screen.Clear(white,'░'); {paint the screen}
            LoadLinkedList;
            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               Win^.SetTitle(' Items from file DEMLS4.TXT ');
               Win^.SetSize(20,5,60,20,1);
               if not FileOk then
                  SetTagging(false);
               Go;
               Remove;
               Total := ItemList.TotalNodes;
               clrscr;
               for L := 1 to Total do
                  if GetStatus(L,0) then
                     Writeln('Selected: ',GetString(L,0,0));
               Done;
            end;
            ItemList.Done;
         end.

         In a real application, you might call a procedure to process the tagged
         items, rather than simply write a list of all tagged items.

         If you are displaying a linked list, you can take advantage of the
         DLLOBJ method DelAllStatus. This method is used to automatically remove
         entries from the list which have one of the status flags set in a
         specified state. The syntax of the DLLOBJ method is as follows:

         DelAllStatus(BitPos:byte; On:boolean);

         This method removes all entries from the linked list which have the
         specified flag set in the specified state. The first parameter indi-
         cates the flag number, in the range 0 to 7. The second parameter deter-
         mines whether all the flags set to True or False will be deleted. For
         example, to remove all tagged entries in a linked list you would call
         the method DelAllStatus(0,true);.



9-28                                                                User's Guide
--------------------------------------------------------------------------------

Displaying Dual Colored Lists

         All list objects are capable of displaying each item in one of two
         color combinations. This facility is put to good effect in the ListDi-
         rOBJ object (discussed in the next chapter), where the files are dis-
         played in one color, and the subdirectories in another. The following
         two methods impact the list display colors:

         SetColors(HAttr,NAttr,SAttr: byte);

         This method sets the display attributes for the items in the list. The
         first parameter specifies the attribute of the active pick. The other
         two attributes specify the attributes for the normal items. If the
         status (discussed below) of the normal item is set to high, the SAttr
         attribute will be used, otherwise the NAttr will be used.

         SetDualColors(On:boolean);

         If you want to exploit the dual color capabilities of the list objects,
         pass True. Passing a False will force all the items to display in the
         same color.

         The Toolkit has to have some way of identifying the status of each
         item, i.e. in which attribute the color should be displayed. The second
         of the status flags, i.e. flag 1, is designated as the color flag. The
         SetStatus and GetStatus flags are used to control the color feature, as
         follows:


         SetStatus(Pick:longint; BitPos: byte; On:boolean);
         This method is used to set the status of any item in the list. The
         first parameter identifies the number of the item to be set. The second
         parameter should be set to 1 (one) to indicate that the color status
         flag is being set. The final parameter is a boolean to indicate whether
         status is on (True) or off (False).



         GetStatus(Pick:longint; BitPos: byte): boolean;
         This function method returns true if the identified item flag is set
         on. The first parameter identifies the item number, and the second
         parameter should be set to 1 (one) to determine the status of the dual
         color flag.

         An example of the dual color facility is included in the DEMLS7.PAS,
         discussed in the Character Hook section at the end of the chapter.



Managing Lists                                                              9-29
--------------------------------------------------------------------------------

Displaying Messages about the Highlighted Pick

         The ListOBJ object family supports the optional display of a message at
         the bottom of the list window. This message is normally related to the
         currently highlighted pick. The message might be a long description of
         a terse pick, or some other information about the highlighted pick.
         There are two different ways to instruct the Toolkit to display a mes-
         sage. The no-fuss way is to write a special procedure (called a message
         hook) and instruct the Toolkit to call this procedure every time a pick
         is highlighted. The alternative is to take advantage of an OOP feature
         known as Polymorphism.

         Once a message displaying routine has been implemented, it can be dis-
         abled and enabled using the following method:

         SetMsgState(On:boolean);

         Pass True to activate the message display, or False to deactivate it.


Using a Message Hook
         A message hook is an external function which is called every time a new
         pick is highlighted. To utilize the message hook facility, all you have
         to do is create a function following some specific rules, and then call
         the method SetMsgHook to instruct the Toolkit to use your function.

         For a function to be eligible as a message hook it must adhere to the
         following rules:
         Rule 1     The function must be declared as a FAR function. This can be
                    achieved by preceding the function with a {$F+} compiler
                    directive, and following the function with a {$F-} direc-
                    tive. Alternatively, Turbo 6 users can use the new keyword
                    FAR following the function statement.

         Rule 2     The function must be declared with one passed parameter of
                    type longint. This parameter indicates the highlighted item
                    number.
         Rule 3     The function must return a value of type string. This return
                    value is the actual text to be displayed in the message area
                    of the window display.

         Rule 4     The function must be at the root level, i.e. the function
                    cannot be nested within another procedure or function.
         The following function declaration follows these rules:



9-30                                                                User's Guide
--------------------------------------------------------------------------------

                  {$F+}
                  function MyMessageHook(HiPick:longint): string;
                  begin
                  ...{function statements}
                     MyMessageHook := 'something!';
                  end;
                  {$F-}


         The following method SetMsgHook is then called to instruct the Toolkit
         to call your function every time a new item is highlighted:

         SetMsgHook(Func:ListMsgFunc);

         This method is passed the function name of a function declared using
         the rules outlined above, e.g. SetMsgHook(MyMessageHook);


         The demo program DEMLS6 (listed below) implements a message hook. In
         this case the message is simply a phrase stating which topic is high-
         lighted. I hope your applications are a little more useful! Figure 9.11
         illustrates the resultant output.


         program DemoList6;
         {demls6 - displaying a list message}
         Uses DOS, CRT,
              totFAST, totLINK, totLIST, totSTR, totMSG;

         Var
            ListWin:  ListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;
         {$F+}
         function MsgHook(HiPick:longint):string;
         {}
         begin
            MsgHook := 'The Hi Pick is '+IntToStr(HiPick);
         end; {MsgHook}
         {$F-}

         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do



Managing Lists                                                              9-31
--------------------------------------------------------------------------------

            begin
               Init;
               {$I-}
               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);
               end;
            end;
         end; {LoadLinkedList}

         begin
            Screen.Clear(white,'░'); {paint the screen}
            LoadLinkedList;
            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               SetMsgHook(MsgHook);
               Win^.SetTitle(' A List With Messages ');
               Win^.SetSize(20,5,60,20,2);
               Win^.SetMinSize(20,7);
               if not FileOk then
                  SetTagging(false);
               Go;
               Done;
            end;
            ItemList.Done;
         end.

Figure 9.11                                                             [SCREEN]
A List with a Mes-
sage



9-32                                                                User's Guide
--------------------------------------------------------------------------------

Creating a Descendant Object

         By design, most of the documentation on customizing the Toolkit with
         object oriented techniques is to be found in Part 2: Extending the
         Toolkit. However, as an appetizer, this section explains how to take
         advantage of OOP to implement your own message method, without needing
         to pass a procedure as a parameter. The message hook procedure
         described in the previous section is perfectly adequate and acceptable,
         but it isn't OOP! If you want to learn a few OOP tidbits, read on,
         otherwise be content with the message hook and skip to the next sec-
         tion.
         Usually, to customize a Toolkit object to better meet your needs, you
         create a descendant object. For illustration, we will modify the List-
         LinkOBJ object. Whenever you create a descendant object, you should
         study the parent object's methods and decide which ones to replace or
         modify.

         A descendant object contains all the data and methods of its parent. As
         a bare minimum, you should always define new Init and Done methods, and
         then replace any other methods that you wish to improve or modify. (You
         can also add new methods, but we'll leave that to Part 2!).
         The ListLinkOBJ method includes the following virtual method:

         function MessageTask(HiPick:longint):string;   VIRTUAL;
         This method is called every time a new topic is highlighted, and it
         returns the text to be displayed. Since this method is declared VIR-
         TUAL, we can replace the method in a descendant object, and other
         methods will use the newly defined version of MessageTask.

         The objective is to create a new object descendant from ListLinkOBJ,
         and replace the MessageTask method with a new routine. The syntax for
         declaring the new object type is as follows:
         Type
         NewListLinkOBJ = object (ListLinkOBJ)
           constructor Init;
           function    MessageTask(HiPick:longint):string;   VIRTUAL;
           destructor  Done;                                 VIRTUAL;
         end; {NewListLinkOBJ}


         The descendant object will be called NewListLinkOBJ. Notice that the
         special constructor and destructor procedures Init and Done are
         declared, as well as the new MessageTask function. The constructor and
         destructor methods are required when an object includes virtual meth-
         ods, as it instructs Turbo Pascal to manage procedure calls differ-
         ently. The keywords constructor and destructor are simply used as
         replacements for procedure. The de facto OOP standard is to name the
         constructor INIT and the destructor DONE.



Managing Lists                                                              9-33
--------------------------------------------------------------------------------

         If the ancestor method is declared VIRTUAL, the descendant method must
         also be declared virtual. Furthermore, when you substitute virtual
         methods in a descendant object, the declaration of the method must be
         exactly the same as the ancestor. For this reason, MessageTask and Done
         are both declared virtual, with the same parameters as ListLinkOBJ.

         Having declared a new type NewListLinkOBJ, you must write the actual
         object methods in the body of your program or unit. In this case, Turbo
         Pascal expects the three object methods Init, MessageTask and Done.
         Listed below is an example of how these methods might be written.
         constructor NewListLinkOBJ.Init;
         {}
         begin
            ListLinkOBJ.Init;
            vMsgActive := true;
         end; {NewListLinkOBJ.Init}

         function NewListLinkOBJ.MessageTask(HiPick:longint):string;
         {}
         begin
            MessageTask := 'The Hi Pick is '+IntToStr(HiPick);
         end; {NewListLinkOBJ.MessageTask}

         destructor NewListLinkOBJ.Done;
         {}
         begin
            ListLinkOBJ.Done;
         end; {NewListLinkOBJ.Done}

         Notice that each method starts with the object name followed by a
         period followed by the method identifier. Whenever you declare an Init
         or Done method, you should always call the ancestors Init or Done --
         very often, this ancestor method performs important data initialization
         tasks, and let's not forget that a descendant object assumes all the
         data of its ancestor.
         In the new Init method, the variable vMsgActive is set to true. (All
         object variables in the Toolkit commence with the letter "v".) This
         variable indicates that the object should always call the message dis-
         play method when the active topic is changed. In the LinkListOBJ, this
         variable defaults to false, and is changed to true when the method
         SetMsgHook is called. The main purpose of this descendant object is to
         replace the old MessageTask method with a new one. In the new method,
         the string value returned is just the statement identifying the high-
         lighted topic.

         That's it. Any instance of NewListLinkOBJ will automatically display
         the string returned by the new MessageTask method. Listed below is the
         example DEMLS7.PAS which shows the example in its entirety.



9-34                                                                User's Guide
--------------------------------------------------------------------------------

         program DemoList7;
         {demls7 - creating a descendant ListObject}

         Uses DOS, CRT,
              totFAST, totLINK, totLIST, totSTR, totMSG;
         Type
           NewListLinkOBJ = object (ListLinkOBJ)
              {Methods...}
              Constructor Init;
              function    MessageTask(HiPick:longint):string;   VIRTUAL;
              destructor  Done;                                 VIRTUAL;
           end; {NewListLinkOBJ}

         Var
            ListWin:  NewListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;

         {+++++new object methods+++++}
         constructor NewListLinkOBJ.Init;
         {}
         begin
            ListLinkOBJ.Init;
            vMsgActive := true;
         end; {NewListLinkOBJ.Init}
         function  NewListLinkOBJ.MessageTask(HiPick:longint):string;
         {}
         begin
            MessageTask := 'The Hi Pick is '+IntToStr(HiPick);
         end; {NewListLinkOBJ.MessageTask}

         destructor NewListLinkOBJ.Done;
         {}
         begin
            ListLinkOBJ.Done;
         end; {NewListLinkOBJ.Done}
         {+++++end of new object methods+++++}
         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do
            begin
               Init;
               {$I-}



Managing Lists                                                              9-35
--------------------------------------------------------------------------------

               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);
               end;
            end;
         end; {LoadLinkedList}

         begin
            Screen.Clear(white,'░'); {paint the screen}
            LoadLinkedList;
            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               Win^.SetTitle(' A List With Messages ');
               Win^.SetSize(20,5,60,20,2);
               Win^.SetMinSize(20,7);
               if not FileOk then
                  SetTagging(false);
               Go;
               Done;
            end;
            ItemList.Done;
         end.

         This example works just like DEMLS6.PAS, but a descendant object was
         created rather than passing a procedure. I know what you are thinking
         "It's a damn sight easier to pass a procedure!". That's true, and that
         is precisely why the Toolkit includes the procedure passing alterna-
         tive. By design, this first taste of OOP was a little simple. If your
         curiosity has been piqued, review the source code in the unit
         TOTLIST.PAS. You will see how the base object ListOBJ does all the
         work, and how the descendant objects ListArrayOBJ and ListLinkOBJ make
         the objects work for string arrays and linked lists. The totDIR unit
         discussed in the next chapter extends the ListLinkOBJ and customizes it
         specifically for displaying files and directories.



9-36                                                                User's Guide
--------------------------------------------------------------------------------

Character Hooks

         The ListOBJ object family provides ways to intercept every key pressed
         by the user. This allows you to implement your own special hotkeys.
         Like the Message facility described earlier, there are two different
         ways to instruct the Toolkit to call a procedure every time a key is
         pressed -- by passing a procedure, or by creating a descendant object.


Using a Character Hook

         A character hook is an external procedure which is called every time a
         key or mouse button is pressed. To utilize the character hook facility,
         all you have to do is create a function following some specific rules,
         and then call the method SetCharHook to instruct the Toolkit to use
         your function.
         For a function to be eligible as a character hook it must adhere to the
         following rules:

         Rule 1     The function must be declared as a FAR function. This can be
                    achieved by preceding the function with a {$F+} compiler
                    directive, and following the function with a {$F-} direc-
                    tive. Alternatively, Turbo 6 users can use the new keyword
                    FAR following the function statement.
         Rule 2     The function must be declared with four (count 'em) passed
                    parameters. Parameter one must be a variable parameter of
                    type word. This parameter indicates which key the user just
                    pressed, and you may change the value of this parameter to
                    substitute a different key. The second and third parameters
                    must be variable parameters of type byte, and they represent
                    the X and Y coordinates of the mouse at the time the key was
                    pressed. The fourth parameter is non-variable, and must be
                    of type longint. This parameter indicates the highlighted
                    item number.

         Rule 3     The function must return a value of type tListAction. This
                    is an enumerated type which indicates to the Toolkit how to
                    proceed. The members of the enumerated type are: Finish,
                    Refresh and None. If you want the list window to terminate,
                    return Finish. If you have changed, inserted, or deleted any
                    items in the visible list, return Refresh. The Toolkit will
                    then re-display the entire window contents. Normally, how-
                    ever, you will just return None.
         Rule 4     The function must be at the root level, i.e. the function
                    cannot be nested within another procedure or function.

         The following function declaration follows these rules:



Managing Lists                                                              9-37
--------------------------------------------------------------------------------

                  {$F+}
                  function MyCharHook(var K:word;
                                         var X,Y: byte;
                                         HiPick:longint): tListAction;
                  begin
                  ...{function statements}
                     MyCharHook := None;
                  end;
                  {$F-}


         The following method SetCharHook is then called to instruct the Toolkit
         to call your function every time a key is pressed:

         SetCharHook(Func:ListCharFunc);

         This method is passed the function name of a function declared using
         the rules outlined above, e.g. SetCharHook(MyCharHook);.

         The demo program DEMLS8.PAS, listed below, implements both a message
         hook and a character hook. The character hook is checking for two spe-
         cial keys. If [KEYCAP] is pressed, a simple help screen is displayed,
         and if [KEYCAP] is pressed, the topic is changed to the alternative
         color.

         program DemoList8;
         {demls8 - using Message and Character hooks}
         Uses DOS, CRT,
              totFAST, totLINK, totLIST, totSTR, totMSG;

         Var
            ListWin:  ListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;
         {$F+}
         function HelpHook(var K:word; var X,Y: byte; HiPick:longint): tListAc-
         tion;
         {}
         var MsgWin: MessageOBJ;
         begin
            HelpHook := None;
            if K = 315 then
            begin
               with MsgWin do
               begin
                  Init(6,'Kinda Help');
                  AddLine('');
                  AddLine('In a real application, this would');



9-38                                                                User's Guide
--------------------------------------------------------------------------------

                  AddLine('be a help screen, and it would give');
                  AddLine('help related to item '+IntToStr(HiPick)+'!');
                  AddLine('');
                  Show;
                  Done;
               end;
               K := 0;
            end
            else if K = 316 then {F2 so swap colors}
            begin
               ListWin.SetStatus(HiPick,1,not ListWin.GetStatus(HiPick,1));
               K := 336; {emulate down cursor}
            end;
         end; {HelpHook}

         function MsgHook(HiPick:longint):string;
         {}
         begin
            MsgHook := 'The Hi Pick is '+IntToStr(HiPick);
         end; {MsgHook}
         {$F-}
         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do
            begin
               Init;
               {$I-}
               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);



Managing Lists                                                              9-39
--------------------------------------------------------------------------------

               end;
            end;
         end; {LoadLinkedList}

         begin
            Screen.Clear(white,'░'); {paint the screen}
            Screen.WriteCenter(25,white,'  F1 Help   F2 Toggle Color!   [Space]
         Toggle Tag  ');
            LoadLinkedList;
            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               SetCharHook(HelpHook);
               SetMsgHook(MsgHook);
               SetDualColors(true);
               Win^.SetTitle(' A Multi-Colored List ');
               Win^.SetSize(20,5,60,20,2);
               Win^.SetMinSize(20,7);
               if not FileOk then
                  SetTagging(false);
               Go;
               Done;
            end;
            ItemList.Done;
         end.

Figure 9.12                                                             [SCREEN]
Using a
Character Hook

Creating a Descendant Object

         I think we've had enough OOP for one chapter. Suffice it to say that
         just like the message hook, the character hook can be implemented by
         creating a descendant object and replacing a ListLinkOBJ method called
         CharTask.
         The demo file DEMLS9.PAS (listed below) shows how to replace both the
         character hook and the message hook by creating a new descendant
         object.

         program DemoListNine;
         {demls9 - extending the LinkListOBJ object}
         Uses DOS, CRT,
              totFAST, totLINK, totLIST, totSTR, totMSG;



9-40                                                                User's Guide
--------------------------------------------------------------------------------

         Type
           NewListLinkOBJ = object (ListLinkOBJ)
              {Methods...}
              Constructor Init;
              function    MessageTask(HiPick:longint):string;       VIRTUAL;
              function    CharTask(var K:word; var X,Y: byte;
                                   HiPick:longint): tListAction;    VIRTUAL;
              destructor  Done;                                     VIRTUAL;
           end; {NewListLinkOBJ}

         Var
            ListWin:  NewListLinkObj;
            ItemList: StrDLLOBJ;
            FileOK: boolean;
         {+++++new object methods+++++}
         constructor NewListLinkOBJ.Init;
         {}
         begin
            ListLinkOBJ.Init;
            vMsgActive := true;
         end; {NewListLinkOBJ.Init}

         function  NewListLinkOBJ.MessageTask(HiPick:longint):string;
         {}
         begin
            MessageTask := 'The Hi Pick is '+IntToStr(HiPick);
         end; {NewListLinkOBJ.MessageTask}

         function NewListLinkOBJ.CharTask(var K:word; var X,Y: byte;
                                          HiPick:longint): tListAction;
         {}
         var MsgWin: MessageOBJ;
         begin
            CharTask := none;
            if K = 315 then
            begin
               with MsgWin do
               begin
                  Init(6,'Kinda Help');
                  AddLine('');
                  AddLine('In a real application, this would');
                  AddLine('be a help screen, and it would give');
                  AddLine('help related to item '+IntToStr(HiPick)+'!');
                  AddLine('');
                  Show;
                  Done;
               end;
               K := 0;



Managing Lists                                                              9-41
--------------------------------------------------------------------------------

            end
            else if K = 316 then {F2 so swap colors}
            begin
               ListWin.SetStatus(HiPick,1,not ListWin.GetStatus(HiPick,1));
               K := 336; {emulate down cursor}
            end;
         end; {NewListLinkOBJ.CharTask}

         destructor NewListLinkOBJ.Done;
         {}
         begin
            ListLinkOBJ.Done;
         end; {NewListLinkOBJ.Done}
         {+++++end of new object methods+++++}

         procedure LoadLinkedList;
         {}
         var
           F: text;
           Line:string;
           Result: integer;
         begin
            with ItemList do
            begin
               Init;
               {$I-}
               Assign(F,'demls4.txt');
               Reset(F);
               {$I+}
               FileOK := (IOResult = 0);
               if not FileOK then
                  Result := Add('File not found')
               else
               begin
                  while not eof(F) do
                  begin
                     Readln(F,Line);
                     Result := Add(Line);
                  end;
                  close(F);
               end;
            end;
         end; {LoadLinkedList}
         begin
            Screen.Clear(white,'░'); {paint the screen}
            Screen.WriteCenter(25,white,'  F1 Help   F2 Toggle Color!   [Space]
         Toggle Tag  ');
            LoadLinkedList;



9-42                                                                User's Guide
--------------------------------------------------------------------------------

            with ListWin do
            begin
               Init;
               AssignList(ItemList);
               SetColWidth(15);
               SetDualColors(true);
               Win^.SetTitle(' A Multi-Colored List ');
               Win^.SetSize(20,5,60,20,2);
               Win^.SetMinSize(20,7);
               if not FileOk then
                  SetTagging(false);
               Go;
               Done;
            end;
            ItemList.Done;
         end.