Bookmarks in User Events Mode

Bookmarks are variants used by a TData control to uniquely identify a record (in other words, row) of data to be displayed or modified. Bookmarks also enable the data provider to quickly position to a specific record.

The bookmarks you provide are passed to bound controls directly, without interpretation. The bound controls then use individual bookmarks to position to specific records. When a row is modified, deleted, or used as a starting point for navigation, its bookmark is passed as a parameter to the appropriate True DataControl event handler.

You must supply bookmarks as variant data in response to the UserReadData and UserAddData events. In some cases, you may need to change the bookmark passed to the UserWriteData event, as when the value of a unique key field is used as a bookmark and the user edits its value.

You are free to use whatever you choose to identify a row, but each row must have its own unique bookmark. In general, you need to be able to search for the associated row or record quickly when given a bookmark. For example, if your data is stored in a Visual Basic array, the array's row index is an obvious choice for a bookmark.

The four common examples of what to use for bookmarks are:

If you have a proprietary database, you can use the values of a unique key field as bookmarks. That way, when given a bookmark, you can search and retrieve the associated record quickly.
If the database you use supports unique row IDs or record numbers, these can be conveniently used as bookmarks.
If you store your data in an ADO recordset; it is natural to use the bookmarks that you get retrieving rows from the ADO recordset.
If your data is stored in an array, the array's row index is an obvious choice for bookmarks.

An important point to remember is that all bookmarks must have the same variant type. True DataControl supports String, Long integer, and floating point bookmarks. All other data types must be converted to strings before they are used as variant bookmarks.