TcxCustomGridTableItem.OnGetProperties Event

This event is fired when getting the properties of an editor used to display and edit the contents of an item cell for a specific record.

Declaration

property OnGetProperties: TcxGridGetPropertiesEvent read; write;

Remarks

The OnGetProperties and OnGetPropertiesForEdit events allow you to implement the MultiEditors feature, i.e. provide different editors to display and edit the cells of a single item. Generally, the MultiEditors feature is used in unbound mode, when you know the type of data stored in a specific item cell.

You can handle the OnGetProperties event to change the default item editor that is used to display the contents of an item cell for a specific record. If the OnGetPropertiesForEdit event is not handled, the OnGetProperties event handler also specifies the default item editor which will be used to edit the contents of an item cell when in-place editing is initiated.

The ARecord parameter specifies the record for which an item editor should be determined. The RepositoryItem and PropertiesClass properties can be used to specify the default item editor (the editor used to edit all the cells of the current item). If they are not specified, the item is assigned an editor based on the field type (in bound mode) or on the DataBinding.ValueTypeClass property (in unbound mode). Refer to the FieldName property and TcxValueType class properties for details.

The properties of the default item editor are passed in the AProperties parameter. To redefine the default editor, assign another properties object (a TcxCustomEditProperties descendant) which corresponds to the required editor to the AProperties parameter.

If you need to provide different edit properties within an event, you can use the edit repository (the TcxEditRepository component) as a storage for particular edit properties. Create repository items corresponding to specific editors and adjust their edit properties. Then use the Properties object of these repository items to return it in the AProperties parameter.

Note: You must avoid situations which require modifying edit properties passed in the AProperties parameter within the OnGetProperties event. Assume you need to disable editing of the first item cell while allowing a user to edit the other item cells. When handling the OnGetProperties event, you should not use the following code:

Delphi

if ARecord.RecordIndex = 0 then
  AProperties.ReadOnly := True
else
  AProperties.ReadOnly := False;

C++

if (ARecord->RecordIndex == 0)
  AProperties->ReadOnly = true
else
  AProperties->ReadOnly = false;

Instead, you should create two repository items and modify their ReadOnly property as required outside the OnGetProperties event handler; then return edit properties of these repository items in the OnGetProperties event handler. The correct code for the OnGetProperties event is as follows:

Delphi

if ARecord.RecordIndex = 0 then
  AProperties := RepositoryItem1.Properties
else
  AProperties := RepositoryItem2.Properties;

C++

if (ARecord->RecordIndex == 0)
  AProperties = RepositoryItem1->Properties
else
  AProperties = RepositoryItem2->Properties;

The following code assumes that the required repository items were created and modified via the edit repository. Different edit properties are specified for the Grade column based on the record index:

Delphi

const
  SkillCount = 6;
procedure TColumnsMultiEditorsDemoMainForm.clnGradeGetProperties(
  Sender: TcxCustomGridTableItem; ARecord: TcxCustomGridRecord;
  var AProperties: TcxCustomEditProperties);
begin
  case ARecord.RecordIndex mod SkillCount of
    //specify the spin editor for records 0, 6, 12, etc.
    0: AProperties := SpinRepositoryItemYears.Properties;
    //specify the image combo box for records 1,2, 7,8, etc.
    1, 2: AProperties := ImageComboRepositoryItemLanguages.Properties;
    //specify another image combo box for records 3, 9, 15, etc.
    3: AProperties := ImageComboRepositoryItemCommunication.Properties;
    //specify the date edit for records 4, 10, 16, etc
    4: AProperties := DateRepositoryItemStartWorkFrom.Properties;
    //for records 5, 11, 17 etc, the default editor
    //(text edit in unbound mode) is used
  end;
end;

C++

const
  SkillCount = 6;
void __fastcall TColumnsMultiEditorsDemoMainForm::clnGradeGetProperties(
  TcxCustomGridTableItem *Sender, TcxCustomGridRecord *ARecord,
  TcxCustomEditProperties *&AProperties) {
  switch(ARecord->RecordIndex % SkillCount) {
    //specify the spin editor for records 0, 6, 12, etc.
    case 0:
      AProperties = SpinRepositoryItemYears->Properties;
      break;
    //specify the image combo box for records 1,2, 7,8, etc.
    case 1, 2:
      AProperties = ImageComboRepositoryItemLanguages->Properties;
      break;
    //specify another image combo box for records 3, 9, 15, etc.
    case 3:
      AProperties = ImageComboRepositoryItemCommunication->Properties;
      break;
    //specify the date edit for records 4, 10, 16, etc
    case 4:
      AProperties = DateRepositoryItemStartWorkFrom->Properties;
      break;
    //for records 5, 11, 17 etc, the default editor
    //(text edit in unbound mode) is used
  }
end;

For the complete example, see the ColumnsMultiEditorsDemo.