Class RadMultiColumnComboBox

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.

Inheritance
System.Object
RadControl
RadEditorControl
RadMultiColumnComboBox
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.GridView.dll

Syntax

[TelerikToolboxCategory("Data Controls")]
public class RadMultiColumnComboBox : RadEditorControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider

Constructors

RadMultiColumnComboBox()

Initializes a new instance of the RadMultiColumnComboBox class with default settings. Sets up basic control properties including auto-sizing, tab behavior, and selection capabilities.

Declaration
public RadMultiColumnComboBox()

Properties

AutoCompleteMode

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.

Declaration
public AutoCompleteMode AutoCompleteMode { get; set; }
Property Value
System.Windows.Forms.AutoCompleteMode

AutoFilter

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.

Declaration
[RadDefaultValue("AutoFilter", typeof(RadMultiColumnComboBoxElement))]
[RadDescription("AutoFilter", typeof(RadMultiColumnComboBoxElement))]
public bool AutoFilter { get; set; }
Property Value
System.Boolean

AutoFilterDelay

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.

Declaration
public int AutoFilterDelay { get; set; }
Property Value
System.Int32

AutoSize

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.

Declaration
public override bool AutoSize { get; set; }
Property Value
System.Boolean

Overrides

AutoSizeDropDownColumnMode

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.

Declaration
public virtual BestFitColumnMode AutoSizeDropDownColumnMode { get; set; }
Property Value
BestFitColumnMode

AutoSizeDropDownHeight

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.

Declaration
public bool AutoSizeDropDownHeight { get; set; }
Property Value
System.Boolean

AutoSizeDropDownToBestFit

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.

Declaration
public bool AutoSizeDropDownToBestFit { get; set; }
Property Value
System.Boolean

ClearTextOnValidation

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.

Declaration
public bool ClearTextOnValidation { get; set; }
Property Value
System.Boolean

Columns

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.

Declaration
public GridViewColumnCollection Columns { get; }
Property Value
GridViewColumnCollection

DataSource

Gets or sets the data source for the combo box. The data source provides the items that are displayed in the dropdown grid.

Declaration
[RadDefaultValue("DataSource", typeof(RadMultiColumnComboBoxElement))]
[RadDescription("DataSource", typeof(RadMultiColumnComboBoxElement))]
public object DataSource { get; set; }
Property Value
System.Object

DblClickRotate

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.

Declaration
[RadDefaultValue("DblClickRotate", typeof(RadMultiColumnComboBoxElement))]
public bool DblClickRotate { get; set; }
Property Value
System.Boolean

DefaultSize

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.

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

DisplayMember

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.

Declaration
[RadDefaultValue("DisplayMember", typeof(RadMultiColumnComboBoxElement))]
[RadDescription("DisplayMember", typeof(RadMultiColumnComboBoxElement))]
public string DisplayMember { get; set; }
Property Value
System.String

DropDownMaxSize

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.

Declaration
public Size DropDownMaxSize { get; set; }
Property Value
System.Drawing.Size

DropDownMinSize

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.

Declaration
public Size DropDownMinSize { get; set; }
Property Value
System.Drawing.Size

DropDownSizingMode

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.

Declaration
[RadDefaultValue("DropDownSizingMode", typeof(RadMultiColumnComboBoxElement))]
public SizingMode DropDownSizingMode { get; set; }
Property Value
SizingMode

DropDownStyle

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.

Declaration
[RadPropertyDefaultValue("DropDownStyle", typeof(RadMultiColumnComboBoxElement))]
public RadDropDownStyle DropDownStyle { get; set; }
Property Value
RadDropDownStyle

EditorControl

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.

Declaration
public virtual RadGridView EditorControl { get; }
Property Value
RadGridView

MultiColumnComboBoxElement

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.

Declaration
public RadMultiColumnComboBoxElement MultiColumnComboBoxElement { get; }
Property Value
RadMultiColumnComboBoxElement

MultiColumnPopupForm

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.

