uidropdown

Create drop-down component

Syntax

dd = uidropdown

dd = uidropdown(parent)

dd = uidropdown(___,Name,Value)

Description

dd = uidropdown creates a drop-down in a new figure window and returns the DropDown object. MATLAB^® calls the uifigure function to create the figure.

dd = uidropdown(parent) creates the drop-down in the specified parent container. The parent can be a Figure created using the uifigure function, or one of its child containers.

dd = uidropdown(___,Name,Value) specifies object properties using one or more Name,Value pair arguments. Use this option with any of the input argument combinations in the previous syntaxes. Use the Name,Value pair, Editable,'on' to specify a drop-down component that allows the app user to type text into the drop-down component or select a predefined option.

Examples

Create Drop-Down Component

Create a drop-down component with the default items.

fig = uifigure;
dd = uidropdown(fig);

Clicking anywhere in the drop-down component causes it to open.

Set and Access Drop Down Properties

Create a drop-down component and specify the options.

fig = uifigure;
dd = uidropdown(fig,'Items',{'Red','Yellow','Blue','Green'},...
                     'Value','Blue');

Determine the value associated with the selected option.

value = dd.Value

value =

    'Blue'

By default, the ItemsData property is empty, so the drop-down component value corresponds to the element selected in the drop-down component.

Associate data values with each drop-down component item.

dd.ItemsData = [1 2 3 4];

Determine the value associated with the selected option.

value = dd.Value

value =

3

Notice that when the ItemsData property value is not empty, the value of the drop-down component is the ItemsData value that corresponds to the selected Items value element.

Create an Editable Drop Down

fig = uifigure;
dd = uidropdown(fig,'Editable','on');

Clicking anywhere in the drop-down component, other than the down-arrow, inserts a caret, enabling the user to type text in the drop-down component.

Code Response to Drop Down Selection

Create a plot and a drop-down component. When the app user makes a selection from the drop-down component, the plot changes color.

Save the following code to plotOptions.m on your MATLAB path. This code creates a window containing a plot and a drop-down component. When an app user changes the drop-down component selection, the ValueChangedFcn callback changes the plot color.

function plotOptions
fig = uifigure; 
fig.Position(3:4) = [440 320];

ax = uiaxes('Parent',fig,...
    'Position',[10 10 300 300]);

x = linspace(-2*pi,2*pi);
y = sin(x);
p = plot(ax,x,y);
p.Color = 'Blue';

dd = uidropdown(fig,...
    'Position',[320 160 100 22],...
    'Items',{'Red','Yellow','Blue','Green'},...
    'Value','Blue',...
    'ValueChangedFcn',@(dd,event) selection(dd,p));
end

% Create ValueChangedFcn callback:
function selection(dd,p)
val = dd.Value;
p.Color = val;
end

Run plotOptions. Select green from the drop-down component to change the plot color to green.

Code Response to Drop-Down Component Entry or Selection

Create a drop-down component and a lamp. When the app user makes a selection from the drop-down component, the lamp size changes.

Save the following code to a lampSize.m on your MATLAB path. This code creates a figure window containing a drop-down component and a lamp. When an app user changes the drop-down component selection, the ValueChangedFcn callback changes the size of the lamp.

function lampSize
% Create figure and components

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

lmp = uilamp(fig,...
    'Position',[100 30 20 20]);

dd = uidropdown(fig,...
    'Editable','on',...
    'Position',[84 204 100 20],...
    'Items',{'Size x 1','Size x 2','Size x 3','Size x 4'},...
    'ItemsData',[1 2 3 4],...
    'Value',1,...
    'ValueChangedFcn',@(dd,event) optionSelected(dd,lmp));
end

% Create ValueChangedFcn callback
function optionSelected(dd,lmp)
val = dd.Value;
s = [20 20];
switch val
    case {1, 2, 3, 4}  % User selected a defined option
        size = val * s;
        lmp.Position(3:4) = size;
    otherwise % User typed a value
        m = str2num(val);
        size = m * s;
        lmp.Position(3:4) = size;
end
end

Run lampSize and select various options from the drop-down component.

Type a value in the drop-down component and press Enter. The lamp size changes. (If you type a large value, you might have to resize the figure to see the lamp.)

Input Arguments

parent — Parent container

Figure object (default) | Panel object | Tab 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 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 quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Items',{'Red','Yellow','Blue'} specifies the options presented in the drop-down component.

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

'Value' — Value

element of Items | element of ItemsData

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

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

'Items' — Drop-down items

{'Option 1','Option 2','Option 3','Option 4'} (default) | cell array of character vectors | string array | ...

Drop-down items, specified as a cell array of character vectors, string array, or 1-D categorical array. Duplicate elements are allowed. The drop-down component 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.

Example: {'Red','Yellow','Blue'}

Example: {'1','2','3'}

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

'Editable' — Editable state of drop-down component

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

Editable state of the drop-down component, 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.

If the Enable property value is 'off', then the app user cannot change the drop-down component text, even if the Editable property value is 'on'.

'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 option from the drop-down list. It does not execute if the Value property changes programmatically.

This callback function can access specific information about the user’s interaction with the drop-down. 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 drop-down. 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	Drop-down component value after app user’s most recent interaction with it.
PreviousValue	Drop-down component value before app user’s most recent interaction with it.
Edited	Logical value (0 or 1) that indicates whether the callback was executed as a result of typing a value into the drop-down component. The Edited value is 1 when the app user typed in the drop-down component and 0 when the app user selected an option from the drop-down component.
Source	Component that executes the callback.
EventName	'ValueChanged'

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

'DropDownOpeningFcn' — Drop-down menu opening callback function

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

Drop-down menu opening callback function, 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 property specifies a callback function to execute when the user clicks open the drop-down menu. A possible use for this callback is to update the dynamic list of entries in the menu list.

For more information about specifying a callback as a function handle, cell array, or character vector, see Write Callbacks in App Designer.

'Position' — Location and size of drop-down component

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

Location and size of the drop-down component relative to the parent, 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 drop-down component
bottom	Distance from the inner bottom edge of the parent container to the outer bottom edge of the drop-down component
width	Distance between the right and left outer edges of the drop-down component
height	Distance between the top and bottom outer edges of the drop-down component

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 22]