Represents a multi-column combo box control that provides a dropdown grid interface for data selection. This control combines the functionality of a text box with a grid-based dropdown for enhanced data browsing and selection.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.GridView.dll
Syntax:
[TelerikToolboxCategory("Data Controls")]
[LookupBindingProperties("DataSource", "DisplayMember", "ValueMember", "SelectedValue")]
[DefaultBindingProperty("Text")]
public class RadMultiColumnComboBox : RadEditorControl, IDropTarget, ISynchronizeInvoke, IWin32Window, IBindableComponent, IComponent, IDisposable, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IAnalyticsProviderInheritance: objectMarshalByRefObjectComponentControlScrollableControlRadControlRadEditorControlRadMultiColumnComboBox...
Implements:
Inherited Members
Constructors
Initializes a new instance of the RadMultiColumnComboBox class with default settings. Sets up basic control properties including auto-sizing, tab behavior, and selection capabilities.
public RadMultiColumnComboBox()Properties
Gets or sets the automatic completion mode for the text entry portion of the combo box. This property is not applicable for RadMultiColumnComboBox and should not be used.
[Browsable(false)]
public AutoCompleteMode AutoCompleteMode { get; set; }Gets or sets a value indicating whether automatic filtering is enabled based on user input. When enabled, the dropdown list is filtered as the user types in the text box.
public bool AutoFilter { get; set; }Gets or sets the delay in milliseconds between the last key press and the start of the filtering operation. This property helps optimize performance by preventing excessive filtering during rapid typing.
public int AutoFilterDelay { get; set; }Gets or sets a value indicating whether the control is automatically resized to display its entire contents. This property controls the auto-sizing behavior of the entire combo box control.
[Browsable(true)]
public override bool AutoSize { get; set; }Overrides:
Gets or sets the mode for automatically sizing columns in the dropdown portion of the control. Determines whether columns are sized based on visible cells, all cells, or other criteria.
public virtual BestFitColumnMode AutoSizeDropDownColumnMode { get; set; }Gets or sets a value indicating whether the dropdown height automatically adjusts when filtering is applied. When enabled, the dropdown shrinks or expands based on the number of filtered results.
public bool AutoSizeDropDownHeight { get; set; }Gets or sets a value indicating whether the dropdown automatically resizes to best fit all columns. The DropDownWidth property must be set to its default value (-1) for this setting to work properly.
public bool AutoSizeDropDownToBestFit { get; set; }Gets or sets a value indicating whether the text is automatically cleared when it does not match any value in the DisplayMember column. When enabled, invalid text entries are automatically removed during validation.
[Browsable(true)]
public bool ClearTextOnValidation { get; set; }Gets the collection of columns displayed in the dropdown grid. Use this collection to define, configure, and manage the columns that appear in the dropdown interface.
public GridViewColumnCollection Columns { get; }Gets or sets the data source for the combo box. The data source provides the items that are displayed in the dropdown grid.
public object DataSource { get; set; }Gets or sets a value indicating whether double-clicking in the text edit area rotates through available items. When enabled, double-clicking cycles through the selectable values in the dropdown.
[Browsable(true)]
public bool DblClickRotate { get; set; }Gets the default size of the control when no explicit size is specified. The default size provides a reasonable starting point for the control's dimensions.
protected override Size DefaultSize { get; }Overrides:
Gets or sets the name of the data source member used to supply the display text for items in the combo box. This property determines which field from the data source is shown to the user.
[TypeConverter("System.Windows.Forms.Design.DataMemberFieldConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
public string DisplayMember { get; set; }Gets or sets the maximum size allowed for the dropdown portion of the combo box. This prevents the dropdown from becoming too large and overwhelming the interface.
public Size DropDownMaxSize { get; set; }Gets or sets the minimum size allowed for the dropdown portion of the combo box. This prevents the dropdown from becoming too small to be usable.
public Size DropDownMinSize { get; set; }Gets or sets the sizing mode for the dropdown portion of the control. The mode can be horizontal, vertical, or a combination that determines how the dropdown is resized.
[Browsable(true)]
public SizingMode DropDownSizingMode { get; set; }Gets or sets the dropdown style of the combo box, which determines the appearance and editing behavior. This controls whether the text portion is editable and how the dropdown is presented.
[Browsable(true)]
public RadDropDownStyle DropDownStyle { get; set; }Gets the RadGridView control hosted in the popup form that provides the multi-column interface. This grid displays the data and handles user selection within the dropdown.
public virtual RadGridView EditorControl { get; }Gets the hosted RadMultiColumnComboBoxElement that provides the core functionality of the combo box. This element contains all the logic for dropdown management, data binding, and user interaction.
[Browsable(false)]
public RadMultiColumnComboBoxElement MultiColumnComboBoxElement { get; }Gets the popup form that contains the multi-column grid interface. This form is displayed when the dropdown is opened and contains the RadGridView for data selection.
protected MultiColumnComboPopupForm MultiColumnPopupForm { get; }Gets or sets the placeholder text that is displayed when the Text property contains an empty string or is null. This provides a visual hint to users about the expected input or purpose of the control.
[Browsable(true)]
[Bindable(true)]
public string NullText { get; set; }Gets or sets a value indicating whether the control is in read-only mode. When read-only, users can view and select items but cannot edit the text portion.
[Browsable(true)]
public bool ReadOnly { get; set; }Gets or sets a value indicating whether the user can scroll through items using the mouse wheel when the popup is closed. This enables convenient item navigation without opening the dropdown.
public bool ScrollOnMouseWheel { get; set; }Gets or sets the index of the currently selected item in the combo box. A value of -1 indicates that no item is selected.
[Browsable(false)]
public int SelectedIndex { get; set; }Gets or sets the currently selected item in the combo box. This represents the entire data object corresponding to the selected row.
[Browsable(false)]
[Bindable(true)]
public object SelectedItem { get; set; }Gets or sets the value of the currently selected item as determined by the ValueMember property. This property provides the underlying value associated with the selected item.
[Browsable(false)]
[Bindable(true)]
public object SelectedValue { get; set; }Gets or sets a value indicating whether ToolTips are shown for the RadItem objects contained in the control. When enabled, tooltips are displayed for both the control and its dropdown grid items.
public override bool ShowItemToolTips { get; set; }Overrides:
Gets or sets the text displayed in the text box portion of the combo box. This text represents the current selection or user input and can be bound to data sources.
public override string Text { get; set; }Overrides:
Gets or sets the name of the data source member used to supply the value for items in the combo box. This property determines which field from the data source provides the actual value for each item.
[TypeConverter("System.Windows.Forms.Design.DataMemberFieldConverter, System.Design, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")]
public string ValueMember { get; set; }Methods
Automatically adjusts the width of all columns based on the content of visible rows. This method resizes columns to optimally display their content without horizontal scrolling.
public void BestFitColumns()Automatically adjusts the width of all columns with options for dropdown sizing and row analysis. This overload provides more control over the best-fit operation.
public void BestFitColumns(bool adjustComboBoxSize, bool bestFitAllRows)true to adjust the dropdown size according to the total width of all columns; otherwise, false.
bestFitAllRowsbooltrue to calculate optimal width by analyzing all rows including non-visible ones; false to analyze only visible rows.
Determines whether the control defines a theme for the specified element. This method prevents theme duplication by indicating which elements have control-defined themes.
public override bool ControlDefinesThemeForElement(RadElement element)The element to check for theme definition.
Returns:true if the control defines a theme for this element; false otherwise.
Overrides:
Creates the child element hierarchy for the combo box control. This method establishes the main combo box element and wires up all necessary event handlers.
protected override void CreateChildItems(RadElement parent)The parent element to which child elements will be added.
Overrides:
Creates and returns a new instance of the RadMultiColumnComboBoxElement that serves as the main element for this control. This method can be overridden to provide custom element implementations.
protected virtual RadMultiColumnComboBoxElement CreateMultiColumnComboBoxElement()A new RadMultiColumnComboBoxElement instance.
Releases the unmanaged resources used by the RadMultiColumnComboBox and optionally releases the managed resources.
protected override void Dispose(bool disposing)true to release both managed and unmanaged resources; false to release only unmanaged resources.
Overrides:
Completes the initialization of the combo box control that is used on a form or by another component. The initialization occurs at run time and finalizes the setup of the control.
public override void EndInit()Overrides:
Determines whether the specified key is an input key that should be processed by the control. This method handles special keys like Up and Down arrows for dropdown-style controls.
Raises the BindingContextChanged event and synchronizes the binding context with the editor control. This method ensures that data binding contexts are properly propagated to the dropdown grid.
Raises the CaseSensitiveChanged event. This method is called when the case sensitivity setting changes.
Raises the DataBindingComplete event when the underlying grid completes its data binding process. This method is called after the grid has been populated with data from the data source.
protected virtual void OnDataBindingComplete(GridViewBindingCompleteEventArgs e)A GridViewBindingCompleteEventArgs that contains information about the data binding operation.
Raises the DropDownClosed event. This method is called after the dropdown window has closed.
protected virtual void OnDropDownClosed(RadPopupClosedEventArgs e)A RadPopupClosedEventArgs that contains information about how the popup was closed.
Raises the DropDownClosing event. This method is called when the dropdown window is about to close and allows cancellation.
protected virtual void OnDropDownClosing(RadPopupClosingEventArgs e)A RadPopupClosingEventArgs that contains information about the closing operation and allows cancellation.
Raises the DropDownOpened event. This method is called after the dropdown window has opened.
Raises the DropDownOpening event. This method is called when the dropdown window is about to open and allows cancellation.
protected virtual void OnDropDownOpening(CancelEventArgs e)A CancelEventArgs that contains information about the opening operation and allows cancellation.
Raises the DropDownStyleChanged event. This method is called when the dropdown style changes.
Raises the ParentChanged event and closes the popup when the parent changes. This method ensures proper cleanup when the control is moved to a different parent.
Raises the ParentVisibleChanged event and closes the popup when the parent's visibility changes. This method handles popup closure when the parent container becomes invisible.
Raises the SelectedIndexChanged event. This method is called when the selected index changes.
Raises the SelectedValueChanged event. This method is called when the selected value changes.
Raises the SortedChanged event. This method is called when the sorting configuration changes.
Raises the VisibleChanged event and closes the popup if the control becomes invisible. This method ensures the popup is closed when the control is hidden.
Processes auto-size mode changes and adjusts the element's stretch behavior accordingly. When auto-sizing is enabled, the control stretches horizontally but not vertically.
protected override void ProcessAutoSizeChanged(bool value)true if auto-sizing is enabled; otherwise, false.
Overrides:
Processes command keys and handles special key combinations. This method intercepts Tab key presses to properly set the current row in the dropdown grid.
protected override bool ProcessCmdKey(ref Message msg, Keys keyData)A Message passed by reference that represents the window message to process.
keyDataKeysOne of the Keys values that represents the key to process.
Returns:true if the character was processed by the control; otherwise, false.
Overrides:
Resets theme value overrides for the BackColor property and reapplies the default theme. This method clears custom background color overrides and restores theme-based coloring.
protected override void ResetBackColorThemeOverrides()Overrides:
Resets theme value overrides for the ForeColor property and reapplies the default theme. This method clears custom foreground color overrides and restores theme-based coloring.
protected override void ResetForeColorThemeOverrides()Overrides:
Sets theme value overrides for the BackColor property across all visual states. This method ensures consistent background color theming for the combo box and its text element.
protected override void SetBackColorThemeOverrides()Overrides:
Sets the binding context of the editor control to match the combo box's binding context. This ensures consistent data binding behavior between the control and its dropdown grid.
protected virtual void SetEditorControlBindingContext()Sets theme value overrides for the ForeColor property across all visual states. This method ensures consistent foreground color theming for the combo box element.
protected override void SetForeColorThemeOverrides()Overrides:
Unwires the data binding event handler from the editor control if it is available. This is called during cleanup to ensure proper event handler removal.
protected virtual void UnwireEditorControlDataBindingEvent()Unwires all event handlers that were previously attached to the combo box element. This method is called during disposal to prevent memory leaks.
protected virtual void UnwireEvents()Wires the data binding event handler for the editor control if it is available. This enables handling of data binding completion events from the underlying grid.
protected virtual void WireEditorControlDataBindingEvent()Wires all necessary event handlers between the combo box element and the control. This includes handlers for text changes, selection changes, popup events, and keyboard input.
protected virtual void WireEvents()Events
Occurs when the CaseSensitive property value changes. This event is raised when the case sensitivity property value changes.
[Browsable(true)]
public event EventHandler CaseSensitiveChangedOccurs when the data binding process for the underlying grid control finishes. This event is useful for performing actions after the grid has been populated with data.
public event GridViewBindingCompleteEventHandler DataBindingCompleteOccurs after the dropdown window has closed and is no longer visible. This event provides information about how and why the dropdown was closed.
[Browsable(true)]
public event RadPopupClosedEventHandler DropDownClosedOccurs when the dropdown window is about to close. This event can be used to cancel the closing operation or perform cleanup actions.
[Browsable(true)]
public event RadPopupClosingEventHandler DropDownClosingOccurs after the dropdown window has opened and is visible to the user. This event is useful for performing actions once the dropdown interface is available.
[Browsable(true)]
public event EventHandler DropDownOpenedOccurs when the dropdown window is about to open. This event can be used to cancel the opening operation or prepare the dropdown content.
[Browsable(true)]
public event RadPopupOpeningEventHandler DropDownOpeningOccurs when the DropDownStyle property value changes. This event is raised when the dropdown style is modified.
[Browsable(true)]
public event EventHandler DropDownStyleChangedOccurs when the ReadOnly property value changes. This event is raised when the read-only state of the control is modified.
public event EventHandler ReadOnlyChangedOccurs when the SelectedIndex property value changes. This event is raised whenever a different item is selected in the combo box.
[Browsable(true)]
public event EventHandler SelectedIndexChangedOccurs when the SelectedValue property value changes. This event is raised whenever the value of the selected item changes.
[Browsable(true)]
public event EventHandler SelectedValueChangedOccurs when the sorting configuration of the dropdown grid changes. This event is raised when columns are sorted or unsorted.
[Browsable(true)]
public event EventHandler SortedChanged