TcxCustomDataController.SaveBookmark Method

Saves the focused record as a bookmark.

Declaration

procedure SaveBookmark;

Remarks

A bookmark is a reference to a record in a data controller. The SaveBookmark method saves the position of the currently focused record as a bookmark thus allowing you to return to this record later using the GotoBookmark procedure.

The data controller maintains only one bookmark. It is supported though by all loading modes (unbound, provider, bound, and grid). In unbound, provider and default bound modes, a bookmark is a record index of a record. In grid mode, a bookmark is a TBookmarkStr object returned by the TDataSet.Bookmark property.

You do not need to operate with bookmarks directly. Instead you should use the following methods:

• SaveBookmark. Saves a bookmark for the currently focused record.

• GotoBookmark. The method jumps to the record referred by the current bookmark.

• ClearBookmark. Removes the bookmark stored by SaveBookmark.

• IsBookmarkAvailable. Indicates whether a bookmark exists.

If you delete a bookmarked record, the bookmark will be deleted as well.

Bookmarks created by the SaveBookmark method are used only for data navigation, i.e. you can store the current record position as a bookmark and then jump to this position at any time using GotoBookmark. In the ExpressQuantumGrid, for instance, the SaveBookmark and GotoBookmark methods are available as navigator control buttons within in a Grid View.

In grid mode, the data controller maintains another type of bookmark – bookmarks for selected records. They are created automatically when you select record(s) and they provide the only way to access selected records in grid mode. The GetSelectedBookmark function allows you to access the bookmarks and selected records.

Selection bookmarks do not affect bookmarks created by the SaveBookmark method and vice versa. Bookmarks for selected and focused rows are created independently and are used for different purposes.

The data controller preserves bookmarks and the selected record after data is reloaded from the dataset. However, it may not correctly restore them if dataset records were deleted by another application.