BinaryTextComboBox

Initialises a new text combo box in DropDown style, with auto-completion on.

The control registers itself as an application message filter, so it can close its suggestion list when the user clicks elsewhere; disposing the control removes the filter. DrawTheControlBasedOnWindowsOS starts true, so the flat look is used while Windows visual styles are on.

Gets or sets how strongly the pane colour shows when the filter and grouping pane's colour is blended with the window colour.

Used only while EnableAlphaBlendingForFilterAndGroupingPanelBackColor is true.

Gets or sets whether the multi-column drop-down animates as it closes after the user picks a row.

The animation is chosen by MultiColumnDroplistWindowAnimationStyle, which must not be MultiColumnDroplistWindowAnimationStyle.None, and paced by AnimationInterval.

productPicker.AnimateDropDownWindow = true;
productPicker.MultiColumnDroplistWindowAnimationStyle = MultiColumnDroplistWindowAnimationStyle.Vanish;
productPicker.AnimationInterval = 20;   // about a fifth of a second in all

Gets or sets the pause between the steps of the multi-column drop-down's closing animation.

The vanish animation takes nine steps; the resize animation about one step for every 11 pixels of the window's height. The user waits for the whole animation, so keep the pause short.

Gets or sets whether the text the user types is completed from the first item that starts with it.

Works in DropDown style. After each key the control finds the first item whose text starts with what has been typed – matching case as AutoCompleteIsCaseSensitive says – fills in the rest, selected so the next key replaces it, and, when ValueMember is set, sets SelectedValue to that item's value. The AutoCompleting event comes first and can skip it.

This completion runs while AutoCompleteMode is None; choose another mode to use the framework's completion instead. Turning this property off turns both off, and turning it back on restores the mode that was set.

In multi-column mode, AutoCompleteStyleForMultiColumnModeIsMultiColumn shows the matching rows in a suggestion list as the user types.

Gets or sets which item the control's auto-completion uses when several start with the typed text: the first, or the last.

The NotInList check searches the list the same way. Not shown in the Properties window.

Gets or sets whether the control's auto-completion, and its check for text that is not in the list, tell upper and lower case apart.

Set it to false so that typing "lee" completes to "Leeds". It applies to the completion done by AutoComplete and to the matching behind NotInList; the framework's own AutoCompleteMode completion ignores case anyway. Not shown in the Properties window.

Gets or sets the framework's auto-completion mode, used in place of the control's own completion.

When the control already has a data source, items or data bindings, setting a mode also sets ComboBox.AutoCompleteSource to ListItems, so the suggestions come from the list. Turning AutoComplete off sets the mode to None, and turning it back on restores the mode set here.

Gets or sets whether, in multi-column mode, the user's typing opens a multi-column suggestion list under the control in place of the ordinary text completion.

Applies while AutoComplete and DropStyleIsMultiColumn are both true. The list is meant to hold the rows whose DisplayMember value starts with the text typed so far; the user picks one by clicking it. Escape, clearing the text, or leaving the control closes it.

Its columns, size and behaviour are set by IsCustomisationOfColumnDisplayEnabledInMultiColumnAutoSuggestMode, SizeForMultiColumnAutoCompleteSuggestionDropDownWindow, SizesForMultiColumnAutoCompleteSuggestionDropDownWindowColumns, ShouldAllowUserInputWhileProcessingMultiColumnAutoCompleDropDownView and IsAutoCompleteModeAppendSuggestInMultiColumnMode.

Gets or sets how the built-in filter of the multi-column drop-down matches a column that holds numbers, dates or other values that are not text.

The user types into the filter pane that ShowFilterOptionsInMultiColumnMode shows. Text columns are matched on what their values start with.

Gets or sets how the built-in filter matches a column that holds text. The setting is stored but not used.

The built-in filter always keeps the text rows whose value starts with what the user typed, whatever this is set to. Columns that do not hold text follow BuiltinFilterOnNonStringTypeColumnFilterMode.

Gets or sets the text shown in the control's text area while the multi-column drop-down is being built.

The text the user had is put back once the window is open. A large data source can take a moment to list; the message tells the user something is happening. The control does not report this text through NotInList.

Gets or sets the file the multi-column drop-down's "Export data to CSV" command writes to.

The user is not asked where to save, so choose the path in advance – a folder the user can write to, such as their documents folder. An existing file is overwritten. An empty value removes the command from the drop-down's shortcut menu.

The export holds the rows the list shows at the time, filtered as they are, with a first line of column names, in the order the columns are shown. Values are separated by commas and are not quoted, so a value that itself contains a comma will split across columns.

