Professional Documents
Culture Documents
EMBAR C ADER O HO ME
LO C ATIO N | ENGLISH | LO G O N
COMMUNITIES
ARTICLES
BLOGS
RESOURCES
DOWNLOADS
HELP
RATING
Download Trial
Buy Now
Download Delphi XE7
now!
Get Free Trial
Special Offer
While this article focuses primarily on the use of code to navigate and edit data in a ClientDataSet, a natural
place to begin this discussion is with Delphi data-aware controls and the navigation and editing features
they provide.
Another DBNavigator property whose default value you may want to change is ShowHint. Some users have
difficulty interpreting the glyphs on the DBNavigator's buttons. For those users, setting ShowHint to True
supplements the glyphs with popup help hints. You can control the text of these hints by editing the Hints
property.
The second category of controls that provide navigation is the multi-record controls. Delphi includes two: the
DBGrid and DBCtrlGrid. A DBGrid displays data in a row/column format. By default, all fields of the
ClientDataSet are displayed in the DBGrid. You can control which fields are displayed, as well as specific
column characteristics, such as color, by editing the DBGrid's Columns collection property. The following is an
example of a DBGrid.
Delphi Free Trial
A DBCtrlGrid, by comparison, is a limited, multi-record container. It is limited in that it can only hold certain
Delphi components, including Labels, DBEdits, DBLabels, DBMemos, DBImages, DBComboBoxes,
DBCheckBoxes, DBLookupComboBoxes, and DBCharts. It is also limited in that it is not available in Kylix. As
a result, the DBCtrlGrid is little used. An example of a two-row, one-column DBCtrlGrid is shown in the
following figure.
edn.embarcadero.com/article/29122
1/6
08/09/2014
Depending on which multi-record control you are using, you can navigate between records using UpArrow,
DownArrow, Tab, Ctrl-End, Ctrl-Home, PgDn, PgUp, among others. These key presses may produce the
same effect as clicking the Next, Prior, Last, First, and so on, buttons in a DBNavigator. It is also possible to
navigate the records of a dataset using the vertical scrollbar of these controls.
How you edit a record using these controls also depends on which type of control you are using, as well as
their properties. Using the default properties of these controls, you can typically press F2 or click twice on a
field in one of these controls to begin editing. Posting a record occurs when you navigate off an edited
record. Inserting and deleting records, depending on the control's property settings, can also be achieved
using Ins and Ctrl-Del, respectively. Other operations, such as Refresh, are not directly supported.
Consequently, in most cases, multi-record controls are combined with a DBNavigator to provide a complete
set of record management options.
Webinars on demand!
Delphi
Like
There are additional event handlers that are available in most situations where a ClientDataSet is being
navigated and edited, and which are always available when data-aware controls are concerned. These are
the event handlers associated with a DataSource. Since all data-aware controls must be connected to at
least one DataSource, the event handlers of a DataSource provide you with another source of customization
when a user navigates and edits records. These event handlers are OnDataChange, OnStateChange, and
OnUpdateData.
OnDataChange triggers whenever a ClientDataSet arrives at a new records, as well as when a
ClientDataSet arrives at the first record when it is initially opened. OnStateChange triggers when a
ClientDataSet changes betw een state, such as when it changes from dsBrowse to dsEdit (when a user
enters the edit mode), or when it changes from dsEdit to dsBrowse (following the posting or cancellation of
a change). Finally, OnUpdateData triggers when the dataset to which the DataSource points is posting its
data.
Navigating Programmatically
Whether data-aware controls are involved or not, it is sometimes necessary to use code to navigate and
edit data in a ClientDataSet, or any DataSet descendent for that matter. For a ClientDataSet, these core
navigation methods include First, Next, Prior, Last, MoveBy, and RecNo. The use of First, Next, Prior, and
Last are pretty much self-explanatory. Each one produces an effect similar to the corresponding buttons on
a DBNavigator.
ARTICLE TAGS
ClientDataSet
MoveBy permits you to move forw ard and backw ard in a ClientDataSet, relative to the current record. For
example, the following statement moves the current cursor 5 records forward in the dataset (if possible):
ClientDataSet1.MoveBy(5);
To move backwards in a dataset, pass MoveBy a negative number. For example, the following statement will
move the cursor to the record that is 100 records prior to the current records (again, if possible):
ClientDataSet1.MoveBy(-100);
The use of RecNo to navigate might come as a surprise. This property, which is always returns -1 in the
TDataSet class, can be used for two purposes. You can read this property to learn the position of the
current record in the current record order (based on which index is currently selected). In the ClientDataSet
you can also write to this property. Doing so moves the cursor to the record in the position defined by the
value you assign to this property. For example, the following statement will move the cursor to the record in
the 5th position of the current index order (if possible):
ClientDataSet1.RecNo := 5;
Each of the preceding examples has been qualified by the statement that the operation will succeed if
possible. This qualification has two aspects to it. First, the cursor movement will not take place if the current
record has been edited, but cannot be posted. For example, if data that cannot pass at least one the
ClientDataSet's Contraints has been added to a record. When you attempt to navigate off a record that
cannot be posted, an exception is raised.
The second situation where the record navigation might not be possible is related to the current record
edn.embarcadero.com/article/29122
2/6
08/09/2014
position and the number of records in the dataset. For example, if the current record is the last in the
dataset, it makes no sense to move 5 records forward. Similarly, if the current record is the 99th in the
dataset, an attempt to move backwards by 100 records will fail. You can determine whether an attempt to
navigate succeeded or failed by reading the Eof and Bof properties of the ClientDataSet. Eof (end-of-file) will
return True if a navigation method attempted to move beyond the end of the table. When Eof returns True,
the current record is the last record in the dataset.
Similarly, Bof will return True if a backwards navigation attempted to move before the beginning of the
dataset. In that situation the current record is the first record in the dataset.
RecNo behaves differently. Attempting to set RecNo to a record beyond the end of the table, or prior to the
beginning of the table, raises an exception.
Scanning a ClientDataSet
Combining several of the methods and properties described so far provides you with a mechanism for
scanning a ClientDataSet. Scanning simply means the systematic navigation from one record to the next,
until all records in the dataset have been visited. The following code segment demonstrates how to scan a
ClientDataSet.
procedure TForm1.Button1Click(Sender:
TObject);
begin
if not ClientDataSet1.Active then ClientDataSet1.Open;
ClientDataSet1.First;
while not ClientDataSet1.EOF do
begin
//perform some operation based on one or
//more fields of the ClientDataSet
ClientDataSet1.Next;
end;
end;
Editing a ClientDataSet
You edit a current record in a ClientDataSet by calling its Edit method, after which you change the values of
one or more of its fields. Once your changes have been made, you can either move off the record to attempt
to post the new values, or you can explicitly call the ClientDataSet's Post method. In most cases, navigating
off the record and calling Post produce the same effect. But there are two instances where they do not, and
it is due to these situations that an explicit call to Post should be considered essential. In the first instance,
if you are editing the last record in a dataset and then call Next or Last, the edited record is not posted. The
second situation is similar, and involves editing the first record in a dataset followed by a call to either Prior
to First. So long as you always call Post prior to attempting to navigate, you can be assured that your
edited record will be posted (or raise an exception due to a posting failure).
If you modify a record, and then decide not to post the change, or discover that you cannot post the
change, you can cancel all changes to the record by calling the ClientDataSet's Cancel method. For example,
if you change a record, and then find that calling Post raises an exception, you can call Cancel to cancel the
changes and return the dataset to the dsBrowse state.
To insert and post a record you have several options. You can call Insert or Append, after which your cursor
will be on a newly inserted record (assuming that you started from the dsBrowse state. If you were editing
a record prior to calling Insert or Append, a new record will not be inserted if the record being edited can
not be posted). Once it is inserted, assign data to the fields or that record and call Post to post those
changes.
The alternative to calling Insert or Append is to call InsertRecord or AppendRecord. These methods insert a
new record, assign data to one or more fields, and attempt to post, all in a single call. The following is the
syntax of the InsertRecord method. The syntax of AppendRecord is identical.
procedure InsertRecord(const Values: array of const);
You include in the constant array the data values you want to assign to each field in the dataset. If you
want to leave particular field unassigned, include the value null in the variant array. Fields you want to leave
unassigned at the end of the record can be omitted from the constant array. For example, If you are
inserting and posting a new record into a four-field ClientDataSet, and you want to assign the first field the
value 1000 (a field associated with a unique index), leave the second and fourth fields unassigned, but
assign a value of 'new' to the third record, your InsertRecord invocation may look something like this:
ClientDataSet1.InsertRecord([1001, null,
'new']);
The following code segment demonstrates another instance of record scanning, this time with edits that
need to be posted to each record. In this example, Edit and Post are performed within try blocks. If the
record was placed in the edit mode (which corresponds to the dsEdit state), and cannot be posted, the
change is canceled. If the record cannot even be placed into edit state (which for a ClientDataSet should
only happen if the dataset has its ReadOnly property set to True), the attempt to post changes is skipped.
procedure TForm1.Button1Click(Sender:
TObject);
begin
if not ClientDataSet1.Active then ClientDataSet1.Open;
ClientDataSet1.First;
while not ClientDataSet1.EOF do
begin
try
ClientDataSet1.Edit;
try
ClientDataSet1.Fields[0].Value :=
UpperCase(ClientDataSet1.Fields[0].Value);
ClientDataSet1.Post;
except
//record cannot be posted. Cancel;
ClientDataSet1.Cancel;
end;
except
//Record cannot be edited. Skip
end;
ClientDataSet1.Next;
edn.embarcadero.com/article/29122
3/6
08/09/2014
Note: Rather than simply canceling changes that cannot be posted, an alternative except clause would
identify why the record could not post, and produce a log which can be used to apply the change at a later
date. Also note that if these changes are being cached, for update in a subsequent call to ApplyUpdates,
the ClientDataSet provides an OnReconcileError event handler that can be used to process failed postings.
Navigation Demonstration
The Navigation project, which you can download from Code Central by clicking this link Navi gation Project,
demonstrates the various methods and properties described in this article. The following figure shows this
project when it is running.
edn.embarcadero.com/article/29122
4/6
08/09/2014
Each of the Buttons on this form is associated with an event handler that performs the indicated type of
navigation. In addition, this project includes OnDataChange and OnStateChange DataSource event
handlers that are used to update the panels in the StatusBar at the bottom of the form. These event
handlers are shown in the following code listing.
procedure TForm1.SelectDataFile;
begin
if OpenDialog1.Execute then
begin
if ClientDataSet1.Active then ClientDataSet1.Close;
ClientDataSet1.FileName := OpenDialog1.FileName;
ClientDataSet1.Open;
end
else
Halt;
end;
procedure TForm1.FormCreate(Sender: TObject);
begin
SelectDataFile;
end;
procedure TForm1.DataSource1DataChange(Sender: TObject; Field: TField);
begin
StatusBar1.Panels[0].Text := 'Record ' +
IntToStr(ClientDataSet1.RecNo) + ' of ' +
IntToStr(ClientDataSet1.RecordCount);
StatusBar1.Panels[2].Text :=
'BOF = ' + BoolToStr(ClientDataSet1.Bof, True) +
'. ' +
'EOF = ' + BoolToStr(ClientDataSet1.Eof, True) +
'. ';
end;
procedure TForm1.DataSource1StateChange(Sender: TObject);
begin
StatusBar1.Panels[1].Text :=
'State = ' + GetEnumName(TypeInfo(TDataSetState),
Ord(ClientDataSet1.State));
end;
procedure TForm1.FirstBtnClick(Sender: TObject);
begin
ClientDataSet1.First;
end;
procedure TForm1.NextBtnClick(Sender: TObject);
begin
ClientDataSet1.Next;
end;
procedure TForm1.PriorBtnClick(Sender: TObject);
begin
ClientDataSet1.Prior;
end;
procedure TForm1.LastBtnClick(Sender: TObject);
begin
ClientDataSet1.Last;
end;
edn.embarcadero.com/article/29122
5/6
08/09/2014
LATEST COMMENTS
Move mouse over comment to see the full text
edn.embarcadero.com/article/29122
Site Map
6/6