MoveBy
function MoveBy(Distance: Integer): Integer;
Example
procedure MoveForward(const Data: TvxClientDataSet; Requested: Integer;
var Actual: Integer);
begin
Actual := Data.MoveBy(Requested);
end;
Usage
MoveBy moves relatively by up to the requested record distance and returns the signed distance actually travelled.
- Compare the returned value with the requested distance to detect a boundary.
- Never assume movement succeeded solely because no exception was raised.
- Avoid zero-distance calls as harmless probes; they can resolve edits and invoke an unpaired before-scroll callback.
Additional Technical Info
MoveBy is declared by hidden ancestor TDataSet and is normally used through a visible descendant such as TvxClientDataSet. Positive moves forward, negative moves backward and zero performs no movement.
Source-backed behaviour
The base first calls CheckBrowseMode, so it can Post/Cancel pending state, then runs before-scroll. It advances through buffered/descendant records until the requested distance is exhausted or EOF/BOF is reached. The result increments for forward moves and decrements for backward moves; its magnitude can be smaller than requested.
Forward boundary sets EOF; backward boundary sets BOF. Negative movement invokes CheckBiDirectional when it needs a prior record and therefore raises for unidirectional datasets. Dataset-change/scroll and after-scroll events run in finally once movement enters the directional branch. A zero distance, or a request made while the matching boundary flag is already true, still runs CheckBrowseMode and DoBeforeScroll but skips that branch and therefore does not pair it with DoAfterScroll in this implementation.
Related members
Next calls a one-step forward path and Prior a one-step backward path. RecNo is descendant sequence metadata, not equivalent movement.