Topics

• DataList properties
• Loading data into a datalist
• Replacing data into a line
• Pointing to a line in the list
• Multi-Select notes
• Clearing List
• Getting Data from list via methods
• Getting Data from list via GetItem

Properties

• SORTED sorts the datalist starting in column 1 of the text string.
  
  
  
• MULTI-SELECT
  • NONE: Only ohe line can be selected at any time.
    
    
  • BASIC: Each line clicked will be selected and stay selected until clicked again. The CTRL-CLICK and SHIFT-CLICK have no effect.
    
    
  • EXTENDED: Each line clicked will turn off all other selected lines UNLESS you use the standard Windows CTRL-CLICK to select multiple lines or the SHIFT-CLICK to select a series of lines.
  
  
  
• SCROLL BARS: You can have both horizontal and vertical scroll bars.
  
  
• HorzExtent:If you use a horizontal scroll bar, you also have to set the HorzExtent to say how far across the user can scroll. This allows you to, in theory, hide data at the end of the line.
  
  There seems to be a limit on this value. Anything greater than about 9500 doesn't work well. You just can't see the end of the line.

DATALIST_CONTENTS        DIM    2000
DATALIST_CURR_ITEM       FORM      6       modifier 0
DATALIST_TOTAL_ITEMS     FORM      6       modifier 1
DATALIST_ITEMS_SELECTED  FORM      6       modifier 2
DATALIST_NEXT_ITEM       FORM      6       modifier 3

     DELETEITEM    {datalist}, 0            ; Clear entire list

     DELETEITEM    {datalist}, 0            ; Clear entire list

     INSERTITEM    {datalist},99999,{data}  ; Insert at END of the list

     INSERTITEM    {datalist},nnn,  {data}  ; Insert at a specific line

        MOVE          ZERO,IX1               ; Initialize the index
        LOOP
          ADD         ONE, IX1               ; increment index
          INSERTITEM  {datalist},IX1,{data}  ; Put {data} in line IX1
        REPEAT UNTIL {condition}

        LOOP
          INSERTITEM  {datalist},99999,{data}  ; Put {data} in LAST line
        REPEAT UNTIL {condition}

        MOVE          ZERO,IX1               ; Initialize the index
        MOVE          ZERO,OURGUY            ; Don't know which line
        LOOP
          ADD         ONE, IX1               ; increment index
          INSERTITEM  {datalist},IX1,{data}  ; Put {data} in line IX1
          IF ({data} = {our salesman})       ; Is this our guy?
              MOVE    IX1, OURGUY            ; When true, remember IX1
          ENDIF
        REPEAT UNTIL {condition}
        SETITEM       {datalist},0,OURGUY    ; Point to our salesman

          SETITEM  {datalist},IX1,{data}  ; replace {data} in line IX1

  SETITEM {datalist},0,{index}    ; Point to line at {index}

  {datalist}.SetSel USING *Select={0|1}, *Index={index}  
  ... *Select = 1 for selected
  ...           0 for NOT selected
  ... *Index is ZERO BASED               

  {datalist}.SelItemRange USING *Select={0|1}:
		*First={first},*Last={last}
  ... *Select = 1 for selected
  ...           0 for NOT selected
  ... *Index is ZERO BASED               

GETTING DATA OUT OF THE LIST:

METHOD Technique:

DLMAX        FORM   3    ;number of items in the data list
DLSEL        FORM   3    ;number of items selected
DLIX         FORM   3    ;Zero based line index
DATA_STRING  DIM  250    ;Data from list

        F1_DL_Accounts.GetCount    GIVING DLMAX  ;information only
        F1_DL_Accounts.GetSelCount GIVING DLSEL  ;information only
		
        F1_DL_Accounts.GetFirstSel GIVING DLIX   ;first line we want
        LOOP
          IF (DLIX < 0)        ;is -1 if no more lines
              BREAK
          ENDIF
          F1_DL_Accounts.GetText    GIVING DATA_STRING USING DLIX
		  --- process the data ---
          F1_DL_Accounts.GetNextSel GIVING DLIX
        REPEAT

