In this tutorial, you will learn how to use the unbound mode (DataMode property set to 1 - Unbound) of True DBList to display an array of strings.

This unbound mode has been retained for backward compatibility with the original DBGrid control.  ComponentOne recommends using unbound extended mode (Tutorial 14), application mode (Tutorial 15), or storage mode (Tutorial 16) instead.  For detailed instructions on how to use unbound mode 1, see Unbound Mode.

1. Start a new project.

2. Place a True DBCombo control (TDBCombo1) on the form (Form1).

3. Set the DataMode property of TDBCombo1 to 1 - Unbound (the default value of this property is 0 - Bound) and the MaxComboItems property to 14.

   Configuring the combo at design time

   This example displays a two-column array within the list portion of a True DBCombo control.  Since the control displays two columns by default, you do not have to add or delete columns at design time.

4. Right-click TDBCombo1 to display its context menu.  Choose Properties to display the Property Pages dialog box.

5. 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. The combo should look like this.

   

   Initializing the array data

   We first create and initialize a two-dimensional array to hold the data to be displayed in the list.

6. Add the CLASS1.CLS file from the TUTOR13 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

   When using the ListBox control in Visual Basic, you store all of the data in the control using its AddItem (ListBox control) method.  This storage method is neither adequate nor efficient when you have a large amount of data or when the data source continuously changes.

   Unlike the ListBox control, True DBList's unbound modes do not store your data.  You manage the data while the list handles all display and end-user interactions.  Whenever the list needs to display more rows of data, such as during vertical scrolling, it will fire the UnboundReadData event to ask for data from your data source.  The list generally asks for only what it needs to display, but may cache some data for efficiency considerations.  You cannot predict when the list will ask for data, nor can you assume data will be requested in any particular order.  Furthermore, since the list does not store the data, any data that has been requested once may be requested again.

7. This example shows how data is provided to the combo via the RowBuffer object.  The class module CLASS1.CLS declares a private variable using the WithEvents (Visual Basic) keyword:

   Example Title	Copy Code
   Private WithEvents TDBC As TrueDBList80.TDBCombo

   This provides a convenient mechanism for encapsulating all of the unbound combo events into a self-contained class. 

   Since the WithEvents (Visual Basic) keyword is not supported by Visual Basic 4.0, the control's event handlers need to delegate the work to the appropriate subroutine in CLASS1.CLS.

   
   

   Example Title

   Copy Code

   ' Called when the Combo needs data Private Sub TDBC_UnboundReadData( _ ByVal RowBuf As TrueDBList80.RowBuffer, _ StartLocation As Variant, ByVal ReadPriorRows As Boolean) ' UnboundReadData is fired by a combo control whenever ' it requires data for display. This event will fire ' when the list is first shown, when Refresh or ReBind ' is used and when the list is scrolled. The ' list fetches data in "chunks", and the number of rows ' the list is asking for is given by RowBuf.RowCount. ' RowBuf is the row buffer where you place the data and ' the bookmarks for the rows that the list is requesting ' to display. It will also hold the number of rows that ' were successfully supplied to the list. ' StartLocation is a bookmark which specifies the row ' before or after the desired data, depending on the ' value of ReadPriorRows. If we are reading rows after ' StartLocation (ReadPriorRows = False), then the first ' row of data the list wants is the row after ' StartLocation, and if we are reading rows before ' StartLocation (ReadPriorRows = True) then the first ' row of data the list wants is the row before ' StartLocation. ' ReadPriorRows is a Boolean value indicating whether ' we are reading rows before (ReadPriorRows = True) or ' after (ReadPriorRows = False) StartLocation. Dim RowsFetched As Integer Dim I As Integer, J As Integer, RelPos As Integer Dim CurRow As Long RowsFetched = 0 If ReadPriorRows Then ' Requesting data in rows prior to StartLocation RelPos = -1 Else ' Requesting data in rows after StartLocation RelPos = 1 End If If IsNull(StartLocation) Then If ReadPriorRows Then ' StartLocation refers to EOF. CurRow = MaxRow - 1 Else ' StartLocation refers to BOF. CurRow = 0 End If Else CurRow = Val(StartLocation) + RelPos End If For I = 0 To RowBuf.RowCount - 1 ' If the next row is BOF or EOF, then stop ' fetching and return any rows fetched up to this ' point. If CurRow < 0 Or CurRow >= MaxRow Then Exit For ' Place the record data into the row buffer For J = 0 To RowBuf.ColumnCount - 1 RowBuf.Value(I, J) = ComboArray(J, CurRow) Next J ' Set the bookmark for the row RowBuf.Bookmark(I) = CurRow CurRow = CurRow + RelPos ' Increment the count of fetched rows RowsFetched = RowsFetched + 1 Next I RowBuf.RowCount = RowsFetched End Sub

8. The following implementation of the UnboundGetRelativeBookmark event demonstrates how to provide bookmarks to the unbound combo.  Although it is not required for DataMode 1 - Unbound, it will greatly improve speed and efficiency:

   Example Title

   Copy Code

   Private Sub TDBC_UnboundGetRelativeBookmark( _ StartLocation As Variant, ByVal OffSet As Long, _ NewLocation As Variant, ApproximatePosition As Long) Dim Index As Long ' TDBCombo calls this routine each time it needs to ' reposition itself. StartLocation is a bookmark ' supplied by the combo to indicate the "current" ' position -- the row we are moving from. Offset is ' the number of rows we must move from StartLocation ' in order to arrive at the desired destination row. ' A positive offset means the desired record is after ' the StartLocation, and a negative offset means the ' desired record is before StartLocation. ' If StartLocation is NULL, then we are positioning ' from either BOF or EOF. Once we determine the ' correct index for StartLocation, we will simply add ' the offset to get the correct destination row. If IsNull(StartLocation) Then If OffSet < 0 Then Index = MaxRow + OffSet Else Index = -1 + OffSet End If Else Index = Val(StartLocation) + OffSet End If ' If we are on a valid data row (that is, not at BOF or ' EOF), then set the ApproximatePosition (the ordinal ' row number) to improve scroll bar accuracy. If Index >= 0 And Index < MaxRow Then ApproximatePosition = Index NewLocation = Index Else NewLocation = Null End If End Sub

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

   Option Explicit

   Dim Sink As New Class1

10. 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 list to position the vertical scroll bar accurately.

    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 13.

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