listdlg

Shows a dialog box with a list of strings which the user can pick. This command is only available in the GUI.

Syntax

[R, status] = listdlg('ListString', data...)

[R, status] = listdlg('ListString', data, 'ListSize', size, 'SelectionMode', mode, 'Name', caption, 'InitialValue', value, 'PromptString', prompt, 'OkString', ok, 'CancelString', cancel)

Inputs

data
Value for the key 'ListString', giving the list of strings which is displayed in the list box for selection. data can either be a string or a cell array of strings.
Type: string | cell
size (optional)
Value for the key 'ListSize', specifying the minimum size of the list box. size needs to be a two-element vector of integers.
Type: vector
mode (optional)
Value for the key 'SelectionMode' argument, specifying whether the selection type is 'single' or 'multiple'. By default, the selection is mode is 'multiple'.
Type: string
caption (optional)
Value for the key 'Name' argument, specifying the caption of the list box.
Type: string
value (optional)
Value for the key 'InitialValue' argument, specifying the entries in the list box which are preselected. The value is a one-based vector of indicies corresponding to the selected entries in data. By default, the first entry is selected.
Type: vector
prompt (optional)
Value for the key 'PromptString' argument, specifying the label(s) to be displayed above the list box. prompt can be a string or a cell array of strings.
Type: string | cell
ok (optional)
Value for the key 'OkString' argument, specifying the caption of the 'OK' button, which accepts your selection in the dialog box. The default caption for the button is 'OK'.
Type: string
cancel (optional)
Value for the key 'CancelString' argument, specifying the caption of the 'Cancel' button, which discards your selection in the dialog box. The default caption for the button is 'Cancel'.
Type: string

Outputs

R
The result is a matrix of one-based indicies of the selected entries from the dialog box.
Type: integer | mat
status
status specifies how the list dialog is dismissed. The value is 1 if the OK button is clicked and 0 if the dialog box is dismissed by clicking on the Cancel button.
Type: integer

Examples

List dialog dismissed by clicking the OK button:
[R, status] = listdlg('ListString', {'String1', 'String2', 'String3'})
R = [Matrix] 1 x 2
2  3
status = 1
List dialog with caption, preselected values, prompt, and custom strings for OK/Cancel buttons:
[R, status] = listdlg('ListString', {'Name', 'Address', 'Other'}, 'Name', 'Field Value',
              'InitialValue', [1, 2], 'PromptString', 'Values:', 'OkString', 'Select',
              'CancelString', 'Clear')
R = 1
status = 1
List dialog with single selection mode and using the Cancel button to dismiss the dialog:
[R, status] = listdlg('ListString', {'Name', 'Address'}, 'SelectionMode', 'single')
R = [Matrix] 0 x 0
status = 0