BaseListBoxControl.DataSource Property

Gets or sets the data source that provides items to display in the control.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DefaultValue(null)]
[DXCategory("Data")]
public virtual object DataSource { get; set; }

VB.NET

<DefaultValue(Nothing)>
<DXCategory("Data")>
Public Overridable Property DataSource As Object

Property Value

Type	Default	Description
Object	null	A data source object whose data is displayed by the ListBox control.

Remarks

Use the DataSource property to bind the control to a data source and thus display data source records as listbox items. The data source can be any object implementing the IList or IListSource interface. Changing the DataSource property value at runtime raises the BaseListBoxControl.DataSourceChanged event.

The following properties can be additionally customized:

• BaseListBoxControl.ValueMember - Gets or sets the field name in the bound data source whose contents are assigned to item values.
• BaseListBoxControl.DisplayMember - Gets or sets the name of the data source field that specifies display text for listbox items. This property is not supported when listbox items are rendered based on Item Templates.
• CheckedListBoxControl: BaseCheckedListBoxControl.CheckMember - Gets or sets the name of the data source field that provides check states for listbox items.
• ImageListBoxControl: BaseImageListBoxControl.ImageMember - Gets or sets the name of the data source field that provides images for listbox items. This property is not supported when listbox items are rendered based on Item Templates.
• ImageListBoxControl: BaseImageListBoxControl.ImageIndexMember - Gets or sets the name of the data source field that provides image indexes for listbox items. This property is not supported when listbox items are rendered based on Item Templates.

To retrieve listbox items in bound mode, use the BaseListBoxControl.GetItem method.

To populate the ListBox control in unbound mode, add items to the control’s Items collection (ListBoxControl.Items, BaseCheckedListBoxControl.Items or BaseImageListBoxControl.Items).

Examples

The code below shows how to use a DataTable as a data source.

C#

using DevExpress.XtraEditors;

listBoxControl1.DataSource = GetCountries();
listBoxControl1.DisplayMember = "Name";
listBoxControl1.ValueMember = "PhoneCode";
listBoxControl1.SelectedValueChanged += ListBoxControl1_SelectedValueChanged;

private void ListBoxControl1_SelectedValueChanged(object sender, EventArgs e) {
    var listBoxControl = sender as ListBoxControl;
    XtraMessageBox.Show(listBoxControl.SelectedValue.ToString());
}

DataTable GetCountries() {
    DataTable table = new DataTable();
    DataColumn name = new DataColumn("Name", typeof(string));
    DataColumn phoneCode = new DataColumn("PhoneCode", typeof(int));
    table.Columns.AddRange(new DataColumn[] { name, phoneCode});
    table.Rows.Add(new object[] { "United States", 1 });
    table.Rows.Add(new object[] { "Afghanistan", 93 });
    // ...
    table.Rows.Add(new object[] { "Zimbabwe", 263 });
    return table;
}

VB.NET

Imports DevExpress.XtraEditors

listBoxControl1.DataSource = GetCountries()
listBoxControl1.DisplayMember = "Name"
listBoxControl1.ValueMember = "PhoneCode"
AddHandler listBoxControl1.SelectedValueChanged, AddressOf ListBoxControl1_SelectedValueChanged

Private Sub ListBoxControl1_SelectedValueChanged(ByVal sender As Object, ByVal e As EventArgs)
    Dim listBoxControl = TryCast(sender, ListBoxControl)
    Call XtraMessageBox.Show(listBoxControl.SelectedValue.ToString())
End Sub

Private Function GetCountries() As DataTable
    Dim table As DataTable = New DataTable()
    Dim name As DataColumn = New DataColumn("Name", GetType(String))
    Dim phoneCode As DataColumn = New DataColumn("PhoneCode", GetType(Integer))
    table.Columns.AddRange(New DataColumn() {name, phoneCode})
    table.Rows.Add(New Object() {"United States", 1})
    table.Rows.Add(New Object() {"Afghanistan", 93})
    ' ...
    table.Rows.Add(New Object() {"Zimbabwe", 263})
    Return table
End Function

The code below uses the ValueMember and DisplayMember properties to specify data fields that contain a business object’s value and string representation. If you do not specify these properties, the control uses the business object as a value and the ToString() method to obtain the object’s string representation.