string documents = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
customerPicker.CSVFileSaveAs = Path.Combine(documents, "Customers.csv");

Gets or sets how the values in each column of the multi-column drop-down are formatted – dates, currency, decimals or thousands separators.

Each ColumnDataTypeFormatInfoContainer says what kind of value its column holds and gives the format to use: a .NET date format such as "dd MMM yyyy" for dates, or the number of decimal places, such as "2", for decimals and currency. A value that does not parse as that kind is shown as it stands.

Give an entry for every column shown; a column without one is shown empty. When the data source is a list of objects or a DataSet, which the control copies into a table of its own, and IsFilterSearchResultBasedOnColumnDataType is on (the default), give an entry for every property or column of the source: the entries then also set the type each column is filtered as. Set the list before DataSource.

invoicePicker.ColumnDataTypeFormatInfoContainers = new List<ColumnDataTypeFormatInfoContainer>
{
    new ColumnDataTypeFormatInfoContainer { ColumnDataTypeFormat = ColumnDataTypeFormat.Text },
    new ColumnDataTypeFormatInfoContainer
    {
        ColumnDataTypeFormat = ColumnDataTypeFormat.DateAndTimeOrDateOnly,
        CustomFormatForTheColumnDataType = "dd MMM yyyy"
    },
    new ColumnDataTypeFormatInfoContainer
    {
        ColumnDataTypeFormat = ColumnDataTypeFormat.CurrencyFormattedForSpecifiedNumberofDecimalPlaces,
        CustomFormatForTheColumnDataType = "2"
    },
};
invoicePicker.DataSource = invoices;   // InvoiceNo, IssuedOn, Amount

Gets or sets the width of each column of the multi-column drop-down, in place of the widths it works out from the content.

The widths are scaled to the display. Columns beyond the end of the array keep their measured width; a width beyond the last column adds an empty column, so give no more widths than there are columns. When MultiColumnDropDownSize is empty the window sizes itself to these widths.

The user can still drag the column edges unless EnableUserColumnResizing is off.

accountPicker.ColumnsToDisplay = new[] { "AccountNo", "Name", "City", "Balance" };
accountPicker.ColumnWidths = new[] { 80, 200, 110, 90 };

Gets or sets which columns of the data source the multi-column drop-down shows, and in what order.

An empty array, or one whose first name is blank, means null. Every name must be a column of the source; a name that is not leaves the drop-down empty.

The headings are the column names unless HeadersToDisplay gives one per column; set this property first, since HeadersToDisplay is checked against it. DisplayMember and ValueMember need not be among the columns shown.

employeePicker.DropStyleIsMultiColumn = true;
employeePicker.DataSource = employees;          // EmployeeId, Surname, Forename, Department, Extension
employeePicker.DisplayMember = "Surname";
employeePicker.ValueMember = "EmployeeId";
employeePicker.ColumnsToDisplay = new[] { "Surname", "Forename", "Department", "Extension" };
employeePicker.HeadersToDisplay = new[] { "Surname", "First name", "Department", "Ext." };

Gets or sets whether the user is prevented from typing in the control's text area, while still being able to select and copy its text.

Applies to DropDown style, which has a text area. Typing, Delete and Backspace are ignored, and the control's shortcut menu is replaced by one with a single Copy command. The user can still pick another item from the list; to stop that too, set BinaryComboBox.IsInExtendedReadOnlyMode.

Turning it off removes the shortcut menu, including one you had assigned to Control.ContextMenu yourself.

Gets or sets the column the multi-column drop-down searches when the user types a letter or digit in it, jumping to the next row whose value in that column starts with that character.

Pressing the same key again moves on to the next matching row, and after the last one starts from the first again.

The name is looked up among the data source's columns when ColumnsToDisplay is not set; when it is set, or the name is not found, the first column shown is searched.

Gets or sets a comparison of your own for sorting the rows of the multi-column drop-down.

The built-in comparison orders values that read as numbers by their value and everything else as text, ignoring case. A comparer of your own is handed the list's rows: read the cell text from SubItems and keep track of the sort direction yourself.

The value in force when the user clicks a heading is the one used, so it is usually set in a CustomSorting handler. Not shown in the Properties window.

Gets or sets a fixed screen position for the top-left corner of the multi-column drop-down.

A position set here is used as it is: the window is not moved to fit on the screen, and DropDownWindowDisplayOrientation is not applied. Convert from the form's coordinates with Control.PointToScreen.

// Open the drop-down over the details panel rather than under the combo box.
productPicker.CustomDropDownWindowLocationPoint = detailsPanel.PointToScreen(Point.Empty);

