Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

uilistbox

(App Designer) Create list box component

Use only with App Designer or figures created with the uifigure function. When using GUIDE or the figure function, create a list box using uicontrol.

Syntax

lb = uilistbox
lb = uilistbox(parent)
lb = uilistbox(___,Name,Value)

Description

lb = uilistbox creates a list box in a new UI figure window and returns a ListBox object.

example

lb = uilistbox(parent) creates the list box in the specified parent container. The parent container can be a Figure created using the uifigure function, or one of its child containers: Tab, Panel, or ButtonGroup.

example

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

Input Arguments

collapse all

Parent object, specified as a Figure created using the uifigure function, or one of its child containers: Tab, Panel, or ButtonGroup.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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.

collapse all

List box selection, specified as an element from the Items property, an element from the ItemsData property, or an empty cell array. The default list box selection is the first element of the Items array.

Specify an element from the Items property to list items that are not associated with any data. Specify an element from the ItemsData property when your list items have specific data associated with them. To specify no selection, set the Value property to an empty cell array.

When the app is running, and user selects an item in the list box, the Value property changes. The new value depends on whether the ItemsData property is empty:

  • If ItemsData is empty, then the new value is the selected element in the Items property.

  • If ItemsData is not empty, then the new value is the corresponding element from the ItemsData property.

You can allow your users to select multiple list items by setting the Multiselect property to 'on'. When the user selects multiple items, the Value property contains multiple values.

Programmatic Changes When ItemsData Is Empty

Suppose all of the following are true:

  • The Items property value is {'Red','Blue','Green'}.

  • The ItemsData value is empty.

  • The app user has the second element, Blue, selected in the list box.

If the Items value changes programmatically to {'Pink','Blue','Aqua'}, then the element selected before the programmatic change is an element of the updated Items value. In this case, the Value remains 'Blue' and the list box selection remains the second list box element.

If the Items value changes programmatically to {'Red','Teal','Green'}, then the list box element selected before the programmatic change is not an element of the updated Items value. In this case, the Value becomes the first element of the Items value ('Red') and the list box selection becomes the first list box element.

Programmatic Changes When ItemsData Is Not Empty

Suppose all of the following are true:

  • The Items value is {'Red','Blue','Green'}.

  • The ItemsData value is originally [10 20 30].

  • The app user has the second element, Blue, selected in the list box.

If the ItemsData property changes programmatically to [0 10 20], then the app user selection corresponds to an element of ItemsData that is the same before and after the programmatic change (20). However, 20 now corresponds to the third Items element. So the third list box element (Blue) is selected, even though the Value remains unchanged.

If the ItemsData property changes programmatically to [10 100 1000], then the app user selection corresponds to an element of ItemsData that no longer exists. In this case, the Value becomes the first element of ItemsData (10) and the first list box element (Red) is selected.

Programmatic Changes Resulting in Duplicate ItemsData Values

Suppose all of the following are true:

  • The Items value is {'Red','Blue','Green'}.

  • The ItemsData value is originally [10 20 20].

  • The app user has the first element, 'Red', selected in the list box before the programmatic change.

If the Value property changes programmatically to 20, then the list box selection becomes the first element of Items that matches that value, namely, 'Blue'.

List box options presented to the app user, specified as a 1-by-n cell array of character vectors. Duplicate elements are allowed. The list box displays as many options as there are elements in the Items property value.

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]

Multiple node selection, specified as 'off' or 'on'. Set this property to 'on' to allow users to select multiple items simultaneously.

Code to execute when list box selection changes, specified as a function handle, a cell array containing a function handle and additional arguments, or a character vector.

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.

PropertyValue
ValueValue of list box after app user’s most recent interaction with it
PreviousValueValue of list box before app user’s most recent interaction with it
SourceComponent that executes the callback
EventName'ValueChanged'

The ValueChangedFcn does not execute if the app user clicks the currently selected option, or if the Value property setting changes programmatically.

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.

ElementDescription
leftDistance from the inner left edge of the parent container to the outer left edge of the list box
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the list box
widthDistance between the right and left outer edges of the list box
heightDistance 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]

Examples

collapse all

Create a list box in a UI figure window.

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

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

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.

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.

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.

Tips

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

See Also

Functions

Properties

Introduced in R2016a

Was this topic helpful?