TcxCustomDataController.Append Method

Appends a new record to the underlying dataset.

Declaration

procedure Append; virtual;

Remarks

Call this method to add a new record to your data controller. If the data controller represents dataset data (TcxDBDataController), the Append method just calls the TDataSet.Append method and this

1. Creates a new record at the end of the dataset

2. Sets the active record to the new record

After the record becomes active, a user can set its field values and then post those changes. To set values via code, use the methods and properties of the dataset (for instance, TDataSet.FieldValues). To post changes, see the Post method (you can also use the Post method provided by the dataset).

In provider and unbound modes, Append behaves in a similar manner: It adds a new record and focuses it. When in these modes, you should use the Values property to set field values. To identify a particular cell, you should know its record and item indexes. The Append method does not return the index of the new record. To work around this, use the FocusedRecordIndex property after adding a new record.

When a record is added using the Append method, data changes are not immediately posted. Thus you can cancel changes until the data posting is performed. If the record is cancelled, all changes are lost and the record is deleted. A user can cancel the new record by pressing the Esc key. To cancel modifications via code, see the Cancel method.

In provider and unbound modes, you can use the AppendRecord method to add a new record. AppendRecord retrieves the record index that can be used to access its field values via the Values property. The record added by AppendRecord does not require posting. Also such a record cannot be discarded by calling the Cancel method.

Note

Do not call the Append method within the BeginUpdate/EndUpdate and BeginFullUpdate/EndFullUpdate blocks.