ASPxComboBox Class

An editor which displays a list of items within its dropdown window.

Assembly: DevExpress.Web.v24.1.dll

Declaration

C#
VB.NET

public class ASPxComboBox :
    ASPxAutoCompleteBoxBase,
    IListBoxColumnsOwner,
    IValueTypeHolder,
    IControlDesigner,
    IListEditItemRequestEventOwner,
    IListEditCustomFilteringEventOwner,
    IListEditServerModeOwner

Public Class ASPxComboBox
    Inherits ASPxAutoCompleteBoxBase
    Implements IListBoxColumnsOwner,
               IValueTypeHolder,
               IControlDesigner,
               IListEditItemRequestEventOwner,
               IListEditCustomFilteringEventOwner,
               IListEditServerModeOwner

Library	Related API Members
ASP.NET Web Forms Controls	ASPxCardViewGroupSelectorInitializeEventArgs.GroupSelector
XAF: Cross-Platform .NET App UI & Web API	RenderHelper.CreateASPxComboBox()

Remarks

The ASPxComboBox control combines the functionality of a text editor, button editor, and drop-down list editor. The editor’s drop-down menu displays a list of items that users can select.

ASPxComboBox Control

Run Demo

Create a ComboBox Control

Design Time

The ASPxComboBox control is available on the DX.24.1: Common Concepts toolbox tab in the Microsoft Visual Studio IDE.

ComboBox in Toolbox

Drag the control onto a form and customize the control’s settings, or paste the control’s markup in the page’s source code.

ASPX

<dx:ASPxComboBox ID="ASPxComboBox1" runat="server">
</dx:ASPxComboBox>

using DevExpress.Web;
//...
protected void Page_Load(object sender, EventArgs e) {
    ASPxComboBox comboBox = new ASPxComboBox();
    comboBox.ID = "ASPxComboBox1";
    // Add the created control to the page
    Page.Form.Controls.Add(comboBox);
}

Imports DevExpress.Web
' ...
Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
    Dim comboBox As ASPxComboBox = New ASPxComboBox()
    comboBox.ID = "ASPxComboBox1"
    ' Add the created control to the page
    Page.Form.Controls.Add(comboBox)
End Sub

Client-Side API

Availability	Set the ASPxEditBase.EnableClientSideAPI property to `true` or handle any client event.
Client object type	ASPxClientComboBox
Access name	ASPxEditBase.ClientInstanceName
Events	ASPxComboBox.ClientSideEvents

Run Demo: Cascading Combo Boxes

Bind to Data

Specify the DataSourceID property to bind ASPxComboBox at design time, or call the DataBind() or DataBindItems() method to bind the editor at runtime.

Important

If you bind ASPxComboBox at runtime, make sure that you perform this operation during each round trip to the server in the control’s Init or Page_Init event.

C#
VB.NET

protected void ASPxComboBox_Init(object sender, EventArgs e) {  
    DevExpress.Web.ASPxEditors.ASPxComboBox cmb = (DevExpress.Web.ASPxEditors.ASPxComboBox)sender;  
    cmb.DataSource = DATA_SOURCE;  
    cmb.DataBindItems();  
}

Protected Sub ASPxComboBox_Init(sender As Object, e As EventArgs)  
    Dim cmb As DevExpress.Web.ASPxEditors.ASPxComboBox = DirectCast(sender, DevExpress.Web.ASPxEditors.ASPxComboBox)  
    cmb.DataSource = DATA_SOURCE  
    cmb.DataBindItems()  
End Sub

The ASPxComboBox automatically binds its items to data if the data source fields are named in the same way as the item properties (Text, Name, ImageUrl). Otherwise, you should specify these properties:

Name	Description
ImageUrlField	Specifies the data source field that contains the image location for the editor’s items.
TextField	Specifies the data source field that contains texts to display in the dropdown.
ValueField	Specifies the data source field that contains values for the editor’s items.

ASPX

