TcxComboBox Class

An unbound combo box.

Declaration

TcxComboBox = class(
    TcxCustomComboBox
)

Remarks

A combo box editor combines a single-line text editor and a drop-down menu. The drop-down menu displays a list of text strings accessible through the Properties.Items property. If user input in the text edit box matches initial characters in a menu string, the combo box allows a user to autocomplete the current input with the full string.

Tip

You can use a TcxComboBox class instance as a standalone or in-place combo box editor.

End-User Input Options

↑ and ↓ keys allow users to switch between combo box items, even when the drop-down menu is closed. Ctrl + PageUp and Ctrl + PageDown keystrokes select first and last items, respectively.

Drop-Down Menu Interaction

Users can do the following to open or close the drop-down combo box menu:

• Click the drop-down button.
• Focus the combo box and press the Alt + ↑ or Alt + ↓ key combination.
• Focus the combo box and press the F4 key.

Note

You can open the drop-down menu only if it contains at least one value.

Main API Members

The list below outlines key members of the TcxComboBox class that allow you to configure combo boxes and manage combo box items.

Appearance and Behavior Settings

BeepOnEnter

Specifies if the combo box plays the default system sound when a user confirms input.

Style | StyleDisabled | StyleFocused | StyleHot | StyleReadOnly

Allow you to define individual appearance settings for different editor states.

Tip

To apply the same style settings to multiple editors, use a TcxEditStyleController component. If you need to apply the same style settings to all editors in your application, you can use a TcxDefaultEditStyleController component.

Styles

Provides access to individual styles applied to the combo box in different states.

Content-Related APIs

Clear | EditingValue | EditValue | EditingText | EditText | ResetEditValue

Manage the edit value.

CopyToClipboard | CutToClipboard | PasteFromClipboard

Allow you to perform clipboard operations.

CanDropDown | DroppedDown | CloseUp

Manage the drop-down menu.

ItemIndex

Specifies the active combo box item.

OnEditing

Allows you to prevent users from activating the combo box.

PopupWindow

Allows you to access and customize the drop-down menu.

ResetEditValue

Restores the previous edit value before the pending change is applied.

SelectAll

Selects editor content.

SelStart | SelLength | SelText | SetSelection | SelectAll | ClearSelection

Manage content selection.

TextHint

Specifies a text hint for the combo box when it has no assigned edit value.

Undo

Discards the last content change when the combo box has focus.

ValidateEdit

Validates the display value.

Combo Box Settings and Repository Items

ActiveProperties

Provides access to the current combo box settings regardless of their source. This property set does not allow you to customize combo box settings.

GetPropertiesClass

Returns the actual editor settings type.

Properties

Allows you to customize combo box settings directly if the combo box does not have an assigned repository item.

RepositoryItem

Specifies a repository item as an external source of combo box settings. A repository item has priority over other combo box settings.

General-Purpose API Members

Enabled

Specifies if the combo box is enabled.

CanModify

Identifies if the combo box is in read-only mode.

IsEditValidating | IsHiding | IsPosting

Allow you to identify the current operation in the combo box.

Width | Height

Allow you to explicitly define combo box dimensions.

Code Examples

Populate the Combo Box Menu from a Dataset Field

The code example in this section does the following:

• Assigns a TcxComboBox as an in-place editor to the Names column in a data-aware Data Grid View.
• Populates the editor’s drop-down window with values from the underlying dataset field.

Tip

If you need to add a user input string as a new combo box item, handle the OnNewLookupDisplayText event.

How to Test this Code Example

Follow the steps below to test this code example in your RAD Studio IDE:

1. Copy the DFM code example in this section.
2. Create a new project in the IDE and focus an empty form.
3. Press Ctrl + V to populate the form with preconfigured components.
4. Create an empty OnCreate event handler for the form and paste the code example into the handler.
5. Add the cxDropDownEdit unit to the uses clause and run the project.

