Handling the UnboundGetRelativeBookmark event in mode 3

You must always provide a handler for the UnboundGetRelativeBookmark event in application mode. True DBList fires this event whenever it needs to determine the bookmark that identifies a row given a starting bookmark and a long integer offset. The starting bookmark may be Null, which denotes BOF if the offset is positive, EOF if the offset is negative. The offset may be positive to denote forward movement, or negative to denote backward movement. The syntax for this event is as follows:

Example Title	Copy Code
Private Sub TDBList1_UnboundGetRelativeBookmark( _ StartLocation As Variant, ByVal Offset As Long, _ NewLocation As Variant, ApproximatePosition As Long)

StartLocation is a bookmark which, together with Offset, specifies the row to be returned in NewLocation.

Offset specifies the relative position (from StartLocation) of the row to be returned in NewLocation. A positive number indicates a forward relative position while a negative number indicates a backward relative position.

NewLocation is a variable which receives the bookmark of the row which is specified by StartLocation plus Offset. If the row specified is beyond the first or the last row (or beyond BOF or EOF), then NewLocation should be set to Null.

ApproximatePosition is a variable which receives the ordinal position of NewLocation. Setting this variable will enhance the ability of the list to display its vertical scroll bar accurately. If the exact ordinal position of NewLocation is not known, you can set it to a reasonable, approximate value, or just ignore it altogether.

Before returning from the UnboundGetRelativeBookmark event, you must set NewLocation to a valid bookmark. For example, if Offset is 1 (or -1), then you must return in NewLocation the bookmark of the row that follows (or proceeds) StartLocation. However, if the requested row is beyond the first or last row, then you should return Null in NewLocation to inform the list of BOF/EOF conditions.

Similarly, a StartLocation of Null indicates a request for a row from BOF or EOF. For example, if StartLocation is Null and Offset is 2 (or -2), then you must return in NewLocation the bookmark of the second (or second to last) row. The following code template provides the basis for a typical implementation of the UnboundGetRelativeBookmark event:

Example Title	Copy Code
If IsNull(StartLocation) Then If Offset < 0 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 ' via one of the unbound events. It is up to the VB ' programmer to ensure the bookmark is valid, and to take ' the appropriate action if it is not. End If

Example Title

Copy Code

If IsNull(StartLocation) Then

    If Offset < 0 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

    ' via one of the unbound events. It is up to the VB

    ' programmer to ensure the bookmark is valid, and to take

    ' the appropriate action if it is not.

End If

The UnboundGetRelativeBookmark event is also used to improve performance in DataMode 1 - Unbound. For more information, see Unbound Mode.