| Object Reference > True DBGrid Events > UnboundReadDataEx Event |
UnboundReadDataEx Event
The UnboundReadDataEx event is fired when an unbound grid (one with its DataMode property set to 2 - Unbound Extended) requires a bookmark for a specific row or data for display, such as when it is first loaded or the user scrolls the grid display.
object_UnboundReadDataEx (ByVal RowBuf As TrueDBGrid80.RowBuffer, StartLocation As Variant, ByVal Offset As Long, ApproximatePosition As Long)
Arguments
RowBuf is a RowBuffer object used to transfer row data to the grid.
StartLocation is a bookmark that, together with Offset, specifies the starting row for data transfer. A StartLocation of Null indicates a request for data from BOF or EOF. For example, if StartLocation is Null and Offset is 2 (or -2), then you should retrieve data starting from the second (or second to last) row.
Offset specifies the relative position (from StartLocation) of the first row of data to be transferred. A positive number indicates a forward relative position; a negative number indicates a backward relative position.
ApproximatePosition is a variable that optionally receives the ordinal position of the first row of data to be transferred. Setting this variable will enhance the ability of the grid to display its vertical scroll bar accurately. If the exact ordinal position of the row is not known, you can set it to a reasonable, approximate value, or just ignore this parameter.
Before returning from the UnboundReadDataEx event, you must fill the Bookmark array of RowBuf with unique row identifiers, and the Value array with the actual data. For example, if Offset is 1 (or -1), then you must fill in RowBuf, starting from the row that follows (or precedes) StartLocation.
The RowBuf argument acts like a two-dimensional array of variants corresponding to the grid cells being fetched. By populating its Value property with the appropriate data, your event procedure transfers rows from the unbound dataset to the grid.
Use the row buffer's RowCount property to determine how many rows of data the grid is requesting. Use its ColumnCount property to determine the number of columns to be populated, if any. If ColumnCount is zero, the grid is requesting the bookmark of a single row; if ColumnCount is nonzero, the grid is requesting RowCount rows of data and their corresponding bookmarks.
The ColumnIndex property specifies the grid column index corresponding to a row buffer column index; you must fill in the Value property array with column data according to the column index specified by the ColumnIndex property array.
The RowBuf argument is also used to store a set of variant bookmarks that uniquely identify rows in the unbound dataset. The format of these bookmarks is determined solely by your application. For example, they may be primary key fields, row numbers, or array indexes, depending upon the nature of the unbound dataset.
Your event procedure supplies bookmarks to the grid by populating the row buffer's Bookmark property for each row returned. Keep in mind that the bookmarks you provide in the UnboundReadDataEx event may be subsequently passed to the UnboundWriteData and UnboundDeleteRow events depending on how the user interacts with the grid. In addition, bookmark-based TDBGrid properties and methods such as Bookmark, FirstRow, GetBookmark, and RowBookmark are also designed to work with these unbound bookmarks.
It is not necessary to fill the row buffer completely, and it is in fact acceptable to return no rows at all. The row buffer's RowCount property can be set to indicate that fewer rows were returned than requested. The grid interprets this to mean that there are no more rows to retrieve in the indicated direction. Thus, it is only necessary to fill the row buffer completely if there are more valid rows to be retrieved.