GUI ScreenIO for Windows

Listview Programming

Listviews are different

When you display data to most GUI ScreenIO controls, you load it to the control's panel-4 area (simple controls) or to the panel-3 area (listboxes comboboxes, and treeviews).

All of the data that the control can possibly display is loaded to the control's data area. This is possible because these controls are limited to displaying a "reasonable" amount of data.

Listviews, on the other hand, are capable of displaying lists that may be thousands, or even millions of records long.

It wouldn't be practical to load 10 million records to a listview before you display it; for one thing, it would take a considerable period of time, and for another, it would require a huge amount of storage. Therefore, we adopted a more efficient approach for loading a listview.

How listviews work

Because a listview is capable of displaying lists with up to nearly a billion records, it's not practical to load the entire file to the listview in order to display it. In order to handle extremely large lists, our listview implementation caches the records of interest to the user.

GUI ScreenIO will ask you to supply more records if the user scrolls beyond what is presently in its listview cache. If the user scrolls only a small amount, GUI ScreenIO will request records that are contiguous to those in its cache, either preceding it or following it, depending upon whether the user scrolled forward or backward.

If the user drags the scrollbar a considerable distance along the list, GUI ScreenIO will discard its cache and ask you to supply records at the new position in the list/file.

The caching algorithm is extremely efficient, and you will find it performs well even with very large files because you never need to read many records before they are displayed in the list.

Listview rules

There a couple of rules you must observe when using a listview:

You must provide a unique key for each item you load to a listview
You must specify what percentage the record is in the file
The FIRST record must be loaded with ZERO (0) percent; this tells GUI ScreenIO that it's the first record in the list
The LAST record must be loaded with 100 percent; this tells GUI ScreenIO when you've reached the end of the list
If the contains only ONE record, set it to 100 percent when you load the listview
You must overlap by one record when loading successive listview buffers. (Pay attention to the GET-FROM-KEY)
You need to respond appropriately when a listview event is returned to your program. There are three 'critical' events that you must handle; these are discussed in listview events.

If you follow these rules, you won't have any problem using listviews.

Unique key

Part of your listview definition includes a invisible key column. This is a field which is not displayed, but which must contain data which uniquely identifies each record.

The listview uses this data to make it easy for you to identify each record in your list. The data doesn't have to be a record key; it can be anything that you wish to use to identify your data. You could assign sequential numbers to your data as you load the list, for example, although most of the time you'll be better off using a unique record key.

When the user selects a record by double-clicking it, GUI ScreenIO will pass you the key that you loaded when you loaded the record. This makes it easy for you to find and read the record if you wish to display it in a popup panel, for example.

GUI ScreenIO also uses this key to support other listview events, as we'll see later.

Percentages

You also need to specify each record's percentage along the current keypath. That is, how far it is into the file.

GUI ScreenIO uses the percentages you provide to determine how large the list is, and where the current record is in the list.

The percentage into the file is used for setting the size and position of the scrollbar thumb. The more records in your list, the smaller the scrollbar thumb.

If you're using a database package, it most likely will provide the percentage you need.

If you're using COBOL file management to access your data, you probably don't have percentages available to you. Go here for some tips.

The FIRST record

You absolutely, positively, MUST load ZERO to the percentage of the FIRST record in your list!

If you do not, GUI ScreenIO assumes you're not at the beginning of your list, and will at some point return a listview-GET-PRIOR event to your program to request the data that precedes the first record you've loaded.

The ONLY record

Well, there is an exception. If there's only ONE record in the list; then you load 100 to the percentage of the record to indicate it's the end of file.

The LAST record

You absolutely, positively, MUST load 100 to the percentage of the LAST record in your list!

If you do not, GUI ScreenIO assumes you're not at the end of your list, and will at some point return a listview-GET-NEXT event to your program to request data that follows the last record you loaded.

Listview Events

A listview control can return a variety of events to your program; some of them are requests for more data (listview-GET-NEXT, listview-GET-PRIOR). Others are a request to restart the list somewhere else in the file, which happens if the user drags the scrollbar thumb more than a page or two worth of data (listview-START-AT).

It's critical that your program responds correctly to these events.

The next sections discuss how to load a listview, and how to respond to listview events.