GUI ScreenIO for Windows

The listview-GET-PRIOR event

A listview-GET-PRIOR event is returned when the listview needs records that precede those you've previously loaded.

A listview-GET-PRIOR event occurs when the user scrolls the list towards the beginning of the list further than the first record that's been loaded to the cache.

Data returned with this event

Required to process this event

*In panel-3 area*	Data
listview-GET-FROM-KEY	The value of the invisible key column for the first record in the listview cache.

Returned but not used to handle this event

*In panel-3 area*	Data
listview-MAX	Maximum number records that may be passed in the listview buffer, useful for PERFORMed loops when loading records to your listview buffer.
listview-SCROLL-TO-KEY	Set to HIGH-VALUES.
listview-SEL1-KEY	The value of the invisible key column for the first selected record in the list.
listview-SEL2-KEY	The value of the invisible key column for the last selected record record in the list. Note: Since GUI ScreenIO does not presently support a selection range (multiple record selections), this field is always the same as listview-SEL1-KEY.
listview-TOP-OF-LIST-KEY	The value of the invisible key column for the first (top) record that is visible in the listview control.
All other fields	Set to LOW-VALUES.

*In panel-4 area*	Data
listview	Number of items in the list that are selected.

Required response

Position the file to the record having the key that was returned in listview-GET-FROM-KEY, then load the listview backwards from this point in the file.

The key and percentage of the last record in the listview buffer must match the key and percentage of the first record in the cache; that is, you must reload the record with the key that was returned to you in listview-GET-FROM-KEY.

Note that this is precisely the reverse of your response to a listview-GET-NEXT.

Sample code

     PERFORM WITH TEST AFTER
         UNTIL panel-EVENT-CLOSE-WINDOW
            OR panel-EVENT-CLOSE-AND-STOP

       CALL 'GS' USING panel-1
                       panel-2
                       panel-3
                       panel-4

     EVALUATE TRUE

-->      WHEN listview-GET-PRIOR
-->        MOVE listview-GET-FROM-KEY TO record-KEY
-->        SET file-command-START-EQUAL TO TRUE
-->        CALL file-I-O-routine USING file-commands
-->                                    data-record
-->        IF valid-file-status
-->          PERFORM BROWSE-BACKWARD
-->        END-IF

           .
           .
           .

      END-EVALUATE

END-PERFORM.

Here's the general form of the performed routine that loads the listview buffer.

Note that you must move 0 percent to the first record that was successfully loaded to indicate to the listview that you have loaded the first record in the list. Once the listview has received a record with 0 in the percentage, it will no longer return listview-GET-PRIOR events (unless this record has been discarded from the cache by GUI ScreenIO's caching algorithm).

BROWSE-BACKWARD.

     PERFORM WITH TEST AFTER
         VARYING listview-IDX FROM listview-MAX BY -1
         UNTIL listview-IDX NOT > 1
            OR NOT valid-file-status

       SET file-command-READ-PRIOR TO TRUE
       CALL file-I-O-routine USING file-commands
                                   data-record

       EVALUATE TRUE

         WHEN valid-file-status
           PERFORM LOAD-DATA-TO-LISTVIEW

         WHEN file-status-start-of-file
           IF listview-IDX < listview-MAX
             MOVE 0 TO listview--PERCENT (listview-IDX + 1)
           END-IF

       END-EVALUATE
     END-PERFORM.

LOAD-DATA-TO-LISTVIEW.

     MOVE record-PERCENT TO listview--PERCENT (listview-IDX).
     MOVE record-KEY     TO listview--KEY     (listview-IDX).

     MOVE record-data    TO listview-column-1 (listview-IDX).
     MOVE record-data    TO listview-column-2 (listview-IDX).
     MOVE record-data    TO listview-column-n (listview-IDX).

Common problems

See listview-GET-NEXT for problems commonly encountered when loading listviews.

Remarks

The listview-GET-PRIOR event is used to insert data at the beginning of GUI ScreenIO's listview cache when it is required. This "just-in-time" strategy of loading data to a listview means that there is no particular delay when browsing a very large file with a listview, and also reduces memory utilization.

Preload Cache

Preload cache is discussed in the topic listview-GET-NEXT. You will never receive a listview-GET-PRIOR event if a listview uses preload caching.

Accumulate Cache

Accumulate caching works much like preload cache, except that it only returns listview-GET-PRIOR events when needed, instead of loading the entire list at once. Like preload caching, it's best when used for relatively small files.

Specify accumulate caching in the panel editor using the listview properties. Choose the Listview Behavior tab, then click the radiobutton for Accumulate Cache.

If you didn't begin loading an accumulate-cache listview from the beginning, and the user scrolls backwards beyond what's in the cache, you'll receive a listview-GET-PRIOR event.

Likewise, if the user drags the scrollbar thumb a long way toward the beginning of a list that wasn't loaded from the beginning, you'll receive a series of listview-GET-PRIOR events until the listview receives a record with a percentage that matches the scrollbar thumb position (which can be tricky if your file system doesn't support percentages). If your list is very large, it may take a considerable time for the listview to load all of the data up to the scrollbar thumb position, since accumulate-caching listviews always load the data sequentially.

Accumulate caching is sometimes useful when your file system doesn't handle percentages well, or when you want to keep all of the data you've loaded to the cache in memory.

On the other hand, if you've written the code to handle the listview-GET-PRIOR event, there's really no point to using accumulate (or preload) caching; you would be better served by using the default listview caching.

Percentages

The listview implementation requires that you be able to position the file to a percentage along the keypath, and that you be able to supply this percentage with each record loaded to the listview.

Go here for a complete discussion of percentages with respect to using listviews, and one technique of synthesizing percentages for file systems (like ISAM) which do not provide them.

Internal Listview Cache management

When you respond to a listview-GET-PRIOR event, GUI ScreenIO inserts the records that you supply in the listview buffer, in front of the records already in its cache. If the cache size exceeds the internal maximum, records will be deleted from the end in order to accommodate the records you're adding to the beginning of the cache.

Preload caching causes the cache to be expanded as required to hold the entire list.

Accumulate caching causes the cache to be expanded on demand as records are loaded, until the entire list has been loaded.