TcxCustomEditProperties.OnPropertiesChanged Event

Occurs on every editor setting change.

Declaration

property OnPropertiesChanged: TNotifyEvent read; write;

Remarks

You can handle the OnPropertiesChanged event to execute custom code in response to editor setting changes.

Event Occurrence

The editor raises the OnPropertiesChanged event every time one of its settings changes in the corresponding TcxCustomEditProperties class descendant instance.

Event Occurrence and Batch Changes

The OnPropertiesChanged event occurs only once per batch property setting change (for all changes enclosed between BeginUpdate and EndUpdate procedure calls).

Tip

If you change multiple editor settings simultaneously, we recommend that you enclose them between BeginUpdate and EndUpdate calls to avoid excessive redraw operations and improve performance.

Event Parameter

You can use the Sender parameter to identify and access the TcxCustomEditProperties class descendant instance that raised the OnPropertiesChanged event.

Refer to the TNotifyEvent procedural type description for additional information on the event type.

Code Example

The code example in this topic section demonstrates an OnPropertiesChanged event handler for a TcxImageComboBox editor.

This event handler changes editor appearance and behavior in response to ReadOnly property value changes as follows:

Read-Only Mode

Hides the predefined drop-down button and displays the custom Info button at the left editor border when the ReadOnly property value changes to True.

Normal Mode

Restores the initial editor layout and behavior when the ReadOnly property value changes back to False.

Delphi

procedure TMyForm.cxImageComboBox1PropertiesChanged(Sender: TObject);
var
  AProperties: TcxImageComboBoxProperties;
  AButton: TcxEditButton;
begin
  AProperties := (Sender as TcxImageComboBoxProperties);
  if AProperties.ReadOnly then  // Configures the read-only editor layout
  begin
    AProperties.BeginUpdate;  // Initiates the following batch change
    try
      AProperties.Buttons.Items[0].Visible := False;  // Hides the predefined drop-down button
      if AProperties.Buttons.Count = 1 then
      begin
        AButton := AProperties.Buttons.Add;
        AButton.Kind := bkText;
        AButton.Caption := 'Info';
        AButton.LeftAlignment := True;
      end;
      AProperties.Buttons.Items[1].Visible := True;  // Displays the "Info" button
      AProperties.Buttons.Items[1].Default := True;
    finally
      AProperties.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
    end;
  end
  else if not AProperties.ReadOnly then  // Restores the initial editor layout
  begin
    AProperties.BeginUpdate;  // Initiates the following batch change
    try
      AProperties.Buttons.Items[0].Visible := True;  // Displays the predefined button
      AProperties.Buttons.Items[0].Default := True;
      if AProperties.Buttons.Count = 2 then
        AProperties.Buttons.Items[1].Visible := False; // Hides the "Info" button
    finally
      AProperties.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
    end;
  end;
end;

C++

void __fastcall TMyForm::cxImageComboBox1PropertiesChanged(TObject *Sender)
{
  TcxImageComboBoxProperties *AProperties;
  TcxButton *AButton;
  // ...
  AProperties = dynamic_cast<TcxImageComboBoxProperties*>(Sender);
  if(AProperties->ReadOnly)  // Configures the read-only editor layout
  {
    AProperties->BeginUpdate();  // Initiates the following batch change
    try
    {
      AProperties->Buttons->Items[0]->Visible = false;  // Hides the predefined drop-down button
      if(AProperties->Buttons->Count == 1)
      {
        AButton = AProperties->Buttons->Add();
        AButton->Kind = bkText;
        AButton->Caption = "Info";
        AButton->LeftAlignment = true;
      }
      AProperties->Buttons->Items[1]->Visible = true;  // Displays the "Info" button
      AProperties->Buttons->Items[1]->Default = true;
    }
    __finally
    {
      AProperties->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
    }
  }
  else if(!AProperties->ReadOnly)  // Restores the initial editor layout
  {
    AProperties->BeginUpdate();  // Initiates the following batch change
    try
    {
      AProperties->Buttons->Items[0]->Visible = true;  // Displays the predefined button
      AProperties->Buttons->Items[0]->Default = true;
      if(AProperties->Buttons->Count == 2)
        AProperties->Buttons->Items[1]->Visible = false;  // Hides the "Info" button
    }
    __finally
    {
      AProperties->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
    }
  }
}