Tutorial 14 - Displaying Array Data in Unbound Extended Mode

In this tutorial, you will learn how to use the unbound extended mode (DataMode property set to 2 - Unbound Extended) of True DBList to display an array of strings. As its name implies, the unbound extended mode is an extension of the unbound mode introduced in Tutorial 13. Unbound mode 2 is both easier to use and more efficient than unbound mode 1. For detailed instructions on how to use unbound mode 2, see Unbound Mode.

The TUTOR14.VBP project provides a complete sample that you can use as a template for implementing unbound mode 2. This project is located in the TUTORIAL\TUTOR14 subdirectory of the True DBList installation directory.

Start a new project.
Place a True DBCombo control (TDBCombo1) on the form (Form1).
Set the DataMode property of TDBCombo1 to 2 - Unbound Extended (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

Configuring the combo at design time

We shall configure the combo as in Tutorial 13.
Right-click TDBCombo1 to display its context menu. Choose Properties to display the Property Pages dialog box.
Select the Columns properties page by clicking the Columns tab. Set the Caption property of Columns(00) and Columns(01) to Column 0 and Column 1, respectively.

Initializing the array data

We first create and initialize a two-dimensional array to hold the data to be displayed in the list. As in Tutorial 13, we will use a class module to encapsulate the unbound events.
Add the CLASS1.CLS file from the TUTOR14 directory to the project. This class module will be responsible for storing data and responding to the combo's events.

Displaying data in the unbound combo

As explained in Tutorial 13, True DBList does not store your data in any of its unbound modes. In unbound mode 2, whenever the list needs to display more rows of data, it will fire the UnboundReadDataEx event (instead of UnboundReadData) to ask for data from your data source.

Study the following implementation of the UnboundReadDataEx event from CLASS1.CLS. This example shows how data and the row's ordinal position are provided to the list via the RowBuffer object and the ApproximatePosition arguments, respectively:

Example Title	Copy Code
' Fired when the Combo needs a bookmark or data Private Sub TDBC_UnboundReadDataEx( _ ByVal RowBuf As TrueDBList80.RowBuffer, _ StartLocation As Variant, ByVal offset As Long, _ ApproximatePosition As Long) ' UnboundReadDataEx is fired by an unbound combo whenever ' it requires data for display. This event will fire ' when the combo is first shown, when Refresh or ReBind ' is used and when the combo is scrolled. The ' combo fetches data in "chunks", and the number of rows ' the combo is asking for is given by RowBuf.RowCount. ' RowBuf is the row buffer where you place the data ' the bookmarks for the rows that the combo is ' requesting to display. It will also hold the number ' of rows that were successfully supplied to the combo. ' StartLocation is a bookmark which, together with ' Offset, specifies the row for the programmer to start ' transferring data. A StartLocation of Null indicates ' a request for data from BOF or EOF. ' Offset specifies the relative position (from ' StartLocation) of the row for the programmer to start ' transferring data. A positive number indicates a ' forward relative position while a negative number ' indicates a backward relative position. Regardless ' of whether the rows to be read are before or after ' StartLocation, rows are always fetched going forward ' (this is why there is no ReadPriorRows parameter to ' the procedure). ' If you page down on the combo, for instance, the new ' top row of the combo will have an index greater than ' the StartLocation (Offset > 0). If you page up on ' the combo, the new index is less than that of ' StartLocation, so Offset < 0. If StartLocation is ' a bookmark to row N, the combo always asks for row ' data in the following order: ' (N + Offset), (N + Offset + 1), (N + Offset + 2)... ' ApproximatePosition is a value you can set to indicate ' the ordinal position of (StartLocation + Offset). ' Setting this variable will enhance the ability of the ' combo to display its vertical scroll bar accurately. ' If the exact ordinal position of the new location is ' not known, you can set it to a reasonable, ' approximate value, or just ignore this parameter. Dim ColIndex As Integer, J As Integer Dim RowsFetched As Integer, I As Long Dim NewPosition As Long, Bookmark As Variant RowsFetched = 0 For I = 0 To RowBuf.RowCount - 1 If IsNull(StartLocation) Then If offset < 0 Then ' StartLocation refers to EOF Bookmark = MaxRow + offset Else ' StartLocation referrs to BOF Bookmark = offset - 1 End If Else ' StartLocation is a valid or invalid row Bookmark = StartLocation + offset + I ' If the next row is BOF or EOF, stop fetching ' and return any rows fetched up to this point. If Bookmark < 0 Or Bookmark >= MaxRow _ Then Exit For End If ' Fill the RowBuffer with data For J = 0 To RowBuf.ColumnCount - 1 ColIndex = RowBuf.ColumnIndex(I, J) ' Place the record data into the row buffer RowBuf.Value(I, J) = _ ComboArray(ColIndex, Bookmark) Next J ' Set the bookmark for the row RowBuf.Bookmark(I) = Bookmark ' Increment the count of fetched rows RowsFetched = RowsFetched + 1 Next I ' Tell the list how many rows were fetched RowBuf.RowCount = RowsFetched ' Set the approximate scroll bar position. Only ' nonnegative values are valid. If Bookmark >= 0 Or Bookmark < MaxRow _ Then ApproximatePosition = Bookmark - I End Sub

Example Title

Copy Code

' Fired when the Combo needs a bookmark or data

Private Sub TDBC_UnboundReadDataEx( _

    ByVal RowBuf As TrueDBList80.RowBuffer, _

    StartLocation As Variant, ByVal offset As Long, _

    ApproximatePosition As Long)

 

' UnboundReadDataEx is fired by an unbound combo whenever

' it requires data for display.  This event will fire

' when the combo is first shown, when Refresh or ReBind

' is used and when the combo is scrolled.  The

' combo fetches data in "chunks", and the number of rows

' the combo is asking for is given by RowBuf.RowCount.

 

' RowBuf is the row buffer where you place the data

' the bookmarks for the rows that the combo is

' requesting to display.  It will also hold the number

' of rows that were successfully supplied to the combo.

 

' StartLocation is a bookmark which, together with

' Offset, specifies the row for the programmer to start

' transferring data.  A StartLocation of Null indicates

' a request for data from BOF or EOF.

 

' Offset specifies the relative position (from

' StartLocation) of the row for the programmer to start

' transferring data.  A positive number indicates a

' forward relative position while a negative number

' indicates a backward relative position.  Regardless

' of whether the rows to be read are before or after

' StartLocation, rows are always fetched going forward

' (this is why there is no ReadPriorRows parameter to

' the procedure).

 

' If you page down on the combo, for instance, the new

' top row of the combo will have an index greater than

' the StartLocation (Offset > 0).  If you page up on

' the combo, the new index is less than that of

' StartLocation, so Offset < 0.  If StartLocation is

' a bookmark to row N, the combo always asks for row

' data in the following order:

'   (N + Offset), (N + Offset + 1), (N + Offset + 2)...

 

' ApproximatePosition is a value you can set to indicate

' the ordinal position of (StartLocation + Offset).

' Setting this variable will enhance the ability of the

' combo to display its vertical scroll bar accurately.

' If the exact ordinal position of the new location is

' not known, you can set it to a reasonable,

' approximate value, or just ignore this parameter.

 

    Dim ColIndex As Integer, J As Integer

    Dim RowsFetched As Integer, I As Long

    Dim NewPosition As Long, Bookmark As Variant

 

    RowsFetched = 0

 

    For I = 0 To RowBuf.RowCount - 1

        If IsNull(StartLocation) Then

            If offset < 0 Then

                ' StartLocation refers to EOF

                Bookmark = MaxRow + offset

            Else

                ' StartLocation referrs to BOF

                Bookmark = offset - 1

            End If

        Else

            ' StartLocation is a valid or invalid row

            Bookmark = StartLocation + offset + I

 

            ' If the next row is BOF or EOF, stop fetching

            ' and return any rows fetched up to this point.

            If Bookmark < 0 Or Bookmark >= MaxRow _

                           Then Exit For

        End If

 

        ' Fill the RowBuffer with data

        For J = 0 To RowBuf.ColumnCount - 1

            ColIndex = RowBuf.ColumnIndex(I, J)

            ' Place the record data into the row buffer

            RowBuf.Value(I, J) = _

                          ComboArray(ColIndex, Bookmark)

        Next J

 

        ' Set the bookmark for the row

        RowBuf.Bookmark(I) = Bookmark

        ' Increment the count of fetched rows

        RowsFetched = RowsFetched + 1

    Next I

 

    ' Tell the list how many rows were fetched

    RowBuf.RowCount = RowsFetched

 

    ' Set the approximate scroll bar position.  Only

    ' nonnegative values are valid.

    If Bookmark >= 0 Or Bookmark < MaxRow _

                      Then ApproximatePosition = Bookmark - I

End Sub

In the General section of Form1, insert the following declarations:

Example Title	Copy Code
Option Explicit Dim Sink As New Class1

In the Form_Load (Visual Basic) event, initialize the elements of the Class1 instance and set the ApproxCount property of the combo accordingly.The ApproxCount property is optional, but setting this value will enable the combo to position the vertical scroll bar accurately.

Example Title	Copy Code
Private Sub Form_Load() Dim Row As Long, Col As Integer Row = 100 Col = 2 ' Initialize storage Sink.SetDims Row, Col ' Fill with values For Row = 0 To Sink.RowCount - 1 For Col = 0 To Sink.ColCount - 1 Sink.Value(Row, Col) = _ "Row " & Row & ", Col " & Col Next Col Next Row ' Initialize the class Sink.Attach TDBCombo1 ' Calibrate the VScroll bar TDBCombo1.ApproxCount = Sink.RowCount End Sub

Example Title

Copy Code

Private Sub Form_Load()

    Dim Row As Long, Col As Integer

 

    Row = 100

    Col = 2

 

    ' Initialize storage

    Sink.SetDims Row, Col

 

    ' Fill with values

    For Row = 0 To Sink.RowCount - 1

        For Col = 0 To Sink.ColCount - 1

            Sink.Value(Row, Col) = _

                "Row " & Row & ", Col " & Col

        Next Col

    Next Row

 

    ' Initialize the class

    Sink.Attach TDBCombo1

 

    ' Calibrate the VScroll bar

    TDBCombo1.ApproxCount = Sink.RowCount

End Sub

Run the program and observe the following:

The combo displays the data generated in the Form_Load (Visual Basic) event and otherwise behaves as if it were bound to a Data control.

To end the program, press the End button on the Visual Basic toolbar. You have successfully completed Tutorial 14.