C#

using DevExpress.XtraEditors;

listBoxControl1.DataSource = Country.Countries;
listBoxControl1.DisplayMember = "Name";
listBoxControl1.ValueMember = "PhoneCode";
listBoxControl1.SelectedValueChanged += ListBoxControl1_SelectedValueChanged;

private void ListBoxControl1_SelectedValueChanged(object sender, EventArgs e) {
    var listBoxControl = sender as ListBoxControl;
    XtraMessageBox.Show(listBoxControl.SelectedValue.ToString());
}

public class Country {
    public string Name { get; set; }
    public int PhoneCode { get; set; }

    public override string ToString() {
        return $"{Name}, {PhoneCode}";
    }

    public static Country[] Countries = (new Country[] {
        new Country() { Name = "United States", PhoneCode = 1 },
        new Country() { Name = "Afghanistan", PhoneCode = 93 },
        // ...
        new Country() { Name = "Zimbabwe", PhoneCode = 263 }
    });
}

VB.NET

Imports DevExpress.XtraEditors

listBoxControl1.DataSource = Country.Countries
listBoxControl1.DisplayMember = "Name"
listBoxControl1.ValueMember = "PhoneCode"
AddHandler listBoxControl1.SelectedValueChanged, AddressOf ListBoxControl1_SelectedValueChanged

Private Sub ListBoxControl1_SelectedValueChanged(ByVal sender As Object, ByVal e As EventArgs)
    Dim listBoxControl = TryCast(sender, ListBoxControl)
    Call XtraMessageBox.Show(listBoxControl.SelectedValue.ToString())
End Sub

Public Class Country
    Public Property Name As String
    Public Property PhoneCode As Integer

    Public Overrides Function ToString() As String
        Return $"{Name}, {PhoneCode}"
    End Function

    Public Shared Countries As Country() = (
        New Country() {
            New Country() With {
                .Name = "United States",
                .PhoneCode = 1
            },
            New Country() With {
                .Name = "Afghanistan",
                .PhoneCode = 93
            },
            New Country() With {
                .Name = "Zimbabwe",
                .PhoneCode = 263
            }
        }
    )
End Class

Related GitHub Examples

The following code snippets (auto-collected from DevExpress Examples) contain references to the DataSource property.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

C#

winforms-custom-imagecombobox-editor/CS/DXSample/MyPopupContainerEdit.cs#L29

get {
    return imageListBox.DataSource;
}

how-to-handle-diagramcontrol-events-to-save-diagrams-to-a-database-instead-of-a-file-system-t360920/CS/XtraDiagram.CustomDiagramStorage/DiagramOpenDialog.cs#L26

    if (!DesignMode)
        listBoxControl1.DataSource = DiagramRepository.GetDiagramNames();
}

xaf-how-to-display-a-collection-property-as-a-checked-list-box/CS/DXExample.Module.Win/WinCheckedListBoxPropertyEditor.cs#L32

}
Control.DataSource = dataSource;
Control.DisplayMember = classInfo.DefaultProperty;

reporting-crosstab-customization/CS/CrosstabControlCustomizationExample/Form1.cs#L19

    InitializeComponent();
    listBoxControl1.DataSource = ReportDescriptionData.GetData();
}

VB.NET

winforms-custom-imagecombobox-editor/VB/DXSample/MyPopupContainerEdit.vb#L31

Get
    Return imageListBox.DataSource
End Get

how-to-handle-diagramcontrol-events-to-save-diagrams-to-a-database-instead-of-a-file-system-t360920/VB/XtraDiagram.CustomDiagramStorage/DiagramOpenDialog.vb#L28

If Not DesignMode Then
    listBoxControl1.DataSource = DiagramRepository.GetDiagramNames()
End If

xaf-how-to-display-a-collection-property-as-a-checked-list-box/VB/DXExample.Module.Win/WinCheckedListBoxPropertyEditor.vb#L36

End If
Control.DataSource = dataSource
Control.DisplayMember = classInfo.DefaultProperty

reporting-crosstab-customization/VB/CrossTabControlCustomizationExample/Form1.vb#L20

    InitializeComponent()
    listBoxControl1.DataSource = ReportDescriptionData.GetData()
End Sub