Gets or sets the accent colour the control blends to fill its drop-down button and the highlighted item; the multi-column drop-down takes its accents from it too.

Besides what BinaryComboBox.CustomPaintingColor describes, the colour is the start of the gradient behind the multi-column drop-down's column headings, and the default colour of its filter and grouping pane. While MultiColumnDropDownWindowConfiguration.HeaderControlRenderingStartColor is empty it is set to this colour, so the header and footer match.

Gets or sets the table of a DataSet data source that the multi-column drop-down lists.

Used in multi-column mode when DataSource is a DataSet. Setting it while such a data source is bound loads the named table.

supplierPicker.DropStyleIsMultiColumn = true;
supplierPicker.DataMember = "Suppliers";
supplierPicker.DataSource = purchasingDataSet;     // has Suppliers, Products, Orders tables
supplierPicker.DisplayMember = "CompanyName";
supplierPicker.ValueMember = "SupplierId";

Gets or sets the data the control lists: a DataTable, DataView, DataSet, a BindingSource, or any list of objects.

In single-column mode this is the standard DataSource.

In multi-column mode the drop-down lists a table: a DataTable is used as it is; a DataView is copied, in its sort order and with its filter applied; a DataSet supplies the table named by DataMember, or its first table; and a list of objects is copied into a table with a column for each public property. The copy is refreshed when the source reports that its list has changed.

Set ColumnDataTypeFormatInfoContainers, DataSourceViewCustomSortingExpression and KeepBindingContextInSyncWithParent before the data source, since they act as it is bound.

Gets or sets a sort expression that orders the rows of the multi-column drop-down, such as "City ASC, Name ASC".

The rows are put in this order when the control copies them from a list of objects or from a DataSet table, so set it before DataSource. Filtered results are ordered by it too, and while it is set the list does not sort itself by a column on opening.

A DataTable bound directly is shown in its own row order; to order one, bind a DataView of it with its DataView.Sort set instead.

Gets or sets the column the built-in filter of the multi-column drop-down starts on.

It selects the starting entry of the pane's "Filter on this column" list; the user can choose another. A position outside the list of columns is ignored.

Gets or sets the column or property of the data source whose value the control shows as the item's text.

In multi-column mode at run time a path such as "Customers.Name" is cut to the column name, "Name". It is also the column the control's auto-completion matches against. Setting it does not raise ComboBox.SelectedIndexChanged.

Gets or sets whether the control is drawn with its own flat look – the border, button and colours of BinaryComboBox – rather than as a standard Windows combo box.

While DrawTheControlBasedOnWindowsOS is true (the default) the value follows the visual styles and a value assigned here is ignored; set that property to false first. Turning the flat look off re-creates the control's window.

Gets or sets whether the control decides for itself between its flat look and the standard Windows look, by whether Windows visual styles are on.

With it on, DisplayStyleIsFlat follows the visual styles – flat while they are on, as they are on current versions of Windows – and a value assigned to it is ignored. To choose the look yourself, set this property to false first, then set DisplayStyleIsFlat.

Changing this property does not change the look by itself.

// Always the standard Windows combo box look.
regionPicker.DrawTheControlBasedOnWindowsOS = false;
regionPicker.DisplayStyleIsFlat = false;

Gets or sets the background colour of the drop-down list, in both single-column and multi-column mode.

Setting it also sets MultiColumnDropListBackColor; setting that afterwards changes only the multi-column list.

Gets or sets which way the multi-column drop-down extends from the control: to the right of its left edge, or to the left of its right edge.

DropDownWindowDisplayOrientation.Left lines the window's right edge up with the control's and lets it grow leftwards – useful for a combo box near the right of a form, whose drop-down is wider than it is. DropDownWindowDisplayOrientation.Right and DropDownWindowDisplayOrientation.Default line the left edges up and grow rightwards.

Gets or sets whether the drop-down button opens a multi-column window listing every column of the data source, instead of the ordinary single-column list.

Bind DataSource – a DataTable, DataView, DataSet with DataMember, or a list of objects – and set DisplayMember to the column whose value the text area shows, and ValueMember to the column SelectedValue returns.

When the user picks a row, the control sets SelectedValue, SelectedIndexFromDropList and the text, and raises ComboBox.SelectedIndexChanged if the row is a different one. Read SelectedIndexFromDropList rather than ComboBox.SelectedIndex for the row's position in the data source.

The window lists the columns in ColumnsToDisplay, or all of them; see MultiColumnDropDownSize for its size and placement and the MultiColumnDropList properties for its look. Set MultiColumnDropDownSize only after turning this on.

