TcxCustomDataController.Insert Method

Inserts a new record in a data controller.

Declaration

procedure Insert; virtual;

Remarks

The Insert method inserts a new record in a data controller. This method sets the dceInsert flag in the EditState property.

In bound mode, when the data controller (TcxDBDataController) represents dataset records, the Insert method merely calls the TDataSet.Insert method. It performs the following:

• Opens a new, empty dataset record.

• Sets the active record to the new record.

The TDataSet.Insert method fires the TDataSet.BeforeInsert and TDataSet.AfterInsert events, thus allowing you to perform actions before and after insert mode is activated.

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, Insert behaves in a similar manner: It inserts a new record at the position specified by the currently focused record and then sets focus to it. In these modes, you should use the Values property to set field values. This property needs record and item indexes to identify a particular cell. The Insert method does not return the index of the inserted record. To work around this, use the FocusedRecordIndex property after inserting.

If a record is inserted using the Insert method, it is not immediately posted to the data source. Thus, you can cancel the insertion as long as posting is not performed. If canceling, the inserted record is deleted and all changes are lost. End-users can perform this by pressing the Esc key. The Cancel method enables you to cancel changes via code.

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

Note

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