uilistbox - Create list box component - MATLAB (original) (raw)

Create list box component

Syntax

Description

`lb` = uilistbox creates a list box in a new figure window and returns the ListBox object. MATLAB® calls the uifigure function to create the figure.

`lb` = uilistbox([parent](#buijl86-1%5Fsep%5Fmw%5Fa6330465-2069-40e4-857c-69da4d660066)) creates the list box in the specified parent container. The parent can be aFigure object or one of its child containers.

example

`lb` = uilistbox(___,[Name,Value](#namevaluepairarguments)) creates the list box with properties specified by one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes. For example, uilistbox("Multiselect","on") creates a list box that allows an app user to select multiple items.

example

Examples

collapse all

Create a list box in a UI figure.

fig = uifigure; lb = uilistbox(fig);

Create a list box in a UI figure, and specify the list box items.

fig = uifigure; lb = uilistbox(fig,"Items",["Australia","France","Germany"]);

Query the value of the selected item.

Programmatically update the list box selection.

Create a list box in a UI figure. Allow the app users to select multiple items.

fig = uifigure; lb = uilistbox(fig,"Multiselect","on");

Select multiple items in the list box by holding Ctrl while clicking.

The Value property stores all selected items as a cell array.

val =

1×2 cell array

{'Item 2'}    {'Item 4'}

Create a list box in a UI figure, and specify a list of color names that appear in the list box by setting the Items property.

fig = uifigure; lb = uilistbox(fig,"Items",["Red","Green","Blue"]);

When there is no data associated with the items, the Value property of the list box is an element of Items.

Associate hex color data with the list box items by setting the ItemsData property. Setting ItemsData does not change how the items are displayed to the app user.

lb.ItemsData = ["#F00","#0F0","#00F"];

When the ItemsData property is nonempty, the Value property of the list box is an element of ItemsData.

Specifying ItemsData can make it easier to perform operations associated with the selected item. For example, plot some data in the selected color by passing the hex color value directly to the plot function.

plot(1:10,"Color",lb.Value)

Create an app that updates the colormap of a chart when a user selects a list box item.

In a file named colormapApp.m, write a function that implements the app:

• Create a UI figure and a grid layout manager to lay out the app.
• Create a list box and UI axes with some plotted data in the grid layout manager.
• Write a callback function named listBoxValueChanged that updates the colormap for the UI axes, and assign the function to the ValueChangedFcn callback property of the list box. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.

function colormapApp fig = uifigure; g = uigridlayout(fig,[3 2]); g.RowHeight = {'1x','fit','1x'}; g.ColumnWidth = {'fit','1x'};

lb = uilistbox(g, ... "Items",["Spring","Summer","Autumn","Winter"], ... "ItemsData",{spring,summer,autumn,winter}); lb.Layout.Row = 2; lb.Layout.Column = 1; ax = uiaxes(g); ax.Layout.Row = [1 3]; ax.Layout.Column = 2; surf(ax,peaks) colormap(ax,spring)

lb.ValueChangedFcn = @(src,event) listBoxValueChanged(src,event,ax); end

function listBoxValueChanged(src,event,ax) cmap = event.Value; colormap(ax,cmap) end

Run the colormapApp function. Select an item in the list box to change the colormap.

Since R2023a

Create a list box with three items that represent different images.

fig = uifigure; lb = uilistbox(fig,"Items",["Peppers","Nebula","Street"]);

Create three styles with icons that correspond to the list box items.

s1 = uistyle("Icon","peppers.png"); s2 = uistyle("Icon","ngc6543a.jpg"); s3 = uistyle("Icon","street1.jpg");

Add the styles to the list box items to display the icons.

addStyle(lb,s1,"item",1); addStyle(lb,s2,"item",2); addStyle(lb,s3,"item",3);

Input Arguments

collapse all

Parent container, specified as a Figure object or one of its child containers: Tab, Panel, ButtonGroup, orGridLayout. If you do not specify a parent container, MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: uilistbox(Items=["Model 1","Model 2","Model 3"]) specifies the list box items.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: uilistbox("Items",["Model 1","Model 2","Model 3"]) specifies the list box items.

Note

The properties listed here are a subset of the available properties. For the full list, see ListBox.

List box items, specified as a cell array of character vectors, string array, or 1-D categorical array. Duplicate elements are allowed. The list box displays as many options as there are elements in the Items array. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

Tips

Use the scroll function to programmatically scroll a list box item or the top or bottom of the list into view.

Version History

Introduced in R2016a

expand all

Access the index of the component value in the list of items by using theValueIndex property.

Create styles for list box components using the uistyle function, and add the styles to individual items or entire list box components using the addStyle function.

Use the ClickedFcn and DoubleClickedFcn callback properties to program a response to a user clicking and double-clicking the list box.

For more information, see ListBox.