DFM

  object cxGrid1: TcxGrid
   Left = 72
   Top = 80
   Width = 545
   Height = 200
   TabOrder = 0
   object cxGrid1DBTableView1: TcxGridDBTableView
     Navigator.Buttons.CustomButtons = <>
     ScrollbarAnnotations.CustomAnnotations = <>
     DataController.DataSource = DataSource1
     DataController.Summary.DefaultGroupSummaryItems = <>
     DataController.Summary.FooterSummaryItems = <>
     DataController.Summary.SummaryGroups = <>
     object cxGrid1DBTableView1RecId: TcxGridDBColumn
       DataBinding.FieldName = 'RecId'
       Visible = False
     end
     object cxGrid1DBTableView1Groups: TcxGridDBColumn
       DataBinding.FieldName = 'Groups'
     end
     object cxGrid1DBTableView1Names: TcxGridDBColumn
       DataBinding.FieldName = 'Names'
     end
     object cxGrid1DBTableView1Values: TcxGridDBColumn
       DataBinding.FieldName = 'Values'
       Width = 54
    end
   end
   object cxGrid1Level1: TcxGridLevel
     GridView = cxGrid1DBTableView1
   end
 end
 object dxMemData1: TdxMemData
   Active = True
   Indexes = <>
   Persistent.Data = {
     5665728FC2F5285C8FFE3F04000000140000000100070047726F757073001400
     0000010006004E616D657300040000000300070056616C756573000400000009
     000600446174657300010600000047726F75703101050000004E616D6531010A
     000000017B000B00010600000047726F75703101050000004E616D6532011400
     000001CF0E0B00010600000047726F75703201050000004E616D6533011E0000
     00017A210B00010600000047726F75703201050000004E616D65340128000000
     01892B0B00}
   SortOptions = []
   Left = 520
   Top = 88
   object dxMemData1Groups: TStringField
     FieldName = 'Groups'
   end
   object dxMemData1Names: TStringField
     FieldName = 'Names'
   end
   object dxMemData1Values: TIntegerField
     FieldName = 'Values'
   end
   object dxMemData1Dates: TDateField
     FieldName = 'Dates'
   end
 end
 object DataSource1: TDataSource
   DataSet = dxMemData1
   Left = 472
   Top = 176
 end

Delphi

uses
  cxDropDownEdit;  // Declares the TcxComboBoxProperties class
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  AProperties: TcxComboBoxProperties;
begin
  // Assign a combo box as an in-place editor for the "Names" grid column
  cxGrid1DBTableView1Names.PropertiesClass := TcxComboBoxProperties;
  AProperties := cxGrid1DBTableView1Names.Properties as TcxComboBoxProperties;
  AProperties.BeginUpdate;  // Initiates the following batch operation
  try
    AProperties.Sorted := True;  // Sorts prepopulated values
    AProperties.DropDownListStyle := lsFixedList;  // Limits user input to the prepoulated list
    AProperties.DropDownAutoWidth := False;  // Disables automatic menu width adjustment
    AProperties.DropDownWidth := 105;  // Sets a fixed drop-down menu width
    // Populate the combo box editor's drop-down menu from the "Names" dataset field
    dxMemData1.DisableControls;
    try
      dxMemData1.First;
      while not dxMemData1.Eof do
      begin
        AProperties.Items.Add(dxMemData1.FieldByName('Names').AsString);
        dxMemData1.Next;
      end;
      dxMemData1.First;
    finally
      dxMemData1.EnableControls;
    end;
  finally
    AProperties.EndUpdate;  // Calls EndUpdate regardless of the batch operation's success
  end;
end;

C++

#include "cxDropDownEdit.hpp"  // Declares the TcxComboBoxProperties class

// Add the following linker directive to the corresponding CPP source file:
#pragma link "cxDropDownEdit"  // Required to use cxDropDownEdit declarations

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TcxComboBoxProperties *AProperties;
  // Assign a combo box as an in-place editor for the "Names" grid column
  cxGrid1DBTableView1Names->PropertiesClass = __classid(TcxComboBoxProperties);
  AProperties = dynamic_cast<TcxComboBoxProperties*>(cxGrid1DBTableView1Names->Properties);
  AProperties->BeginUpdate();  // Initiates the following batch operation
  try
  {
    AProperties->Sorted = true;  // Sorts prepopulated values
    AProperties->DropDownListStyle = lsFixedList;  // Limits user input to the prepopulated list
    AProperties->DropDownAutoWidth = false;  // Disables automatic menu width adjustment
    AProperties->DropDownWIdth = 105;  // Sets a fixed drop-down menu width
    // Populate the combo box editor's drop-down menu from the "Names" dataset field
    dxMemData1->DisableControls();
    try
    {
      dxMemData1->First;
      do
      {
        AProperties->Items->Add(dxMemData1->FieldByName("Names")->AsString);
        dxMemData1->Next();
      } while(!dxMemData1->Eof);
    }
    __finally
    {
      dxMemData1->EnableControls();
    }
  }
  __finally
  {
    AProperties->EndUpdate();  // Calls EndUpdate regardless of the batch operation's success
  }
}

Add and Post a New Combo Box Value to the Bound Dataset Field

The code example in this section applies the following changes to an in-place combo box editor of the Names column in a data-aware Data Grid View:

