Documentation

This is machine translation

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

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan 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.

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

Drop-down component value, specified as an element of the Items or ItemsData cell array or the app-user-entered value. The default is the first element of the Items array.

  • If ItemsData is empty, Value is the selected element of Items.

  • If ItemsData is not empty, Value is the element in ItemsData that corresponds to the selected element of Items

The app user can type values in the drop-down component if the Editable property value is 'on'.

Programmatic Changes When ItemsData Is Empty

Suppose all of the following are true:

  • The Items property value is {'Red','Blue','Green'}.

  • The ItemsData value is empty.

  • The app user has the second element, Blue, selected from the drop-down component.

If the Items value changes programmatically to {'Pink','Blue','Aqua'}, then the element selected before the programmatic change is an element of the updated Items value. In this case, the Value remains 'Blue' and the selection remains the second drop-down component element.

If the Items value changes programmatically to {'Red','Teal','Green'}, then the drop-down component element selected before the programmatic change is not an element of the updated Items value. In this case, the Value becomes the first element of the Items value ('Red') and the selection becomes the first drop-down component element.

Programmatic Changes When ItemsData Is Not Empty

Suppose all of the following are true:

  • The Items value is {'Red','Blue','Green'}.

  • The ItemsData value is originally [10 20 30].

  • The app user has the second element, Blue, selected from the drop-down component before the programmatic change.

If the ItemsData property changes programmatically to [0 10 20], then the app user selection corresponds to an element of ItemsData that is the same before and after the programmatic change (20). However, 20 now corresponds to the third Items element. So the third drop-down component element (Blue) is selected, even though the Value remains unchanged.

If the ItemsData property changes programmatically to [10 100 1000], then the app user selection corresponds to an element of ItemsData that no longer exists. In this case, the Value becomes the first element of ItemsData (10) and the first drop-down component item (Red) is selected.

Programmatic Changes Resulting in Duplicate ItemsData Values

Suppose all of the following are true:

  • The Items value is {'Red','Blue','Green'}.

  • The ItemsData value is originally [10 20 20].

  • The app user has the first element, 'Red', selected from the drop-down component before the programmatic change.

If the Value property changes programmatically to 20, then the drop-down component selection becomes the first element of Items that matches that value, namely, 'Blue'.

Drop-down component options presented to the app user, specified as a 1-by-n cell array of character vectors. Duplicate elements are allowed. The drop-down component displays as many options as there are elements in the Items property value.

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

Code to execute when the drop-down selection changes, specified as a function handle, a cell array containing a function handle and additional arguments, or a character vector.

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'

The ValueChangedFcn callback does not execute if the app user clicks the currently selected option, or if the Value property setting changes programmatically.

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]

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

See Also

Functions

Properties

Introduced in R2016a

Was this topic helpful?