DropDown - Drop-down UI component - MATLAB (original) (raw)

Description

A drop-down UI component allows an app user to select an option or type in text. Use the DropDown object to modify the appearance and behavior of a drop-down list after you create it.

Creation

Create a drop-down list in an app using the uidropdown function.

Properties

expand all

Drop-Down

Index of the component value in the list of items or item data, specified as a positive integer.

In most cases, you can use the Value property to query and update the component value. However, the ValueIndex property can be useful when both the Items and ItemsData properties are nonempty. In this case, you can use the ValueIndex property to query the element of Items that corresponds to the current value.

fig = uifigure; dd = uidropdown(fig, ... "Items",["Red","Green","Blue"], ... "ItemsData",["#F00","#0F0","#00F"]); idx = dd.ValueIndex;

disp(dd.Items(idx) + ": " + dd.Value)

When the Editable property of the drop-down component is set to 'on', you can additionally specifyValueIndex as an empty array ([]). MATLAB sets the ValueIndex property to an empty array when an app user types a value into the component that does not correspond to an item inItems. If you set ValueIndex to an empty array, MATLAB sets the Value property to''.

Placeholder text, specified as a character vector or string scalar. The placeholder provides a short description of the drop-down items. The placeholder text appears only when the drop-down component displays ''. There are two situations where this happens:

• The Value property is set to''.
• The Value property is set to an element ofItemsData whose corresponding item is''.

For example, to display a placeholder in a drop-down component with noItemsData, add '' to Items and set the Value property to '':

fig = uifigure('Position',[100 100 300 200]); dd = uidropdown(fig,'Items',{'','One','Two'}, ... 'Value','', ... 'Placeholder','Options');

Font and Color

Font angle, specified as 'normal' or 'italic'. Not all fonts have an italic font angle. For fonts that do not, specifying'italic' results in the normal font angle.

Background color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].
• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes"#FF8800", "#ff8800","#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default_Before R2025a: Most plots use these colors by default._
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem"); H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

This property is read-only.

Configuration of added styles created using the uistyle function, returned as an n-by-3 table array. Each row of the table array corresponds to a style that is currently applied to the drop-down component. Styles that are added consecutively are given a style order number ofn+1. The Target andTargetIndex columns specify the part of the component that the style was added to. The Style column specifies the style class name.

Use this property if you want to remove a style from the drop-down component using the removeStyle function.

Example: Remove a Style

First, add two styles to a drop-down component.

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

s1 = uistyle("FontColor","blue"); s2 = uistyle("FontColor","red");

addStyle(dd,s1,"item",1); addStyle(dd,s2,"item",[2 3 4]);

When you query dd.StyleConfigurations, MATLAB returns a 2-by-3 table array. The blue font style was added to the component first, so it is style order number 1. TheTargetIndex value for the level style,{[1]}, indicates that the style was applied to the first item in the component. Similarly, the second style was added to the last three items in the component

ans =

2×3 table

     Target    TargetIndex              Style          
     ______    ___________    _________________________

1     item      {[    1]}     1×1 matlab.ui.style.Style
2     item      {[2 3 4]}     1×1 matlab.ui.style.Style

Remove the second style that was added to the drop-down component by specifying style order number 2. The component appearance updates to use only the first style.

Interactivity

Tooltip, specified as a character vector, cell array of character vectors, string array, or 1-D categorical array. Use this property to display a message when the user hovers the pointer over the component at run time. The tooltip displays even when the component is disabled. To display multiple lines of text, specify a cell array of character vectors or a string array. Each element in the array becomes a separate line of text. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

Context menu, specified as a ContextMenu object created using the uicontextmenu function. Use this property to display a context menu when you right-click on a component.

Position

Inner location and size of the drop-down component, specified as [left bottom width height]. Position values are relative to the parent container. All measurements are in pixel units. This property value is identical toPosition for drop-down components.

This property is read-only.

Outer location and size of drop-down component returned as [left bottom width height]. Position values are relative to the parent container. All measurements are in pixel units. This property value is identical toPosition for drop-down components.

Layout options, specified as aGridLayoutOptions object. This property specifies options for components that are children of grid layout containers. If the component is not a child of a grid layout container (for example, it is a child of a figure or panel), then this property is empty and has no effect. However, if the component is a child of a grid layout container, you can place the component in the desired row and column of the grid by setting the Row and Column properties on the GridLayoutOptions object.

For example, this code places a drop-down in the third row and second column of its parent grid.

g = uigridlayout([4 3]); dd = uidropdown(g); dd.Layout.Row = 3; dd.Layout.Column = 2;

To make the drop-down span multiple rows or columns, specify theRow or Column property as a two-element vector. For example, this drop-down spans columns 2 through3:

dd.Layout.Column = [2 3];

Callbacks

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.

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

Clicked 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 clicks anywhere in the drop-down component.

This callback function can access specific information about the user’s interaction with the drop-down component. MATLAB passes this information in a ClickedData 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.InteractionInformation returns information about where the user clicked in the drop-down component. The ClickedData object is not available to callback functions specified as character vectors.

This table lists the properties of the ClickedData object.

This table lists the properties of the InteractionInformation object associated with the drop-down component.

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

Example: Display Data When Drop-Down Component Is Clicked

Create a drop-down component with items that represent groceries and item data that represents their cost. Specify a ClickedFcn callback function named displayCost that executes when a user clicks the component. In the displayCost function:

