Class Picker

A customizable UI component for selecting one or multiple items from a list.

Inheritance
object
CallbackEventHandler
Focusable
VisualElement
BaseVisualElement
ExVisualElement
Picker
Picker<TItem, TTitle>
Implements
Inherited Members
VisualElement.Focus()
VisualElement.Overlaps(Rect)
VisualElement.ToString()
VisualElement.TryGetBinding(BindingId, out Binding)
VisualElement.TryGetDataSourceContext(BindingId, out DataSourceContext)
VisualElement.TryGetLastBindingToUIResult(in BindingId, out BindingResult)
VisualElement.TryGetLastBindingToSourceResult(in BindingId, out BindingResult)
VisualElement.GetFirstOfType<T>()
VisualElement.GetFirstAncestorOfType<T>()
VisualElement.canGrabFocus
VisualElement.focusController
VisualElement.cacheAsBitmap
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallbackOnce<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, TrickleDown)
CallbackEventHandler.RegisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.RegisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TUserArgsType, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType>(EventCallback<TEventType>, CallbackOptions)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, TrickleDown)
CallbackEventHandler.UnregisterCallback<TEventType, TUserArgsType>(EventCallback<TEventType, TUserArgsType>, CallbackOptions)
CallbackEventHandler.NotifyPropertyChanged(in BindingId)
Namespace: Unity.AppUI.UI
Assembly: Unity.AppUI.dll
Syntax
[UxmlElement]
public abstract class Picker : ExVisualElement, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IContextOverrideElement, IAdditionalDataHolder, IInputElement<IEnumerable<int>>, IValidatableElement<IEnumerable<int>>, INotifyValueChanged<IEnumerable<int>>, ISizeableElement, IPressable
Remarks

The Picker component provides a flexible way to present users with a list of selectable options. It supports both single and multiple selection modes, making it suitable for various use cases.

When clicked, the Picker displays a menu containing the available options. Users can select items from this menu, and the selection is reflected in the Picker's title area.

The component is highly customizable through its various properties and can be styled using USS classes. It supports both keyboard navigation and mouse interaction.

NOTE: The Picker is an abstract base class. For implementation, use concrete classes like Dropdown that inherit from Picker.

Examples

Create a basic single-select picker with string items.

// Create a basic single-select picker
var picker = new Dropdown();
picker.sourceItems = new List<string> { "Small", "Medium", "Large" };
picker.defaultMessage = "Select size...";
picker.selectedIndex = 1; // Select "Medium" by default

Create a multi-select picker with custom item binding.

// Create a multi-select picker with custom binding
var picker = new Dropdown();
var items = new List<string> { "Red", "Green", "Blue" };

picker.sourceItems = items;
picker.selectionType = PickerSelectionType.Multiple;
picker.bindItem = (item, index) => ;
picker.value = new[] { 0, 2 }; // Select "Red" and "Blue"

Create a picker with validation and change event handling.

// Create a picker with validation
var picker = new Dropdown();
picker.sourceItems = new List<string> { "Option 1", "Option 2", "Option 3" };
picker.validateValue = (values) => {
    // Require at least one selection
    return values.Any();
};
picker.RegisterValueChangedCallback(evt => {
    Debug.Log($"Selection changed: {string.Join(", ", evt.newValue)}");
});

Constructors

Picker()

Default constructor.

Declaration
public Picker()

Picker(IList, int[])

Construct a Picker UI element with a provided dynamic collection of items.

Declaration
public Picker(IList items, int[] defaultIndices = null)
Parameters
Type Name Description
IList items

An items collection.
int[] defaultIndices

The selected index by default.

Fields

appuiPickerMenu

The Picker menu styling class.

Declaration
public const string appuiPickerMenu = "appui-picker__menu"
Field Value
Type Description
string

caretUssClassName

The Picker caret styling class.

Declaration
public const string caretUssClassName = "appui-picker__caret"
Field Value
Type Description
string

emphasizedUssClassName

The Picker emphasized mode styling class.

Declaration
public const string emphasizedUssClassName = "appui-picker--emphasized"
Field Value
Type Description
string

m_Items

The list of items contained in the Picker.

Declaration
protected readonly List<PickerItem> m_Items
Field Value
Type Description
List<PickerItem>

m_TitleContainer

The container for the Picker title.

Declaration
protected readonly VisualElement m_TitleContainer
Field Value
Type Description
VisualElement

m_Value

The list of indices of the selected items.

Declaration
protected readonly List<int> m_Value
Field Value
Type Description
List<int>

sizeUssClassName

The Picker size styling class.

