The UnboundReadData event is fired only if the DataMode property is set to 1 - Unbound. This event is retained only for backward compatibility with DBList and earlier versions of True DBList. If you are writing a new unbound mode application, DataMode 2 - Unbound Extended is recommended, since it is more efficient and easier to use.

The UnboundReadData event is fired whenever the list requires data for display. Its syntax is as follows:

Private Sub TDBList1_UnboundReadData( _

        ByVal RowBuf As RowBuffer, _

        StartLocation As Variant, _

        ReadPriorRows As Boolean)

When this event is fired, the properties of the RowBuf argument are set as follows:

• RowCount specifies the number of rows of data requested from your data source.

• ColumnCount specifies the number of columns of data requested from your data source.

• The ColumnName array contains the names of the list columns corresponding to the columns in RowBuf.

• The Bookmark and Value arrays contain all Null values.

StartLocation is a bookmark that specifies the row before or after the desired data, depending on the value of the ReadPriorRows argument.

ReadPriorRows indicates the direction in which the list is requesting the data. If False, you should provide data in the forward direction, starting with the row immediately after the row specified by StartLocation. If True, you should provide data in the backward direction, starting with the row immediately before the row specified by StartLocation.

Before returning from the UnboundReadData event, you are expected to fill the Bookmark property array with unique row identifiers, and the Value property array with the actual data:

Dim RowIndex As Long

Dim ColIndex As Integer

 

With RowBuf

    For RowIndex = 0 To .RowCount - 1

        .Bookmark(RowIndex) = Variant Bookmark

        For ColIndex = 0 To .ColumnCount - 1

            .Value(RowIndex, ColIndex) = Variant Data

        Next ColIndex

    Next RowIndex

End With

For example, if the list specifies a StartLocation bookmark indicating the 46th row, the ReadPriorRows argument is False, and the row buffer's RowCount property is 10, then the list is asking for the records following the 46th row, and your UnboundReadData event handler should populate the row buffer's Value array as follows:

RowBuf.Value(0, ColIndex) = Data for row 47

RowBuf.Value(1, ColIndex) = Data for row 48

RowBuf.Value(2, ColIndex) = Data for row 49

...

RowBuf.Value(9, ColIndex) = Data for row 56

However, if ReadPriorRows is False, then the list is asking for the records preceding the 46th row, and a different set of values must be returned:

RowBuf.Value(0, ColIndex) = Data for row 45

RowBuf.Value(1, ColIndex) = Data for row 44

RowBuf.Value(2, ColIndex) = Data for row 43

...

RowBuf.Value(9, ColIndex) = Data for row 36

If you reach the beginning or end of the data, and have fewer than RowCount rows to provide, then you should fill the row buffer with the data you can provide, and change the RowCount property to the actual number of rows provided, which may be zero.

For example, if your dataset contains 50 records, the list specifies a StartLocation bookmark indicating the 46th row, the ReadPriorRows argument is False, and the row buffer's RowCount property is 10, then your UnboundReadData event handler should populate the row buffer's Value array as follows:

RowBuf.Value(0, ColIndex) = Data for row 47

RowBuf.Value(1, ColIndex) = Data for row 48

RowBuf.Value(2, ColIndex) = Data for row 49

RowBuf.Value(3, ColIndex) = Data for row 50

 

RowBuf.RowCount = 4       ' Since only 4 rows were processed

At first glance, StartLocation and ReadPriorRows may seem unnecessarily cumbersome. However, they communicate the row boundaries to the list simply and directly. The list only caches a portion of the data, and it is with these two arguments that it can navigate from one bookmark to the next.

For example, suppose there are 100 rows of data, the current row is 75, and the list is asked to move to row 3 using a previously obtained bookmark. The following sequence demonstrates what might happen in this situation:

1. The list receives a bookmark for row 3. Since the data for this row is not in the list's cache, the list requests the data using the UnboundReadData event, which is called with the following parameters:

   Example Title	Copy Code
   RowBuf.RowCount = 10 RowBuf.ColumnCount = Number of columns StartLocation = Bookmark for row 3 ReadPriorRows = False

2. The event code responds as follows:

   Example Title	Copy Code
   RowBuf.Value(0, ColIndex) = Data for row 4 RowBuf.Value(1, ColIndex) = Data for row 5 ... RowBuf.Value(9, ColIndex) = Data for row 13 RowBuf.RowCount = 10 ' Since all 10 rows were processed

3. The UnboundReadData event is called again, this time with:

   Example Title	Copy Code
   RowBuf.RowCount = 10 RowBuf.ColumnCount = Number of columns StartLocation = Bookmark for row 4 ReadPriorRows = True

4. The event code responds as follows:

   Example Title	Copy Code
   RowBuf.Value(0, ColIndex) = Data for row 3 RowBuf.Value(1, ColIndex) = Data for row 2 RowBuf.Value(2, ColIndex) = Data for row 1 RowBuf.RowCount = 3 ' Since only 3 rows were processed

Note that after fetching row 1, the event code stops setting values since there is no more data available in the indicated direction from the starting bookmark. Also, RowBuf.RowCount is set to 3, since only 3 rows could be read before the beginning of the dataset was encountered. At this point, additional UnboundReadData events may be fired to obtain the data necessary to complete the display.

The preceding example demonstrates how the same event interface is called upon to handle both BOF and EOF conditions. When one of these special cases is encountered, the event handler simply exits the loop used to fill the row buffer and reports the number of rows actually processed in the RowCount property.

A StartLocation of Null indicates a request for BOF or EOF. Whether it indicates BOF or EOF depends upon the value of ReadPriorRows:

If IsNull(StartLocation) Then

    If ReadPriorRows Then

        ' StartLocation indicates EOF, because the list is

        ' requesting data in rows prior to the StartLocation,

        ' and prior rows only exist for EOF.

        ' There are no rows prior to BOF.

    Else

        ' StartLocation indicates BOF, because the list is

        ' requesting data in rows after the StartLocation,

        ' and rows after only exist for BOF.

        ' There are no rows after EOF.

    End If

Else

    ' StartLocation is an actual bookmark passed to the list

    ' in the RowBuffer, an event argument (UnboundAddData), or

    ' the setting of a list bookmark. You must ensure that

    ' the bookmark is valid, and take the appropriate action

    ' if it is not.

End If

You cannot make any assumptions about when the list will request data, or how many times it will request the same data. In short, it is the list's responsibility to display the data properly, while the task of storing and maintaining the data falls to you. This division of labor frees you from worrying about when or how to display data in the list.

Copyright (c) GrapeCity, inc. All rights reserved.