listdlg

Create list selection dialog box

Syntax

[indx,tf] = listdlg('ListString',list)

[indx,tf] = listdlg('ListString',list,Name,Value)

Description

[indx,tf] = listdlg('ListString',list) creates a modal dialog box that allows the user to select one or more items from the specified list.

The list value is the list of items to present in the dialog box.

The function returns two output arguments, indx and tf containing information about which items the user selected.

The dialog box includes Select all, Cancel, and OK buttons. You can limit selection to a single item by using the name-value pair, 'SelectionMode','single'.

[indx,tf] = listdlg('ListString',list,Name,Value) specifies additional options using one or more name-value pair arguments. For example, 'PromptString','Select a Color' presents Select a Color above the list.

Examples

Present List of Colors for Multiple Selection

list = {'Red','Yellow','Blue',...                   
'Green','Orange','Purple'};
[indx,tf] = listdlg('ListString',list);

Present Current Folder Files for Single Selection

d = dir;
fn = {d.name};
[indx,tf] = listdlg('PromptString',{'Select a file.',...
    'Only one file can be selected at a time.',''},...
    'SelectionMode','single','ListString',fn);

Input Arguments

list — list of items

character vector | cell array of character vectors | string array

List of items to present in the dialog box, specified as a character vector, cell array of character vectors, or string array. For cell arrays and string arrays, each element typically corresponds to a separate list item. If you insert newline characters using sprintf, it results in more list items. For example, the following code results in four list items, even though there are only three cell array elements.

f = listdlg('ListString', ...
            {'John Smith' ...
             sprintf('Cecelia\nPayne-Gaposchkin') ...
             'Gina Peters'});

Example: {'Ellen','Varun','Haruko','Roger'}

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: 'SelectionMode,'single','InitialValue',4 specifies that the user can select one item from the list and that when the dialog box opens, the fourth item in the list is selected.

PromptString — List box prompt

[ ] (default) | character vector | cell array of character vectors | string array

List box prompt, specified as a character vector, cell array of character vectors, or string array. The prompt appears above the list box.

If you specify the prompt as a character vector that is longer than the width of the dialog box, the prompt clips. To create a multiline list box prompt, specify the prompt as a cell array or string array. Line breaks occur between each array element. Long elements wrap to fit the dialog box.

Example: 'PromptString','Select a catalog number:'

SelectionMode — List selection mode

'multiple' (default) | 'single'

List selection mode specified as the comma-separated pair consisting of 'SelectionMode' and either 'multiple' or 'single'.

• If the selection mode is set to 'multiple', then users can select multiple list items and the Select all button displays in the dialog box.

• If the selection mode is set to 'single', then users can select one list item only and the Select all button does not display in the dialog box.

Example: 'SelectionMode','single'

ListSize — list box size

[160 300] (default) | [width height]

List box size in pixels, specified as the comma-separated pair consisting of 'ListSize' and a two-element vector, [width height].

Example: 'ListSize',[150,250]

InitialValue — Selected list box items

1 (default) | vector of indices

Selected list box items, specified as a scalar index value when 'SelectionMode' is set to 'single' and specified as a vector of indices when 'SelectionMode' is set to 'multiple'. The indices indicate which rows in the list box are selected when the dialog box opens. For example:

• If 'InitialValue' is set to 3, then the third item from the top of the list is selected when the dialog box opens.

• If 'InitialValue' is set to [3 4], then the third and fourth items from the top of the list are selected when the dialog box opens.

Example: 'InitialValue',5

Example: 'InitialValue',[2 5]

Name — Dialog box title

[ ] (default) | character vector | string scalar

Dialog box title, specified as a character vector or string scalar.

Example: 'Name','File Selection'

OKString — OK button label

'OK' (default) | character vector | string scalar

OK button label, specified as a character vector or string scalar.

Example: 'OKString','Apply'

CancelString — Cancel button label

'Cancel' (default) | character vector | string scalar

Cancel button label, specified as a character vector or string scalar.

Example: 'CancelString','No Selection'

Output Arguments

indx — Index to selected rows

array of indices

Index to selected rows, returned as an array of indices. The row indices correspond to selections the user made from the list. If the user clicks Cancel, presses Esc, or clicks the close button in the dialog box title bar, then the indx value is returned as an empty array.

tf — Selection logical

1 | 0

Selection logical returned as 1 or 0.

The selection logical value indicates whether the user made a selection. If the user clicks OK, double-clicks a list item, or presses Return, then the tf return value is 1.

If the user clicks Cancel, presses Esc, or clicks the close button (X) in the dialog box title bar, then the tf return value is 0.

More About

Modal Dialog Box

A modal dialog box prevents the user from interacting with other MATLAB^® windows before responding. For more information, see WindowStyle in Figure.

Version History

Introduced before R2006a