<dx:ASPxComboBox ID="ASPxComboBox1" runat="server" 
    DataSourceID="ProductsDataSource" TextField="ProductName" ValueField="ProductName">
    <!--...-->
</dx:ASPxComboBox>
<ef:EntityDataSource runat="server" ID="ProductsDataSource" ... />

Run Demo: Bind to Data

The ASPxAutoCompleteBoxBase.Items collection contains the ASPxComboBox‘s items. You can access an individual item and specify its properties (ListEditItem).

Database Server Mode

In this mode, the editor loads only required (visible) items to the server memory and executes data operations (for instance, filtering) at the data source level. The GridViewDataComboBoxColumn object does not support database server mode.

Bind the ASPxComboBox to the LinqServerModeDataSource or EntityServerModeDataSource and set the EnableCallbackMode property to true to enable the database server mode.

Run Demo: Database Server Mode

Item Load Modes

The ASPxComboBox supports the following load modes:

Load Mode	Description	Affected Properties
Default	The editor loads items and executes all data operations (for instance, scrolling, filtering, and so on) on the client without a round trip to the server.	EnableCallbackMode=”False”
On-Demand	You can use callbacks to load items from the server on demand. For instance, the editor can dynamically load non-displayed items when a user scrolls the dropdown.	EnableCallbackMode = “True”
Dynamic	You can manually populate a dropdown list with the required items based on the filter criteria and a user’s scroll action.	EnableCallbackMode=”True”

ASPxComboBox - Item Load Mode

ASPX

<dx:ASPxComboBox ID="ASPxComboBox1" runat="server"  EnableCallbackMode="true" CallbackPageSize="30" 
    DataSourceID="SqlDataSource1" ValueField="ShipName" TextField="ShipName">
</dx:ASPxComboBox>
<asp:SqlDataSource ID="SqlDataSource1" runat="server" ...></asp:SqlDataSource>

Incremental Filtering

Use the ASPxAutoCompleteBoxBase.IncrementalFilteringMode property to enable the control to filter data while a user types the filter string.

Filter Mode	Description
StartsWith	The editor filters items that begin with the filter string.
Contains	The editor filters items that contain the filter string.

ComboBox-IncrementalFilteringMode-StartsWith

ASPX

<dx:ASPxComboBox ID="Countries" runat="server" EnableCallbackMode="True" IncrementalFilteringMode="StartsWith">
    <Items>
        <!--...-->
    </Items>
</dx:ASPxComboBox>

Run Demo: ASPxComboBox - Incremental Filtering

You can also use the following properties:

Property	Description
ASPxAutoCompleteBoxBase.IncrementalFilteringDelay	Specifies the time interval after which the editor filters items.
ASPxAutoCompleteBoxBase.FilterMinLength	Specifies the minimum filter string length to filter items.

Custom Filtering

You can filter items by multiple words and columns, or use diacritic characters in the filter string.

ASPxComboBox-CustomFiltering

ASPX
JS

<dx:ASPxComboBox ID="CmbWithClientFiltering" runat="server" ValueField="Name" TextField="Name" DataSourceID="GermanCitiesDataSource" IncrementalFilteringMode="Contains">
    <ClientSideEvents ItemFiltering="onItemFiltering" CustomHighlighting="onCustomHighlighting" />
</dx:ASPxComboBox>

function onItemFiltering(s, e) {
    if (!e.isFit)
        e.isFit = toLatin(e.item.text).indexOf(toLatin(e.filter)) > -1;
}

function onCustomHighlighting(s, e) {
    e.highlighting = new RegExp(toLatin(e.filter)
        .replace(/u/gi, "(u|\u00fc)")
        .replace(/a/gi, "(a|\u00e4)")
        .replace(/o/gi, "(o|\u00f6)")
    , "gi");
}

function toLatin(text) {
    return text
        .replace(/\u00fc/gi, "u")
        .replace(/\u00e4/gi, "a")
        .replace(/\u00f6/gi, "o")
        .toLowerCase();
}

Run Demo: ASPxComboBox - Custom Filtering

Display Format