Declaration
protected MultiColumnComboPopupForm MultiColumnPopupForm { get; }
Property Value
MultiColumnComboPopupForm

NullText

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.

Declaration
[RadDefaultValue("NullText", typeof(RadMultiColumnComboBoxElement))]
public string NullText { get; set; }
Property Value
System.String

ReadOnly

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.

Declaration
public bool ReadOnly { get; set; }
Property Value
System.Boolean

ScrollOnMouseWheel

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.

Declaration
public bool ScrollOnMouseWheel { get; set; }
Property Value
System.Boolean

SelectedIndex

Gets or sets the index of the currently selected item in the combo box. A value of -1 indicates that no item is selected.

Declaration
[RadDescription("SelectedIndex", typeof(BaseComboBoxElement))]
public int SelectedIndex { get; set; }
Property Value
System.Int32

SelectedItem

Gets or sets the currently selected item in the combo box. This represents the entire data object corresponding to the selected row.

Declaration
[RadDescription("SelectedItem", typeof(BaseComboBoxElement))]
public object SelectedItem { get; set; }
Property Value
System.Object

SelectedValue

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.

Declaration
[RadDescription("SelectedValue", typeof(BaseComboBoxElement))]
public object SelectedValue { get; set; }
Property Value
System.Object

ShowItemToolTips

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.

Declaration
public override bool ShowItemToolTips { get; set; }
Property Value
System.Boolean

Overrides

Text

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.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

ValueMember

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.

Declaration
[RadDescription("ValueMember", typeof(RadMultiColumnComboBoxElement))]
[RadDefaultValue("ValueMember", typeof(RadMultiColumnComboBoxElement))]
public string ValueMember { get; set; }
Property Value
System.String

Methods

BestFitColumns()

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.

Declaration
public void BestFitColumns()

BestFitColumns(Boolean, Boolean)

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.

Declaration
public void BestFitColumns(bool adjustComboBoxSize, bool bestFitAllRows)
Parameters
System.Boolean adjustComboBoxSize

true to adjust the dropdown size according to the total width of all columns; otherwise, false.
System.Boolean bestFitAllRows

true to calculate optimal width by analyzing all rows including non-visible ones; false to analyze only visible rows.

ControlDefinesThemeForElement(RadElement)

Determines whether the control defines a theme for the specified element. This method prevents theme duplication by indicating which elements have control-defined themes.

Declaration
public override bool ControlDefinesThemeForElement(RadElement element)
Parameters
RadElement element

The element to check for theme definition.
Returns
System.Boolean

true if the control defines a theme for this element; false otherwise.
Overrides

CreateChildItems(RadElement)

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.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent element to which child elements will be added.
Overrides

CreateMultiColumnComboBoxElement()

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.

Declaration
protected virtual RadMultiColumnComboBoxElement CreateMultiColumnComboBoxElement()
Returns
RadMultiColumnComboBoxElement

A new RadMultiColumnComboBoxElement instance.

Dispose(Boolean)

Releases the unmanaged resources used by the RadMultiColumnComboBox and optionally releases the managed resources.

Declaration
protected override void Dispose(bool disposing)
Parameters
System.Boolean disposing

true to release both managed and unmanaged resources; false to release only unmanaged resources.
Overrides

EndInit()

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.

Declaration
public override void EndInit()
Overrides

IsInputKey(Keys)

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.

Declaration
protected override bool IsInputKey(Keys keyData)
Parameters
System.Windows.Forms.Keys keyData

One of the System.Windows.Forms.Keys values to evaluate.
Returns
System.Boolean

true if the specified key is an input key; otherwise, false.
Overrides

OnBindingContextChanged(EventArgs)

Raises the System.Windows.Forms.Control.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.

Declaration
protected override void OnBindingContextChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnCaseSensitiveChanged(EventArgs)

Raises the CaseSensitiveChanged event. This method is called when the case sensitivity setting changes.

Declaration
protected virtual void OnCaseSensitiveChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnDataBindingComplete(GridViewBindingCompleteEventArgs)

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.

