Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

uidropdown

(App Designer) Create drop-down component

Use only with App Designer or figures created with the uifigure function. When using GUIDE or the figure function, create a drop-down component using uicontrol.

Syntax

dd = uidropdown
dd = uidropdown(parent)
dd = uidropdown(___,Name,Value)

Description

dd = uidropdown creates a drop-down component in a new UI figure window and returns the DropDown component object.

example

dd = uidropdown(parent) creates the drop-down 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

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.

fig = uifigure;
dd = uidropdown(fig);

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

Specify the parent window for a drop-down component.

fig = uifigure('Position', [100 100 300 250]);
dd = uidropdown(fig);

Create a drop-down component and specify the options to present to the app user.

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.

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.

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
% Create UI figure and components:

fig = uifigure;

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

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

% Create drop-down component
dd = uidropdown(fig,...
    'Position',[430 210 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.

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 UI 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

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

collapse all

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.

Drop-down items, specified as a cell array of character vectors or string array. Duplicate elements are allowed. The drop-down component displays as many options as there are elements in the Items array.

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

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.
EditedLogical 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.
SourceComponent that executes the callback.
EventName'ValueChanged'

For more information about writing callbacks, see Write 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]

See Also

Functions

Properties

Introduced in R2016a

Was this topic helpful?