You can specify indexed placeholders (such as “{0}”, “{1}”, and so on) and literals for the following properties to customize the text of the ASPxComboBox‘s edit box:

Property	Description
ASPxAutoCompleteBoxBase.TextFormatString	Defines a pattern to display the selected item’s text when there are several columns in the dropdown.
ASPxTextEdit.DisplayFormatString	Defines the pattern applied to the editor’s value.

ASPxComboBox - Display Formatting

ASPX

<dx:ASPxComboBox ID="ASPxComboBox4" runat="server" DataSourceID="EmployeesDataSource" 
                 TextFormatString="{0} from {2}" ValueField="EmployeeID">
    <Columns>
        <!--...-->
    </Columns>
</dx:ASPxComboBox>

Run Demo: ASPxComboBox - Display Format

Multi-Column Mode

The ASPxComboBox allows you to display a collection of data source fields as multiple columns in the drop-down list.

In design mode, invoke the Designer… and select the Columns… item from the smart tag menu to add and configure columns. Alternatively, you can use the ASPxComboBox.Columns property to access the editor’s columns collection. Specify the ListBoxColumn.FieldName property to bind the column’s items to a data source field.
You can also specify header caption, width, visibility state, and other settings for columns.

ASPX

<dx:ASPxComboBox ID="CmbCustomers" runat="server" DataSourceID="CustomersDataSource" ValueField="CustomerID" ValueType="System.String" TextFormatString="{0}" EnableCallbackMode="true">
    <Columns>
        <dx:ListBoxColumn FieldName="ContactName" />
        <!--...-->
    </Columns>
</dx:ASPxComboBox>

Run Demo: ASPxComboBox - Multi-Column Mode

Item Images

The ASPxComboBox‘s drop-down window can display items with associated images.

Property	Description
ASPxAutoCompleteBoxBase.ItemImage	Specifies a uniform image for all editor’s items.
ListEditItem.ImageUrl	Specifies an image for an individual item.
ASPxAutoCompleteBoxBase.ImageUrlField	Specifies a data field that contains image URLs.

ASPxComboBox_concepts4

ASPX

<dx:ASPxComboBox ID="ASPxComboBox2" runat="server" ShowImageInEditBox="True">
    <ItemImage Height="24px" Width="23px" />
    <Items>
        <dx:ListEditItem Text="Manhattan Bar" ImageUrl="your path" />
        <!--...-->
    </Items>
</dx:ASPxComboBox>

Run Demo: ASPxComboBox - Item Images

Item Appearance Customization

The ASPxComboBox allows you to customize item appearance. Use the ItemTextCellPrepared and ItemRowPrepared events to specify the style of the drop-down window’s cells and rows.

ASPxComboBox-ItemAppearanceCustomization

<dx:ASPxComboBox ID="customersComboBox" runat="server" DataSourceID="CustomersDataSource" ValueField="CustomerID" ValueType="System.String" TextFormatString="{0}" EnableCallbackMode="true" OnItemTextCellPrepared="customersComboBox_ItemTextCellPrepared" OnItemRowPrepared="customersComboBox_ItemRowPrepared">
    <Columns>
        <dx:ListBoxColumn FieldName="ContactName" />
        <dx:ListBoxColumn FieldName="CompanyName" />
        <dx:ListBoxColumn FieldName="Phone" />
    </Columns>
</dx:ASPxComboBox>

protected void Page_Load(object sender, EventArgs e) {
    DemoHelper.Instance.ControlAreaMinHeight = Unit.Pixel(310);
}

//specify the tooltip structure
string GetItemTooltip(ListEditItem item) {
    return string.Format("Country: {0}\r\nCity: {1} \r\nAddress: {2}", item.GetFieldValue("Country"), item.GetFieldValue("City"), item.GetFieldValue("Address"));
}