productPicker.DropStyleIsMultiColumn = true;
productPicker.DataSource = productsTable;          // Sku, Description, UnitPrice, InStock
productPicker.DisplayMember = "Description";
productPicker.ValueMember = "Sku";
productPicker.ColumnsToDisplay = new[] { "Sku", "Description", "UnitPrice" };

Gets or sets whether the drop-down is open; setting it to true opens the multi-column drop-down, or the ordinary list.

Reading the property returns what was last assigned to it, not whether a list is open now: the user opening or closing the list does not change it. Assigning false does not close an open list; to close the multi-column drop-down from code call CloseMultiColumnDropDownListWindow.

Gets or sets whether the filter and grouping pane's colour is blended with the window colour into a paler tint.

The amount is AlphaBlendingfactorForFilterAndGroupingPanelBackColor. With it off, FilterAndGroupingPanelBackColor is used as it is, and an empty colour leaves the pane in its default colour.

Gets or sets whether the user can sort the multi-column drop-down by clicking a column heading.

A first click sorts ascending and the next descending, and the heading shows an arrow in MultiColumnViewSortingGlyphColor. With sorting on, the list also sorts itself when it opens; see MultiColumnModeSourceDataSortedColumnIndex.

With it off the headings cannot be clicked.

Gets or sets whether the multi-column drop-down is framed by a header band and a footer band, set up in MultiColumnDropDownWindowConfigurationData.

The header carries MultiColumnDropDownWindowConfiguration.HeaderText and an icon or bitmap, the footer MultiColumnDropDownWindowConfiguration.FooterText, both on a gradient from MultiColumnDropDownWindowConfiguration.HeaderControlRenderingStartColor to MultiColumnDropDownWindowConfiguration.HeaderControlRenderingEndColor, inside a frame BinaryComboBox.MultiColumnDropDownWindowBorderThickness wide.

The column headings take the same gradient; without the header and footer they run from CustomPaintingColor to the window colour.

var window = supplierPicker.MultiColumnDropDownWindowConfigurationData;
window.HeaderText = "Approved suppliers";
window.FooterText = "Double-click a supplier to choose it";
window.HeaderImageType = HeaderImageStyle.None;
window.HeaderControlRenderingStartColor = Color.SteelBlue;
window.HeaderAndFooterTextForeColor = Color.White;
supplierPicker.EnableDrawingHeaderFooterWhenInMultiColumnMode = true;

Gets or sets whether the user can drag the edges of the multi-column drop-down's column headings to resize the columns.

Gets or sets whether the control checks the text the user types against its list, raising NotInList when it matches no item.

The check runs when the user leaves the control, and also as they type if RaiseNotInListWhenTyping is on. The control raises the event but does not change or reject the text; the handler does that.

Gets or sets the background colour of the multi-column drop-down's filter and grouping pane.

While EnableAlphaBlendingForFilterAndGroupingPanelBackColor is on (the default) the colour is blended with the window colour by AlphaBlendingfactorForFilterAndGroupingPanelBackColor, giving a pale tint; with it off the colour is used as it is.

Gets or sets whether filtering is switched on in the multi-column drop-down's options pane when the drop-down opens.

The pane exists only while ShowFilterOptionsInMultiColumnMode is true. Turning filtering on does not filter anything until the user types a filter; the column it applies to starts as DesiredFilterColumn.

Gets or sets whether the multi-column drop-down opens with its rows grouped under headings, one for each different value in a column.

The rows are grouped by the column at GroupMultiColumnDisplayModeDataBasedOnThisColumn, by the exact text each row shows in it. The group headings are ordered by MultiColumnDefaultGroupedModeGroupSortingOrder.

The user can turn grouping on and off from the drop-down's shortcut menu, and, with ShowFilterOptionsInMultiColumnMode on, choose the column in the options pane.

// Customers grouped by city.
accountPicker.ColumnsToDisplay = new[] { "City", "Name", "AccountNo" };
accountPicker.GroupMultiColumnDisplayModeDataBasedOnThisColumn = 0;
accountPicker.GroupItemsWhenInMultiColumnDisplayMode = true;
accountPicker.MultiColumnDefaultGroupedModeGroupSortingOrder = SortOrder.Ascending;

Gets or sets the column the multi-column drop-down groups its rows by.

Used when the list opens grouped; see GroupItemsWhenInMultiColumnDisplayMode.

Gets or sets the heading text of each column of the multi-column drop-down, in place of the column names.

An empty array, or one whose first heading is blank, means null.

