Main Content

uidropdown

Create drop-down component

collapse all in page

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.

example

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.

example

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

collapse all

Create a drop-down component with the default items.

fig = uifigure;
dd = uidropdown(fig);

UI figure window with a drop-down component. The drop-down has four options, labeled Option 1 through Option 4.

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

Create a drop-down component and specify the options.

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

UI figure with a drop-down component. The value of the drop-down is 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.

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

UI figure window with an editable drop-down component with value Option 1. The drop-down has a cursor at the end of the text.

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

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.

UI figure window with a plot and a drop-down. The plot contains some data with a green line color, and the selected drop-down option is Green.

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

UI figure window with an editable drop-down above a large lamp. The value in the drop-down is 6.

Input Arguments

collapse all

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',{'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, 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.

When Editable is set to 'on', you can additionally specify Value as a character vector or string scalar.

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

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

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.

PropertyValue
ValueDrop-down component value after app user’s most recent interaction with it.
PreviousValueDrop-down component value before app user’s most recent interaction with it.
Edited

Logical value that indicates whether the callback was executed as a result of typing a new value into the drop-down component.

  • 0 (false) — The app user selected or typed an element of the Items property of the drop-down component.

  • 1 (true) — The app user typed a value that is not an element of the Items property of the drop-down component.

SourceComponent that executes the callback.
EventName'ValueChanged'

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

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

This callback function can access specific information about the user’s interaction with the drop-down. MATLAB passes this information in a DropDownOpeningData 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.Source returns the DropDown object that the user interacts with to trigger the callback. The DropDownOpeningData object is not available to callback functions specified as character vectors.

The following table lists the properties of the DropDownOpeningData object.

PropertyValue
SourceComponent that executes the callback
EventName'DropDownOpening'

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

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.

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

Version History

Introduced in R2016a

expand all

See Also

Functions

Properties