TDataSet.MoveBy Method

Moves to another record relative to the active record in the dataset.

Pascal

function MoveBy(Distance: Integer): Integer; virtual;

C++

virtual __fastcall int MoveBy(int Distance);

Description

Call MoveBy to move the active record by the number of records specified by Distance. A positive value for Distance indicates forward progress through the dataset, while a negative value indicates backward progress. For example, the following statement moves backward through the dataset by 10 records:

Copy Code

MoveBy(-10);

Copy Code

DataSet1->MoveBy(-10);

MoveBy posts any changes to the active record and

Sets the Bof and Eof properties to false.

If Distance is positive, repeatedly fetches Distance subsequent records (if possible), and makes the last record fetched active. If an attempt is made to move past the end of the file, MoveBy sets Eof to true.

If Distance is negative, repeatedly fetches the appropriate number of previous records (if possible), and makes the last record fetched active. If an attempt is made to move past the start of the file, MoveBy sets Bof to true. If the dataset is unidirectional, the dataset raises an EDatabaseError exception when MoveBy tries to fetch a prior record.

Broadcasts information about the record change so that data-aware controls and linked datasets can update.

Returns the number of records moved. In most cases, Result is the absolute value of Distance, but if MoveBy encounters the beginning-of-file or end-of-file before moving Distance records, Result will be less than the absolute value of Distance.

C++ Examples:

Copy Code

/*
The following example enables the user to move the current
selected cell in a db grid.  The Up and Down buttons have
their OnClick events assigned to the UpDownClick procedure.
The Left and Right buttons have their OnClick events
assigned to the LeftRightClick procedure.  The Up and Left
buttons have their Tag property set to -1, while the Down
and Right buttons have their Tag property set to 1.  MoveBy
does not move the cell in the db grid, it only moves the
selection.  The data set is not edited.  Notice that the
Up button and the Down button are separate TButtons, not
one TUpDown.  The tags must be set different.
*/
void __fastcall TForm1::UpDownClick(TObject *Sender)
{
  CDS2->MoveBy((dynamic_cast<TComponent *>(Sender))->Tag);
  DBGrid2->SetFocus();
}

void __fastcall TForm1::LeftRightClick(TObject *Sender)
{
  DBGrid2->SelectedIndex = DBGrid2->SelectedIndex + (dynamic_cast<TComponent *>(Sender))->Tag;
  DBGrid2->SetFocus();
}

Delphi Examples:

Copy Code

{
The following example enables the user to move the current
selected cell in a db grid.  The Up and Down buttons have
their OnClick events assigned to the UpDownClick procedure.
The Left and Right buttons have their OnClick events
assigned to the LeftRightClick procedure.  The Up and Left
buttons have their Tag property set to -1, while the Down
and Right buttons have their Tag property set to 1.  MoveBy
does not move the cell in the db grid, it only moves the
selection.  The data set is not edited.  Notice that the
Up button and the Down button are separate TButtons, not
one TUpDown.  The tags must be set different.
}
procedure TForm1.UpDownClick(Sender: TObject);
begin
  CDS.MoveBy(TComponent(Sender).Tag);
  DBGrid1.SetFocus;
end;

procedure TForm1.LeftRightClick(Sender: TObject);
begin
  DBGrid1.SelectedIndex := DBGrid1.SelectedIndex + TComponent(Sender).Tag;
  DBGrid1.SetFocus;
end;