In multi-column mode the number of headings is checked: it must equal the number of names in ColumnsToDisplay, or, without those, the number of columns in the data source. Otherwise an IndexOutOfRangeException is thrown – so set ColumnsToDisplay first.

Gets or sets whether the multi-column suggestion list also fills in the rest of the first matching item's text, the way SuggestAppend does.

The filled-in part is selected, so the next key replaces it. Applies only with AutoCompleteStyleForMultiColumnModeIsMultiColumn on.

Gets or sets whether the multi-column suggestion list shows only the columns in ColumnsToDisplay, rather than every column of the data source.

The columns are headed by HeadersToDisplay when it has one heading for each of them, and otherwise by their names. Without ColumnsToDisplay every column is shown.

Gets or sets whether the formats in ColumnDataTypeFormatInfoContainers also set the type each column is filtered as, so the built-in filter compares numbers and dates by value.

Applies when the control copies the data source into a table of its own – a list of objects or a DataSet – and ColumnDataTypeFormatInfoContainers is set. A column formatted as a decimal becomes a decimal column, currency and thousands-separated whole numbers become floating-point columns, and dates become date columns; the built-in filter then matches them as BuiltinFilterOnNonStringTypeColumnFilterMode says, rather than as text.

With it off, each column keeps the type of its property.

Gets or sets whether the data source is already in the order the multi-column drop-down should show, so the list does not sort it again.

With it on, the list opens in the source's order when MultiColumnModeSourceDataSortedColumnIndex is 0, instead of sorting itself by that column. The user can still sort by clicking a heading.

Gets or sets whether the user picks a row of the multi-column drop-down with a single click or a double-click.

Enter always picks the highlighted row. A double-click leaves single clicks free for moving the highlight and for the headings; a single click suits short lists where the user picks at once.

Gets or sets whether the multi-column combo box moves the current record of the form's data binding when the user picks a row, and follows it when the form moves it.

When the user picks a row, the control moves the current record of its parent's binding for the same data source, so text boxes on the form bound to that source show the record picked; and when the current record is moved elsewhere (by a navigator, for example), the selection here follows.

Applies only while DropStyleIsMultiColumn is true. Set it before DataSource.

Gets or sets whether the filter and grouping sections of the multi-column drop-down's options pane open folded to their title lines.

The user unfolds each section with its + button. To hide the whole pane instead, set KeepTheFilterAndGroupingViewsPaneFullyCollapsedAtStartup.

Gets or sets whether the multi-column drop-down opens with its filter and grouping pane hidden, leaving only the button that shows it.

The user shows the pane with the button at the bottom of the window, captioned by MultiColumnViewUIElementsTextProvider.WindowItemShowFilterAndGroupingOptions. Applies only while ShowFilterOptionsInMultiColumnMode is true.

Gets or sets the order of the group headings when the multi-column drop-down opens with its rows grouped.

The value also seeds the direction of the sort the list applies when it opens (see MultiColumnModeSourceDataSortedColumnIndex): opening reverses it once, so with Ascending rows sorted on the first column open in descending order, and with None or Descending in ascending order.

Gets or sets the size of the multi-column drop-down window, in logical pixels.

Size.Empty sizes the window to show every column in full and about a dozen rows, and never narrower than the combo box. Any other value is the size to open at, scaled to the display the combo box is on – a value in a form's designer file keeps meaning what it meant at 100%. Either way the window is kept within the working area of that display.

When the user resizes the window, the size they chose is stored here, in logical pixels, and the next open uses it. Setting the property is ignored unless DropStyleIsMultiColumn is true, so set that first.

Gets or sets the settings for the multi-column drop-down's header and footer bands, its column headings, and its no-data message.

The header and footer are drawn only while EnableDrawingHeaderFooterWhenInMultiColumnMode is true; the column heading font and colour and the no-data message apply always. In the designer the settings expand in the Properties window and are saved with the form.

Gets or sets the background colour of the rows in the multi-column drop-down.

Gets or sets the font of the rows in the multi-column drop-down.

The row height, and the height of a window that sizes itself, follow this font. The headings use MultiColumnDropDownWindowConfiguration.ColumnHeaderFont.

Gets or sets the colour of the text in the rows of the multi-column drop-down.

Gets or sets whether lines are drawn between the rows and columns of the multi-column drop-down.

Gets or sets whether a row of the multi-column drop-down is highlighted when the pointer rests on it, without a click.

Highlighting a row does not pick it; the user still picks with the click set by ItemSelectionClick, or Enter.

Gets or sets whether the user can resize the multi-column drop-down by dragging its edges.