The third parameter's type determines how the instruction works. If the third item is a CHARACTER STRING you'll get data from the list. If the third item is a NUMBER you'll get the index to the line that was clicked. Getting POINTERS for the datalist is done with GETITEM where the 3rd parameter is a number. A data value will be returned in that field as follows:

    GETITEM {datalist}, 0,   {numeric}   Gets the index of CURRENTLY
                                         active item in the list

    GETITEM {datalist}, 1,   {numeric}   Gets the TOTAL NUMBER of
                                         items that are in the list.

    GETITEM {datalist}, 2,   {numeric}   Gets the number of items
                                         which are SELECTED in a
                                         multi-select list.

    GETITEM {datalist}, 3,   {numeric}   Gets the index of the NEXT
                                         selected from a multi-select
                                         list.

Note that there are pre-defined variables for these pointers in the COMMONWK.PLS include unit for MMCC. Those are defined at the top of this page.

Getting DATA from the datalist is done with GETITEM where the 3rd parameter is a STRING. The second parameter is the index to the item you want.

For an EDIT style list (where the user can key anything into the datalist's top line), you can use index ZERO to get the top line as it appears to the user.

    GETITEM {datalist}, nnn, {string}    Gets the contents of the
                                         entry number "nnn".

    GETITEM {datalist}, 0,   {string}    Get the actual value keyed
                                         but only if this is a style
                                         EDIT where they can put
                                         anything in the field.

RETREIVING MULTI-SELECT DATA: Getting data out of a multi-select datalist is not as obvious at it seems.

The trick is to use the CURRENT ITEM and the NEXT ITEM pointers properly. CURRENT ITEM points to the currently selected item. That part is obvious. What seems to be the confusion is the next item is the one after the first item in the list OR the next one after the last item you retrieved. Here's a loop that works:

      GETITEM      DataList, 0, CURR_ITEM
      LOOP
        COMPARE    ZERO,        CURR_ITEM
        BREAK IF EQUAL		
        GETITEM    Datalist,    CURR_ITEM, TEXT_STRING
        GETITEM    Datalist, 3, CURR_ITEM
      REPEAT

That seems a bit less than elegant, but it works. The point is that before starting the loop you have to learn the current item. That's the first one that the user selected. If that pointer is ZERO then no data was selected. If not zero then you can retreive that first item.

After getting the first item, you need to use the "3" value to get the NEXT item after the one you just retreived. Note that in the sample code I used the CURR_ITEM variable. Although that's what I'm calling it, the "3" says to get the next item after the last one selected or retreived.

With the NEXT item in hand we loop back to see if it's a valid item. If we got a ZERO then we're all done.

NOTE: A useful method is DataList.GetSelCount GIVING WK_Counter.
This will tell you how many lines are selected at any given time.

FORMATTING THE DATALIST: Datalist contents are simple strings. You can load a list with data like this.

        LOOP
          PACK        WORK_STRING,ID, NAME, ADDRESS ; build string
          INSERTITEM  {datalist},999999,WORK_STRING ; put in list
        REPEAT UNTIL {condition}

The above list will not produce nice columns of data as you might expect. If you use a proportional font the data will appear like this: 101 John Jones 600 Lakeshore Drive
101 Larry Lewis 1420 Mountain
103 Susie Sunshine 980 Summer Circle You can control the column spacing to some degree by insertting the TAB character (0x09) into your string. But tabs just skip to the next system defined tab, which you can't control. Sometimes things will come out right, sometimes they won't.

To produce formatted columns, you must use a fixed width font such as Courier, or FIXEDSYS. (You can select the font when building the form in the forms designer, or you can set it by hand.)

Using a fixed font you'll get this:

         101   John Jones         600 Lakeshore Drive
         101   Larry Lewis        1420 Mountain
         103   Susie Sunshine     980 Summer Circle

LISTVIEW
Starting with Windows 95 users have become accoustomed to a structure that looks much like a DATALIST but is, in fact, something else. This is the LISTVIEW (aka DATAGRID).

The LISTVIEW is typified by several features: There's a header bar across the top with dividers between columns.

The data lines up under the columns regardless of the font.

You can change the width of the columns with the mouse by grabbing a divider and sliding it left and right.

You can sort the entire grid on any column by clicking in the column heading. Multiple clicks sort ascending then descending. A small arrow in the right corner of the heading shows which column was sorted last and the direction of the sort. PL/B provides this function with the LISTVIEW object described in this link.

---

Multi-Select Notes

Clearing Multi-Selections: If you have a multi-select data list, you may need to just clear ALL of the selections that a user may have made. There is no METHOD for doing that. You can loop over all of the selected lines and deselect them one at a time. But it's easier to use SETITEM {datalistname},0,0.