uilistbox

Create list box component

Syntax

lb = uilistbox

lb = uilistbox(parent)

lb = uilistbox(___,Name,Value)

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) creates the list box in the specified parent container. The parent can be a Figure created using the uifigure function, or one of its child containers.

lb = uilistbox(___,Name,Value) specifies ListBox properties using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

Create List Box

Create a list box in a figure window.

fig = uifigure('Position', [100 100 300 250]);
lbx = uilistbox(fig);

Set and Access List Box Property Values

Create a list box.

fig = uifigure;
lbx = uilistbox(fig);

Determine whether the list box allows multiple selections.

multi = lbx.Multiselect

multi =

     off

Enable multiselection.

lbx.Multiselect = 'on';

Display List Box Selection

Create a list box that performs an action when the user selects an item in the list.

Save the following code as selectlistbox.m on your MATLAB path.

This code creates an app containing a list box and a text area. The ValueChangedFcn callback updates the text area to display the list box selection.

function selectlistbox

fig = uifigure('Position',[100 100 350 275]);

% Create text area
txt = uitextarea(fig,...
    'Position',[125 90 100 22],...
    'Value','First');

% Create list box
lbox = uilistbox(fig,...
    'Position',[125 120 100 78],...
    'Items',{'First','Second','Third'},... 
    'ValueChangedFcn', @updateEditField); 

% ValueChangedFcn callback
function updateEditField(src,event) 
    txt.Value = src.Value;
end

end

Run selectlistbox and select an option from the list.

Display List Box Data

Create a list box that has a numeric value associated with each item. When the user selects an item in the list box, the edit field displays the associated numeric value.

Save the following code as dataselection.m on your MATLAB path. This code creates an app containing a list box and a numeric edit field. Each item in the list has a temperature associated with it. When the user selects an item in the list, the ValueChangedFcn callback displays the corresponding temperature in the edit field.

function dataselection
fig = uifigure('Position',[100 100 350 275]);

% Create Numeric Edit Field
ef = uieditfield(fig,'numeric',...
    'Position',[125 90 100 22]);

% Create List Box
lbox = uilistbox(fig,...
    'Items', {'Freezing', 'Warm', 'Hot', 'Boiling'},...
    'ItemsData', [0, 25, 40, 100],...
    'Position',[125 120 100 78],...
    'ValueChangedFcn', @selectionChanged);

% ValueChangedFcn callback
function selectionChanged(src,event)
    % Display list box data in edit field
    ef.Value = src.Value;
end

end

Run dataselection and select an item in the list. The numeric edit field updates to reflect the temperature associated with the selection.

Add Icons to List Box Items

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);

List Box That Allows Selection of Multiple Items

Create an app containing a list box that allows multiple items to be selected. Write the ValueChangedFcn callback to display the selected items in the text area below the list box.

Save the following code as multiselect.m on your MATLAB path.

function multiselect
fig = uifigure('Position',[100 100 350 275]);

% Create Text Area
txt = uitextarea(fig,...
    'Position',[125 80 100 50]);

% Create List Box
lbox = uilistbox(fig,...
    'Position',[125 150 100 78],...
    'Multiselect','on',...
    'ValueChangedFcn',@selectionChanged);

% ValueChangedFcn callback
function selectionChanged(src,event)
    txt.Value = src.Value;
end

end

Run multiselect and select items from the list. The text area displays your selection.

Input Arguments

parent — Parent container

Figure object (default) | Tab object | Panel object | ButtonGroup object | GridLayout object

Parent container, specified as a Figure object created using the uifigure function or one of its child containers: Tab, Panel, ButtonGroup, or GridLayout. 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

Specify optional pairs of arguments as Name1=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.

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

Example: 'Items',{'Model 1','Model 2', 'Model 3', 'Model 4'} specifies the list box options that the app user sees, from top to bottom.

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

Value — Value

element of Items | element of ItemsData | {}

Value, specified as an element of the Items array, ItemsData array, or an empty cell array. By default, Value is the first element in Items.

To specify no selection, set Value to an empty cell array.

Specifying Value as an element of Items selects the list item that matches that element. If ItemsData is not empty, then Value must be set to an element of ItemsData, and the list box will select the associated item in the list.

Items — List box items

{'Item 1','Item 2', 'Item 3', 'Item 4'} (default) | 1-by-n cell array of character vectors | string array | ...

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.

ItemsData — Data associated with each element of the Items property value

empty array ([]) (default) | 1-by-n numeric array | 1-by-n cell array

Data associated with each element of the Items property value, specified as a 1-by-n numeric array or a 1-by-n cell array. Duplicate elements are allowed.

For example, if you set the Items value to employee names, you might set the ItemsData value to corresponding employee ID numbers. The ItemsData value is not visible to the app user.

If the number of array elements in the ItemsData value and the Items value do not match, one of the following occurs:

• When the ItemsData value is empty, then all the elements of the Items value are presented to the app user.

• When the ItemsData value has more elements than the Items value, then all the elements of the Items value are presented to the app user. MATLAB ignores the extra ItemsData elements.

• When the ItemsData value is not empty, but has fewer elements than the Items value, the only elements of the Items value presented to the app user are those that have a corresponding element in the ItemsData value.

Example: {'One','Two','Three'}

Example: [10 20 30 40]

Multiselect — Multiple item selection

'off' (default) | on/off logical value

Multiple item selection, specified as 'off' or 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Set this property to 'on' to allow users to select multiple items simultaneously.

ValueChangedFcn — Value changed callback

'' (default) | function handle | cell array | character vector

Value changed callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user selects a different item in the list box. It does not execute if the Value property setting changes programmatically.

This callback function can access specific information about the user’s interaction with the list box. MATLAB passes this information in a ValueChangedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.PreviousValue returns the previous value of the list box. The ValueChangedData object is not available to callback functions specified as character vectors.

The following table lists the properties of the ValueChangedData object.

Property	Value
Value	Value of list box after app user’s most recent interaction with it
PreviousValue	Value of list box before app user’s most recent interaction with it
Source	Component that executes the callback
EventName	'ValueChanged'

For more information about writing callbacks, see Callbacks in App Designer.

Position — Location and size of list box

[100 100 100 74] (default) | [left bottom width height]

Location and size of the list box relative to the parent container, specified as the vector [left bottom width height]. This table describes each element in the vector.

Element	Description
left	Distance from the inner left edge of the parent container to the outer left edge of the list box
bottom	Distance from the inner bottom edge of the parent container to the outer bottom edge of the list box
width	Distance between the right and left outer edges of the list box
height	Distance between the top and bottom outer edges of the list box

All measurements are in pixel units.

The Position values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by decorations such as a menu bar or title.

Example: [100 100 100 200]

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

R2023a: Style list box items

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.

R2022b: Program a response to a user clicking or double-clicking the list box

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 Properties.