A resizable window has a sizing border and a size grip; a size the user drags it to is kept in MultiColumnDropDownSize for the next time it opens. With it off the window has a fixed, single-line border.

Gets or sets how the multi-column drop-down animates as it closes after the user picks a row.

The animation runs only while AnimateDropDownWindow is true and AnimationInterval is above 0, and only when the window closes because a row was picked – not on Escape or a click elsewhere.

Gets or sets the column the multi-column drop-down is sorted by when it opens.

On opening, the list sorts itself as if the user had clicked this column's heading, and the heading shows the sort arrow. With IsSourceDataPreSorted on, name the column the data is already sorted by: 0 leaves the rows in the source's order, and any other column is sorted again so its heading shows the arrow.

Nothing is sorted on opening when DataSourceViewCustomSortingExpression is set, or when EnableColumnSorting is off. The opening sort raises CustomSorting like a click does.

Gets or sets the message the multi-column drop-down shows while it rebuilds its rows – when the user filters or groups them.

Gets or sets the message the multi-column drop-down shows when a filter leaves no rows.

A data source with no rows at all shows MultiColumnDropDownWindowConfiguration.NoDataToDisplayMessageText instead.

Gets or sets the colour of the arrow drawn in the heading of the column the multi-column drop-down is sorted by.

The arrow points up for an ascending sort and down for a descending one. It is drawn only when the column is wide enough to hold it beside the heading text.

Gets or sets the captions, messages and menu text the multi-column drop-down shows, so they can be translated.

Change the provider's properties, in the designer or in code, before the drop-down opens; the window reads them each time it opens. The busy and no-data messages are MultiColumnViewBusyProcessingText and MultiColumnViewNoDataFoundText.

var text = productPicker.MultiColumnViewUIElementsTextProvider;
text.ContextMenuItemEnableDataGroupingText = "Grouper les données";
text.ContextMenuItemExportDataToCSV = "Exporter au format CSV";
text.WindowItemUseFilterToRetrieveData = "Filtrer les données";

Gets or sets whether NotInList is raised as the user types, rather than only when they leave the control.

Applies only while EnforceItemsInList is true. As the user types, the event is raised whenever no item starts with the text so far – so it warns as soon as the text cannot lead to an item. It can be raised more than once for one key; keep the handler light (a label or an error provider rather than a message box).

The check on leaving the control, for an exact match, still runs.

Gets or sets the position, in the data source, of the row picked in the multi-column drop-down.

Read it in a ComboBox.SelectedIndexChanged handler to find the record the user picked, for example to pass to GetTheColumnValue. In multi-column mode prefer it to ComboBox.SelectedIndex.

In multi-column mode, setting it selects that row and shows its DisplayMember value; -1, or a row that does not exist, clears the text and the selection. Outside multi-column mode setting it only stores the number.

Gets or sets the ValueMember value of the selected item – typically the key of the record the user picked.

In single-column mode this is the standard SelectedValue.

In multi-column mode, setting it selects the first row whose ValueMember value has the same text as the value given, and shows that row's DisplayMember value; a value no row has leaves the selection as it was. Setting null or Value clears the text. It is ignored while ValueMember is empty. For a data source that is a list of objects but not an IBindingList – a List or an array – only the first item's value is found; any other value selects the first row and clears the text, so bind such data through a BindingList.

The property can be data-bound, which makes the combo box a lookup: bind it to the foreign key of the record being edited.

// Show the customer of the order being edited, and write the user's choice back to it.
accountPicker.DataBindings.Add("SelectedValue", orderBindingSource, "AccountNo",
    true, DataSourceUpdateMode.OnPropertyChanged);

Gets or sets whether the multi-column drop-down keeps its size when the user shows or hides the filter and grouping pane, the pane taking its room from the list.

With it off, showing or hiding the pane makes the window taller where the list would otherwise be left with too little room. The pane is shown by ShowFilterOptionsInMultiColumnMode.

Gets or sets whether the user can drag the multi-column drop-down's column headings to change the order of the columns.

Without reordering, the list stretches its last column to fill the window's width, so no empty heading is left at the right. With reordering allowed it does not, and an empty heading area may show beside the last column.

Gets or sets whether the user can go on typing while the multi-column suggestion list is open.

With it on, the list stays open as the user types and closes when they click anywhere outside it and the control. With it off, the list takes the keyboard when it opens, so the user can move through it with the arrow keys, and it closes by itself when it loses the focus. See AutoCompleteStyleForMultiColumnModeIsMultiColumn.

Gets or sets whether the column widths the user has set in the multi-column drop-down are kept when a filter is applied or cleared.