Declaration
protected virtual void OnDataBindingComplete(GridViewBindingCompleteEventArgs e)
Parameters
GridViewBindingCompleteEventArgs e

A GridViewBindingCompleteEventArgs that contains information about the data binding operation.

OnDropDownClosed(RadPopupClosedEventArgs)

Raises the DropDownClosed event. This method is called after the dropdown window has closed.

Declaration
protected virtual void OnDropDownClosed(RadPopupClosedEventArgs e)
Parameters
RadPopupClosedEventArgs e

A RadPopupClosedEventArgs that contains information about how the popup was closed.

OnDropDownClosing(RadPopupClosingEventArgs)

Raises the DropDownClosing event. This method is called when the dropdown window is about to close and allows cancellation.

Declaration
protected virtual void OnDropDownClosing(RadPopupClosingEventArgs e)
Parameters
RadPopupClosingEventArgs e

A RadPopupClosingEventArgs that contains information about the closing operation and allows cancellation.

OnDropDownOpened(EventArgs)

Raises the DropDownOpened event. This method is called after the dropdown window has opened.

Declaration
protected virtual void OnDropDownOpened(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnDropDownOpening(CancelEventArgs)

Raises the DropDownOpening event. This method is called when the dropdown window is about to open and allows cancellation.

Declaration
protected virtual void OnDropDownOpening(CancelEventArgs e)
Parameters
System.ComponentModel.CancelEventArgs e

A System.ComponentModel.CancelEventArgs that contains information about the opening operation and allows cancellation.

OnDropDownStyleChanged(EventArgs)

Raises the DropDownStyleChanged event. This method is called when the dropdown style changes.

Declaration
protected virtual void OnDropDownStyleChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnEnter(EventArgs)

Raises the System.Windows.Forms.Control.Enter event and transfers focus to the text box element. This method ensures proper focus handling when the control receives focus.

Declaration
protected override void OnEnter(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnGotFocus(EventArgs)

Raises the System.Windows.Forms.Control.GotFocus event and selects all text in the text box. This method provides convenient text selection when the control gains focus.

Declaration
protected override void OnGotFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnLeave(EventArgs)

Raises the System.Windows.Forms.Control.Leave event and closes the popup if it is open. This method handles cleanup when the control loses focus.

Declaration
protected override void OnLeave(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnLostFocus(EventArgs)

Raises the System.Windows.Forms.Control.LostFocus event and handles selection state when focus is lost. This method processes the current selection and clears text selection if appropriate.

Declaration
protected override void OnLostFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnParentChanged(EventArgs)

Raises the System.Windows.Forms.Control.ParentChanged event and closes the popup when the parent changes. This method ensures proper cleanup when the control is moved to a different parent.

Declaration
protected override void OnParentChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

OnParentVisibleChanged(EventArgs)

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.

Declaration
protected override void OnParentVisibleChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnSelectedIndexChanged(EventArgs)

Raises the SelectedIndexChanged event. This method is called when the selected index changes.

Declaration
protected virtual void OnSelectedIndexChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnSelectedValueChanged(EventArgs)

Raises the SelectedValueChanged event. This method is called when the selected value changes.

Declaration
protected virtual void OnSelectedValueChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnSortedChanged(EventArgs)

Raises the SortedChanged event. This method is called when the sorting configuration changes.

Declaration
protected virtual void OnSortedChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.

OnVisibleChanged(EventArgs)

Raises the System.Windows.Forms.Control.VisibleChanged event and closes the popup if the control becomes invisible. This method ensures the popup is closed when the control is hidden.

Declaration
protected override void OnVisibleChanged(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs that contains the event data.
Overrides

ProcessAutoSizeChanged(Boolean)

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.

Declaration
protected override void ProcessAutoSizeChanged(bool value)
Parameters
System.Boolean value

true if auto-sizing is enabled; otherwise, false.
Overrides

ProcessCmdKey(ref Message, Keys)

Processes command keys and handles special key combinations. This method intercepts Tab key presses to properly set the current row in the dropdown grid.

Declaration
protected override bool ProcessCmdKey(ref Message msg, Keys keyData)
Parameters
System.Windows.Forms.Message msg

A System.Windows.Forms.Message passed by reference that represents the window message to process.
System.Windows.Forms.Keys keyData

One of the System.Windows.Forms.Keys values that represents the key to process.
Returns
System.Boolean

true if the character was processed by the control; otherwise, false.

ResetBackColorThemeOverrides()

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.

Declaration
protected override void ResetBackColorThemeOverrides()
Overrides

ResetForeColorThemeOverrides()

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.

Declaration
protected override void ResetForeColorThemeOverrides()
Overrides

SetBackColorThemeOverrides()

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.

Declaration
protected override void SetBackColorThemeOverrides()
Overrides

SetEditorControlBindingContext()

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.

Declaration
protected virtual void SetEditorControlBindingContext()

SetForeColorThemeOverrides()

Sets theme value overrides for the ForeColor property across all visual states. This method ensures consistent foreground color theming for the combo box element.

Declaration
protected override void SetForeColorThemeOverrides()
Overrides

UnwireEditorControlDataBindingEvent()

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.

Declaration
protected virtual void UnwireEditorControlDataBindingEvent()

UnwireEvents()

Unwires all event handlers that were previously attached to the combo box element. This method is called during disposal to prevent memory leaks.

Declaration
protected virtual void UnwireEvents()

WireEditorControlDataBindingEvent()

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.

Declaration
protected virtual void WireEditorControlDataBindingEvent()

WireEvents()

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.

Declaration
protected virtual void WireEvents()

Events

CaseSensitiveChanged

Occurs when the CaseSensitive property value changes. This event is raised when the case sensitivity property value changes.

Declaration
public event EventHandler CaseSensitiveChanged
Event Type
System.EventHandler

DataBindingComplete

Occurs 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.

Declaration
public event GridViewBindingCompleteEventHandler DataBindingComplete
Event Type
GridViewBindingCompleteEventHandler

DropDownClosed

Occurs after the dropdown window has closed and is no longer visible. This event provides information about how and why the dropdown was closed.

Declaration
public event RadPopupClosedEventHandler DropDownClosed
Event Type
RadPopupClosedEventHandler

DropDownClosing

Occurs when the dropdown window is about to close. This event can be used to cancel the closing operation or perform cleanup actions.

Declaration
public event RadPopupClosingEventHandler DropDownClosing
Event Type
RadPopupClosingEventHandler

DropDownOpened

Occurs 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.

Declaration
public event EventHandler DropDownOpened
Event Type
System.EventHandler

DropDownOpening

Occurs when the dropdown window is about to open. This event can be used to cancel the opening operation or prepare the dropdown content.

Declaration
public event RadPopupOpeningEventHandler DropDownOpening
Event Type
RadPopupOpeningEventHandler

DropDownStyleChanged

Occurs when the DropDownStyle property value changes. This event is raised when the dropdown style is modified.

Declaration
public event EventHandler DropDownStyleChanged
Event Type
System.EventHandler

ReadOnlyChanged

Occurs when the ReadOnly property value changes. This event is raised when the read-only state of the control is modified.

Declaration
public event EventHandler ReadOnlyChanged
Event Type
System.EventHandler

SelectedIndexChanged

Occurs when the SelectedIndex property value changes. This event is raised whenever a different item is selected in the combo box.

Declaration
public event EventHandler SelectedIndexChanged
Event Type
System.EventHandler

SelectedValueChanged

Occurs when the SelectedValue property value changes. This event is raised whenever the value of the selected item changes.

Declaration
public event EventHandler SelectedValueChanged
Event Type
System.EventHandler

SortedChanged

Occurs when the sorting configuration of the dropdown grid changes. This event is raised when columns are sorted or unsorted.

Declaration
public event EventHandler SortedChanged
Event Type
System.EventHandler

Extension Methods