//customize the tootltip for specific cells, specify their appearance
protected void customersComboBox_ItemTextCellPrepared(object sender, ListBoxItemTextCellPreparedEventArgs e) {
    if(e.Column.FieldName == "ContactName") {
        string contactTitle = e.Item.GetFieldValue("ContactTitle").ToString();
        if(contactTitle == "Owner") {
            e.TextCell.CssClass += " owner";
            e.TextCell.ToolTip = "Owner";
        }
    }

    if(e.Column.FieldName == "Phone")
        e.TextCell.CssClass += " phone";
}

//show the tooltip
protected void customersComboBox_ItemRowPrepared(object sender, ListBoxItemRowPreparedEventArgs e) {
    e.Row.ToolTip = GetItemTooltip(e.Item);
}

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
    DemoHelper.Instance.ControlAreaMinHeight = Unit.Pixel(310)
End Sub

' specify the tooltip structure
Private Function GetItemTooltip(ByVal item As ListEditItem) As String
    Return String.Format("Country: {0}" & Constants.vbCrLf & "City: {1} " & Constants.vbCrLf & "Address: {2}", item.GetFieldValue("Country"), item.GetFieldValue("City"), item.GetFieldValue("Address"))
End Function

' customize the tootltip for specific cells, specify their appearance
Protected Sub customersComboBox_ItemTextCellPrepared(ByVal sender As Object, ByVal e As ListBoxItemTextCellPreparedEventArgs)
    If e.Column.FieldName = "ContactName" Then
        Dim contactTitle As String = e.Item.GetFieldValue("ContactTitle").ToString()
        If contactTitle = "Owner" Then
            e.TextCell.CssClass &= " owner"
            e.TextCell.ToolTip = "Owner"
        End If
    End If

    If e.Column.FieldName = "Phone" Then
        e.TextCell.CssClass &= " phone"
    End If

End Sub

' show the tooltip
Protected Sub customersComboBox_ItemRowPrepared(ByVal sender As Object, ByVal e As ListBoxItemRowPreparedEventArgs)
    e.Row.ToolTip = GetItemTooltip(e.Item)
End Sub

Run Demo: ASPxComboBox - Item Appearance Customization

Item Template

Use the ASPxAutoCompleteBoxBase.ItemTemplate property to define a custom layout for the editor’s items.

ASPxComboBox-ItemTemplate

ASPX

<dx:ASPxComboBox ID="ComboBox" EnableCallbackMode="true" DataSourceID="ContactsDataSource" TextField="Name" runat="server">
    <ItemTemplate>
        <table>
            <tr>
                <td rowspan="2">
                    <div class="frame">
                        <img class="photo" alt="photo" src="<%# Page.ResolveUrl(Eval("PhotoUrl").ToString()) %>" />
                    </div>
                </td>
                <!--...-->
        </table>
    </ItemTemplate>
</dx:ASPxComboBox>

Run Demo: ASPxComboBox - Item Template

Customizable Button Collection

The ASPxComboBox contains an edit button collection (EditButtonCollection) that allows you to define button appearance and handle its events. You can also customize the DropDownButton‘s settings.

ASPxComboBox_concepts5

ASPX

<dx:ASPxComboBox ID="ASPxComboBox" runat="server">
    <Buttons>
        <dx:EditButton Text="Previous" Position="Left" />
        <dx:EditButton Text="Next" Position="Right" />
    </Buttons>
</dx:ASPxComboBox>

Built-in Validation

The ASPxComboBox supports the client-side and server-side validation.

The control allows you to define validation rules in the following ways:

The ValidationSettings.RequiredField property allows you to mark the editor as required.
The ValidationSettings.RegularExpression property allows you to validate the editor’s value based on a regular expression.
Validation events validate the editor’s input data on the client or server.

ASPX

<dx:ASPxComboBox ID="ASPxComboBox" runat="server" DataSourceID="SqlDataSource1" TextField="City" ValueField="City" >
    <ValidationSettings ErrorTextPosition="Bottom" Display="Dynamic">
        <RequiredField IsRequired="True" ErrorText="Select a city!" />
    </ValidationSettings>
</dx:ASPxComboBox>

ASPxComboBox-Validation