Gets or sets whether the multi-column drop-down is moved and, if need be, shortened so that it fits on the screen.

With it on, the window opens below the control if it fits there, above it if it fits there instead, and otherwise on the side with more room, cut to fit; it is moved sideways as far as it must be to stay within the working area of the control's display. With it off, it always opens just below the control, where it may run off the screen.

CustomDropDownWindowLocationPoint, when set, takes precedence over both.

Gets or sets whether the drop-down opens when there is nothing to list.

With it on, an empty multi-column drop-down opens as a small window showing MultiColumnDropDownWindowConfiguration.NoDataToDisplayMessageText, and an empty ordinary list opens empty. With it off, clicking the button of an empty control does nothing.

Gets or sets whether the multi-column drop-down has a filter and grouping pane at its foot, for the user to filter and group the rows.

The pane offers a built-in filter on a chosen column – text columns keep the rows that start with what the user types, other columns follow BuiltinFilterOnNonStringTypeColumnFilterMode – and a custom filter expression in the syntax of Expression, such as Balance > 1000 AND City = 'Leeds'. The built-in filter can apply as the user types, or when they press OK. The pane also turns grouping on and picks the column to group by.

A status strip under the pane has a button that hides and shows it, and the shortcut menu gains commands to switch filtering and the status strip on and off. The pane is not shown when the data source has no rows.

The pane's starting state is set by FilteringIsON, DesiredFilterColumn, KeepTheFilterAndGroupingViewsCollapsedAtStartUp and KeepTheFilterAndGroupingViewsPaneFullyCollapsedAtStartup; its captions by MultiColumnViewUIElementsTextProvider.

Gets or sets the size of the multi-column suggestion list.

See AutoCompleteStyleForMultiColumnModeIsMultiColumn.

Gets or sets the width of each column of the multi-column suggestion list.

The widths are applied as given, without scaling to the display. A width beyond the last column adds an empty column. See AutoCompleteStyleForMultiColumnModeIsMultiColumn.

Gets or sets the table the multi-column drop-down lists. Kept for older applications; set DataSource instead.

Setting a table sets DataSource to it. Setting null leaves the data source as it is.

Reading it returns the table the multi-column drop-down lists: the bound DataTable itself, or the table the control builds from any other kind of data source.

Gets or sets the column or property of the data source whose value SelectedValue returns, such as the record's key.

In multi-column mode at run time a path such as "Customers.AccountNo" is cut to the column name, "AccountNo", so the same setting works for a DataSet and for its table. Setting it does not raise ComboBox.SelectedIndexChanged.

Closes the multi-column drop-down if it is open, without picking a row.

Does nothing when the drop-down is not open. The selection and text stay as they were.

Removes the control's application message filter and releases its resources.

Returns the text shown for one row of the data source: its DisplayMember value.

The row's display text; the object's own ToString text when DisplayMember is empty; or an empty string when there is no data source, the row does not exist or the value cannot be read.

Returns the value of one column of one row of the data source, as text – for reading another column of the record the user picked.

The value as text; or an empty string when the control is not in multi-column mode, the row is negative or does not exist, the name is empty or unknown, or (for a list of objects) the property is not a string.

accountPicker.SelectedIndexChanged += (sender, e) =>
{
    int row = accountPicker.SelectedIndexFromDropList;
    cityLabel.Text = accountPicker.GetTheColumnValue(row, "City");
};

Clears the selection, so the control shows no item, without raising ComboBox.SelectedIndexChanged.

ComboBox.SelectedIndex becomes -1 and the text area is emptied. Because the change is not reported, SelectedIndexFromDropList keeps its previous value.

Opens the drop-down: in multi-column mode it builds and shows the multi-column window; otherwise it raises the ComboBox.DropDown event as usual.

In multi-column mode the ComboBox.DropDown event is not raised; use DropDownAboutToBeShown. While the window is being built the text area shows BusyIndicatorText.

Raises the Control.KeyDown event after opening the multi-column drop-down for Alt+Down, Alt+Up or F4, when the control is in multi-column mode.

DropDownAboutToBeShown is raised first, and can keep the drop-down closed.

Raises the Control.KeyUp event and then does the control's typing work: completing the text, checking it for NotInList, and showing the multi-column suggestion list.

Raises the Control.Leave event, then raises NotInList if EnforceItemsInList is on and the text equals no item, and closes the multi-column suggestion list.

Raises the ComboBox.SelectedIndexChanged event after the control's own bookkeeping.