Declaration
public const string sizeUssClassName = "appui-picker--size-"
Field Value
Type Description
string

titleContainerUssClassName

The Picker title container styling class.

Declaration
public const string titleContainerUssClassName = "appui-picker__titlecontainer"
Field Value
Type Description
string

titleUssClassName

The Picker title styling class.

Declaration
public const string titleUssClassName = "appui-picker__title"
Field Value
Type Description
string

trailingContainerUssClassName

The Picker trailing container styling class.

Declaration
public const string trailingContainerUssClassName = "appui-picker__trailingcontainer"
Field Value
Type Description
string

ussClassName

The Picker main styling class.

Declaration
public const string ussClassName = "appui-picker"
Field Value
Type Description
string

Properties

clickable

Clickable Manipulator for this Picker.

Declaration
[CreateProperty]
public Pressable clickable { get; set; }
Property Value
Type Description
Pressable

closeOnSelection

Close the picker menu automatically when an item is selected.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool closeOnSelection { get; set; }
Property Value
Type Description
bool

defaultMessage

The Picker default message when no item is selected.

Declaration
[CreateProperty]
[UxmlAttribute]
public string defaultMessage { get; set; }
Property Value
Type Description
string

defaultValue

The Picker default value. This is the value that will be selected if no value is set.

Declaration
[CreateProperty]
public int[] defaultValue { get; set; }
Property Value
Type Description
int[]

emphasized

The Picker emphasized mode.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool emphasized { get; set; }
Property Value
Type Description
bool

invalid

The Picker invalid state.

Declaration
[CreateProperty]
[UxmlAttribute]
public bool invalid { get; set; }
Property Value
Type Description
bool

selectedIndex

Quick access to the currently selected index for a Picker in Single selection mode.

Declaration
[CreateProperty]
public int selectedIndex { get; set; }
Property Value
Type Description
int

selectionType

The Picker selection type.

Declaration
[CreateProperty]
[UxmlAttribute]
public PickerSelectionType selectionType { get; set; }
Property Value
Type Description
PickerSelectionType
Remarks

If the selection type is changed, the Picker value will be reset.

size

The Picker size.

Declaration
[CreateProperty]
[UxmlAttribute]
public Size size { get; set; }
Property Value
Type Description
Size

sourceItems

The source items collection.

Declaration
[CreateProperty]
public IList sourceItems { get; set; }
Property Value
Type Description
IList

validateValue

The Picker validation function.

Declaration
[CreateProperty]
public Func<IEnumerable<int>, bool> validateValue { get; set; }
Property Value
Type Description
Func<IEnumerable<int>, bool>

value

The Picker value. This is the index of the selected item.

Declaration
[CreateProperty]
public IEnumerable<int> value { get; set; }
Property Value
Type Description
IEnumerable<int>

Methods

GetSizeUssClassName(Size)

Declaration
public static string GetSizeUssClassName(Size enumValue)
Parameters
Type Name Description
Size enumValue
Returns
Type Description
string

OnPickerItemRemoved(PickerItem, int)

Called when a Picker item is removed.

Declaration
protected virtual void OnPickerItemRemoved(PickerItem item, int index)
Parameters
Type Name Description
PickerItem item

The item to remove.
int index

The index of the item to remove.

OnPickerItemsCreated()

Called when the Picker items are created.

Declaration
protected virtual void OnPickerItemsCreated()

OnRequestItemCreation(int)

Create a Picker item.

Declaration
protected abstract VisualElement OnRequestItemCreation(int i)
Parameters
Type Name Description
int i

The index of the item to create.
Returns
Type Description
VisualElement

The created item.

OnUnbindItem(VisualElement, int)

Unbind a Picker item.

Declaration
protected abstract void OnUnbindItem(VisualElement item, int index)
Parameters
Type Name Description
VisualElement item

The item to unbind.
int index

The index of the item to unbind.

OnValueSet()

Called when the Picker value is set with or without notifying listeners.

Declaration
protected virtual void OnValueSet()

Refresh()

Refresh the Picker UI.

Declaration
public void Refresh()

RefreshListUI()

Refresh the Picker list UI.

Declaration
protected void RefreshListUI()

RefreshTitleUI()

Refresh the Picker title UI.

Declaration
protected abstract void RefreshTitleUI()

RefreshUI()

Refresh the Picker UI.

Declaration
protected void RefreshUI()

SetValueWithoutNotify(IEnumerable<int>)

Set the Picker value without notifying any listeners.

Declaration
public void SetValueWithoutNotify(IEnumerable<int> newValue)
Parameters
Type Name Description
IEnumerable<int> newValue

The new value to set.

Implements

Extension Methods