• Use the event.InteractionInformation object to access information about whether the user clicked an item.
• If the user did click an item (as opposed to a location in the drop-down component that is not associated with an item), query the item and its cost.
• Display the item and its cost in the Command Window.

To try this example, save the code in a new script and run it. Click an item in the drop-down component to display its cost.

fig = uifigure; dd = uidropdown(fig); dd.Items = ["Apple","Banana","Orange"]; dd.ItemsData = [1.2,0.5,1.2]; dd.ClickedFcn = @displayCost;

function displayCost(dd,event) idx = event.InteractionInformation.Item; if ~isempty(idx) fruit = dd.Items(idx); cost = dd.ItemsData(idx); disp(fruit + " cost $" + cost) end end

Callback Execution Control

This property is read-only.

Parent/Child

Parent container, specified as a Figure object or one of its child containers: Tab, Panel, ButtonGroup, orGridLayout. If no container is specified, MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.

Identifiers

This property is read-only.

Type of graphics object, returned as 'uidropdown'.

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

Object Functions

Examples

collapse all

Create a drop-down component in a UI figure and specify the items.

fig = uifigure; dd = uidropdown(fig,"Items",["Red","Yellow","Blue","Green"]);

Determine the value associated with the selected item. When theItemsData property is empty (the default), the drop-down component Value property stores the name of the selected item as it appears in the Items property.

Associate a hexadecimal color code with each drop-down component item by specifying the ItemsData property.

dd.ItemsData = ["#F00" "#FF0" "#00F" "#0F0"];

When ItemsData is nonempty, the drop-down componentValue property stores the data associated with the selected item.

Since R2023a

Create a drop-down UI component with three items.

fig = uifigure; dd = uidropdown(fig,"Items",["Good","Fair","Poor"]);

Create three background color styles.

s1 = uistyle("BackgroundColor","#77AC30"); s2 = uistyle("BackgroundColor","#EDB120"); s3 = uistyle("BackgroundColor","#F77A8F");

Add the styles to the drop-down component items to change their background colors.

addStyle(dd,s1,"item",1); addStyle(dd,s2,"item",2); addStyle(dd,s3,"item",3);

The item background colors update, and the appearance of the component reflects the style of the selected item. The style does not change the color that displays when a user points to an item.

Create an app that changes the color of a plotted line when an app user makes a selection from a drop-down list.

In a file named plotOptions.m, write a function that implements the app:

• Create a UI figure and a grid layout manager to lay out the app.
• Create UI axes and a drop-down component in the grid layout manager.
• Write a callback function named updatePlot that changes the plot color based on the selected drop-down component item, and assign the function to the ValueChangedFcn callback property. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.

function plotOptions fig = uifigure; g = uigridlayout(fig); g.RowHeight = {'1x','fit','1x'}; g.ColumnWidth = {'1x','fit'};

ax = uiaxes(g); ax.Layout.Row = [1 3]; ax.Layout.Column = 1;

x = linspace(-2pi,2pi); y = sin(x); p = plot(ax,x,y,"Color","#F00");

dd = uidropdown(g, ... "Items",["Red","Yellow","Blue","Green"], ... "ItemsData",["#F00" "#FF0" "#00F" "#0F0"], ... "ValueChangedFcn",@(src,event) updatePlot(src,p)); dd.Layout.Row = 2; dd.Layout.Column = 2; end

function updatePlot(src,p) val = src.Value; p.Color = val; end

Run the plotOptions function. Select an item from the drop-down list to change the plot color.

Create an app that allows a user to choose an image to display. Because the app contains an editable drop-down component, write your code to handle users selecting an existing item and users entering their own value.

In a file named imageApp.m, write a function that implements the app:

• Create a UI figure and a grid layout manager to lay out the app.
• Create an editable drop-down component and an image component in the grid layout manager.
• Write a callback function named updateImage that changes the image based on the selected drop-down component item, and assign the function to the ValueChangedFcn callback property. Query the callback event data to check if the new value was selected from the existing items or was entered by the user, and validate any user-entered value. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.

function imageApp fig = uifigure; g = uigridlayout(fig,[2 3]); g.RowHeight = {22,'1x'}; g.ColumnWidth = {'1x','fit','1x'};

dd = uidropdown(g, ... "Editable","on", ... "Items",["peppers.png","street1.jpg"]); dd.Layout.Row = 1; dd.Layout.Column = 2;

im = uiimage(g,"ImageSource","peppers.png"); im.Layout.Row = 2; im.Layout.Column = [1 3];

dd.ValueChangedFcn = @(src,event)updateImage(src,event,im,fig); end

function updateImage(src,event,im,fig) val = src.Value; if event.Edited && ~exist(val,"file") im.ImageSource = ""; uialert(fig,"Enter a file on the MATLAB path","Invalid Image") else im.ImageSource = val; end end

Run the imageApp function and update the image by selecting an existing item or by entering your own image path.

Version History

Introduced in R2016a

expand all

The default FontColor property value in the light theme has changed slightly. Starting in R2025a, the default value is [0.1294 0.1294 0.1294]. Previously, the default value was [0 0 0].

Access the index of the component value in the list of items by using theValueIndex property.

Create styles for drop-down components using the uistyle function, and add the styles to individual items or entire drop-down components using theaddStyle function.

Use the ClickedFcn callback property to program a response to a user clicking the drop-down component.

Provide a short hint that describes the expected drop-down component input by using thePlaceholder property.