Before the event is raised the control puts back the previous item when it is in extended read-only mode, records the new SelectedIndexFromDropList, and moves the form's current record when KeepBindingContextInSyncWithParent is set. Changes the control makes while it is loading or rebinding its data are not reported.

Raises the Control.TextChanged event, then raises NotInList if the new text cannot lead to an item and RaiseNotInListWhenTyping is on.

Draws one item's text, in the list or on the closed control, over the background the base draws.

Items from a data source are aligned by BinaryComboBox.DropDownItemTextAlignment and show their DisplayMember value.

Watches the application's mouse clicks so that, while the multi-column suggestion list lets the user go on typing, a click outside the list and the control closes it.

Always false: every message carries on to its target.

Part of the IMessageFilter the control registers when it is created and removes when it is disposed. There is no need to call it.

Redraws the selected item's text on the closed control, aligned by BinaryComboBox.TextAlignment.

Draws the disabled control, with the selected item's text in SystemColors.ControlDark.

Processes Windows messages, raising DropDownAboutToBeShown when the user clicks the control or presses Alt+Down, and opening the multi-column drop-down in place of the ordinary list.

Occurs after each key the user types, just before the control completes the text, and lets the handler skip the completion.

Raised only when the control's own completion would run: AutoComplete on and AutoCompleteMode None. Skipping it leaves the typed text as it is, for that key only.

// Let the user type a new product code freely once it starts with "NEW-".
productPicker.AutoCompleting += (object sender, ref bool cancel) =>
{
    cancel = productPicker.Text.StartsWith("NEW-", StringComparison.OrdinalIgnoreCase);
};

Occurs when the multi-column drop-down is about to sort its rows by a column, so the application can supply its own comparison or cancel the sort.

Raised when the user clicks a column heading, and once as the drop-down opens for its first sort (see MultiColumnModeSourceDataSortedColumnIndex). Raised only while EnableColumnSorting is true.

After the handler returns, the list is sorted with CustomComparerImplementor – so set it in the handler for the columns that need it, and back to null for the built-in comparison, which orders values that read as numbers by their value and everything else as text, ignoring case.

// In the form: dates in the "Ordered" column read "12 Mar 2024", which does not sort as text.
private bool orderedNewestFirst;

private void HookUpOrderSorting()
{
    orderPicker.CustomSorting += (object sender, ref bool cancel, int column, string heading) =>
    {
        if (heading == "Ordered")
        {
            orderedNewestFirst = !orderedNewestFirst;
            orderPicker.CustomComparerImplementor = new DateColumnComparer(column, orderedNewestFirst);
        }
        else
        {
            orderPicker.CustomComparerImplementor = null;   // the built-in comparison
        }
    };
}

public sealed class DateColumnComparer : IComparer
{
    private readonly int column;
    private readonly bool descending;

    public DateColumnComparer(int column, bool descending)
    {
        this.column = column;
        this.descending = descending;
    }

    public int Compare(object x, object y)
    {
        DateTime a = DateTime.Parse(((ListViewItem)x).SubItems[column].Text);
        DateTime b = DateTime.Parse(((ListViewItem)y).SubItems[column].Text);
        return descending ? b.CompareTo(a) : a.CompareTo(b);
    }
}

Occurs when the user is about to open the drop-down – by clicking the control, or pressing Alt+Down, Alt+Up or, in multi-column mode, F4 – and lets the handler stop it.

Set the handler's cancelNow argument to true to keep the drop-down closed, for example until another field has been filled in. Opening it from code through DroppedDown does not raise the event.

The event can be raised more than once for one gesture (on the key going down and again on its release), so keep the handler quick and free of side effects such as message boxes.

contactPicker.DropDownAboutToBeShown += (object sender, ref bool cancelNow) =>
{
    // There is nothing to choose from until a customer is chosen.
    cancelNow = customerPicker.SelectedIndex < 0;
};

Occurs when the text the user typed matches no item in the list, so the application can reject it or add it.

Raised only while EnforceItemsInList is true. By default it is raised when the user leaves the control and the text equals no item. With RaiseNotInListWhenTyping on it is also raised as the user types, whenever no item starts with the text so far. Empty text is never reported. Case is matched as AutoCompleteIsCaseSensitive says.

The control does not change the text itself; the handler decides what happens.

cityPicker.EnforceItemsInList = true;
cityPicker.NotInList += (sender, userText) =>
{
    var answer = MessageBox.Show(this, "\"" + userText + "\" is not in the list. Add it?",
        "New city", MessageBoxButtons.YesNo);
    if (answer == DialogResult.Yes)
        cityPicker.Items.Add(userText);
    else
        cityPicker.MakeBlank();
};