ComboBox

Introduction

The ComboBox control provides a compact way for users to select from a list of options.

Code Example: Adding a ComboBox

// Initialize
var comboBox = new ComboBox();
comboBox.AddToRoot();
for(int i = 0; i < 10; i++)
{
    comboBox.Items.Add($"Item {i}");
}

Try on XnaFiddle.NET

ComboBox displaying a list of items

ComboBox's internal ListBox is hidden until the dropdown opens, so Gum automatically skips layout when adding items. This means adding hundreds of items to a ComboBox is fast without any extra code. If you are adding many items to a visible ListBox or other ItemsControl, see Reducing Layout Calls for how to suspend layout during bulk adds.

Adjusting the Drop-Down ListBox

ComboBox provides a ListBox property which can be used to customize the ListBox instance.

This can be modified, even if it hasn't yet been shown. The following code shows how to modify the default size of the ListBox:

// Initialize
var comboBox = new ComboBox();
comboBox.AddToRoot();
comboBox.Anchor(Gum.Wireframe.Anchor.Top);
comboBox.ListBox.Height = 400;

for(int i = 0; i < 40; i++)
{
    comboBox.Items.Add($"Item {i+1}");
}

Try on XnaFiddle.NET

ComboBox ListBox with custom Height

The ListBox property returns a fully functional ListBox instance. For more information on how to customize the ListBox, see the ListBox page.

Performance with Many Items

If all items in the ComboBox dropdown are the same height (no text wrapping or variable-sized icons), you can improve dropdown open performance by setting UseFixedStackChildrenSize on the ListBox's inner panel. This tells the layout engine to measure only the first child and assume all others are the same size, skipping per-child measurement.

// Initialize
var comboBox = new ComboBox();
comboBox.AddToRoot();
comboBox.ListBox.InnerPanel.UseFixedStackChildrenSize = true;

for(int i = 0; i < 800; i++)
{
    comboBox.Items.Add($"Item {i}");
}

Only use UseFixedStackChildrenSize when all items have the same height. If items have different heights (for example, from text wrapping or varying content), this setting produces incorrect layout.

SelectedObject and SelectedIndex

Use SelectedIndex to select an item by its zero-based position in Items, or read it back to find which item is currently selected. Use SelectedObject to get or set the selected item directly as an object.

// Initialize
var comboBox = new ComboBox();
comboBox.AddToRoot();
for(int i = 0; i < 5; i++)
{
    comboBox.Items.Add($"Item {i}");
}
comboBox.SelectedIndex = 2;

Try on XnaFiddle.NET

SelectionChanged

The SelectionChanged event fires whenever the user picks a different item. The handler receives a SelectionChangedEventArgs with information about the previously and newly selected items. You can also read SelectedObject or SelectedIndex directly inside the handler.

// Initialize
var label = new Label();
label.AddToRoot();

var comboBox = new ComboBox();
comboBox.AddToRoot();
comboBox.Y = 24;
for(int i = 0; i < 5; i++)
{
    comboBox.Items.Add($"Item {i}");
}
comboBox.SelectionChanged += (sender, args) =>
{
    // comboBox.SelectedObject holds the newly selected item
    label.Text = $"Selected: {comboBox.SelectedObject}";
};

Try on XnaFiddle.NET