• Adds a new combo box item if a user enters a string that does not match any existing combo box item.
• Creates a new record and sets the custom text entry as a value of the new cell in the Names column.

How to Test this Code Example

Follow the steps below to test this code example in your RAD Studio IDE:

1. Copy the DFM code example in this section.
2. Create a new project in the IDE and focus an empty form.
3. Press Ctrl + V to populate the form with preconfigured components.
4. Select the Names column and expand the Properties node in the Events tab of the Object Inspector.
5. Create an empty OnNewLookupDisplayText event handler, paste the code example, and run the project.

DFM

  object cxGrid1: TcxGrid
   Left = 72
   Top = 80
   Width = 545
   Height = 200
   TabOrder = 0
   object cxGrid1DBTableView1: TcxGridDBTableView
     Navigator.Buttons.CustomButtons = <>
     ScrollbarAnnotations.CustomAnnotations = <>
     DataController.DataSource = DataSource1
     DataController.Summary.DefaultGroupSummaryItems = <>
     DataController.Summary.FooterSummaryItems = <>
     DataController.Summary.SummaryGroups = <>
     object cxGrid1DBTableView1RecId: TcxGridDBColumn
       DataBinding.FieldName = 'RecId'
       Visible = False
     end
     object cxGrid1DBTableView1Groups: TcxGridDBColumn
       DataBinding.FieldName = 'Groups'
     end
     object cxGrid1DBTableView1Names: TcxGridDBColumn
       DataBinding.FieldName = 'Names'
       PropertiesClassName = 'TcxComboBoxProperties'
       Properties.Items.Strings = (
         'Name1'
         'Name2'
         'Name3'
         'Name4')
     end
     object cxGrid1DBTableView1Values: TcxGridDBColumn
       DataBinding.FieldName = 'Values'
       Width = 54
     end
   end
   object cxGrid1Level1: TcxGridLevel
     GridView = cxGrid1DBTableView1
   end
 end
 object dxMemData1: TdxMemData
   Active = True
   Indexes = <>
   Persistent.Data = {
     5665728FC2F5285C8FFE3F04000000140000000100070047726F757073001400
     0000010006004E616D657300040000000300070056616C756573000400000009
     000600446174657300010600000047726F75703101050000004E616D6531010A
     000000017B000B00010600000047726F75703101050000004E616D6532011400
     000001CF0E0B00010600000047726F75703201050000004E616D6533011E0000
     00017A210B00010600000047726F75703201050000004E616D65340128000000
     01892B0B00}
   SortOptions = []
   Left = 520
   Top = 88
   object dxMemData1Groups: TStringField
     FieldName = 'Groups'
   end
   object dxMemData1Names: TStringField
     FieldName = 'Names'
   end
   object dxMemData1Values: TIntegerField
     FieldName = 'Values'
   end
   object dxMemData1Dates: TDateField
     FieldName = 'Dates'
   end
 end
 object DataSource1: TDataSource
   DataSet = dxMemData1
   Left = 472
   Top = 176
 end

Delphi

procedure TMyForm.ComboBox(
  Sender: TObject; const AText: TCaption);
var
  AProperties: TcxComboBoxProperties;
begin
  AProperties := cxGrid1DBTableView1Names.Properties as TcxComboBoxProperties;
  dxMemData1.DisableControls;
  try
    dxMemData1.Append;
    AProperties.Items.Add(AText);
    cxGrid1DBTableView1Names.DataBinding.Field.AsString := AText;
    dxMemData1.Post;
  finally
    dxMemData1.EnableControls;
  end;
end;

C++

void __fastcall TMyForm::ComboBox(TObject *Sender, const TCaption &AText)
{
  TcxComboBoxProperties *AProperties;
  // ...
  AProperties = dynamic_cast<TcxComboBoxProperties*>(cxGrid1DBTableView1Names->Properties);
  dxMemData1->DisableControls();
  try
  {
    dxMemData1->Append();
    AProperties->Items->Add(AText);
    cxGrid1DBTableView1Names->DataBinding->Field->AsString = AText;
    dxMemData1->Post();
  }
  __finally
  {
    dxMemData1->EnableControls();
  }
}

Repository Item Class

You can create a TcxEditRepositoryComboBoxItem component in an edit repository to define an unbound combo box, store combo box settings, and share them between multiple combo boxes.

Inheritance

Show 16 items

TObject

TPersistent

TComponent

TControl

TWinControl

TCustomControl

TcxCustomControl

TcxControl

TcxContainer

TcxCustomEditContainer

TcxCustomEdit

TcxCustomTextEdit

TcxCustomMaskEdit

TcxCustomDropDownEdit

TcxCustomComboBox

TcxComboBox