Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

uilistbox

创建列表框组件

说明

lb = uilistbox 在新图窗窗口中创建一个列表框,并返回 ListBox 对象。MATLAB® 调用 uifigure 函数来创建该图窗。

示例

lb = uilistbox(parent) 在指定的父容器中创建列表框。父容器可以是使用 uifigure 函数创建的图窗或其子容器之一。

示例

lb = uilistbox(___,Name,Value) 用一个或多个名称-值参量指定的属性创建列表框。可将此选项与上述语法中的任何输入参量组合一起使用。例如,uilistbox("Multiselect","on") 创建一个允许 App 用户选择多个项目的列表框。

示例

全部折叠

在 UI 图窗中创建列表框。

fig = uifigure;
lb = uilistbox(fig);

Figure contains an object of type uilistbox.

在 UI 图窗中创建一个列表框,并指定列表框项目。

fig = uifigure;
lb = uilistbox(fig,"Items",["Australia","France","Germany"]);

Figure contains an object of type uilistbox.

查询所选项目的值。

val = lb.Value
val = 
'Australia'

以编程方式更新列表框选择。

lb.Value = "Germany";

Figure contains an object of type uilistbox.

在 UI 图窗中创建列表框。允许 App 用户选择多个项目。

fig = uifigure;
lb = uilistbox(fig,"Multiselect","on");

通过点击时按住 Ctrl 键,在列表框中选择多个项目。

List box in a UI figure with four items: "Item 1", "Item 2", "Item 3", and "Item 4". The pointer is on "Item 4", and both "Item 2" and "Item 4" are selected.

Value 属性将所有所选项目存储为一个元胞数组。

val = lb.Value
val =

  1×2 cell array

    {'Item 2'}    {'Item 4'}

在 UI 图窗中创建一个列表框,并通过设置 Items 属性指定一个列表框中的颜色名称列表。

fig = uifigure;
lb = uilistbox(fig,"Items",["Red","Green","Blue"]);

Figure contains an object of type uilistbox.

当没有与项目相关联的数据时,列表框的 Value 属性是 Items 中的一个元素。

val = lb.Value
val = 
'Red'

通过设置 ItemsData 属性,将十六进制颜色数据与列表框项目相关联。设置 ItemsData 不会更改项目向 App 用户显示的方式。

lb.ItemsData = ["#F00","#0F0","#00F"];

Figure contains an object of type uilistbox.

ItemsData 属性非空时,列表框的 Value 属性是 ItemsData 中的一个元素。

val = lb.Value
val = 
"#F00"

指定 ItemsData 有利于更轻松地执行与所选项目相关联的操作。例如,通过将十六进制颜色值直接传递给 plot 函数,用所选颜色绘制一些数据。

plot(1:10,"Color",lb.Value)

Figure contains an axes object. The axes object contains an object of type line.

创建一个 App。当用户选择列表框项目时,该 App 会更新颜色图。

在名为 colormapApp.m 的文件中,编写实现该 App 的函数:

  • 创建一个 UI 图窗和一个网格布局管理器,以对该 App 进行布局。

  • 在网格布局管理器中用一些绘制的数据创建一个列表框和 UI 坐标区。

  • 编写一个名为 listBoxValueChanged 的回调函数来更新 UI 坐标区的颜色图,并将该函数赋给列表框的 ValueChangedFcn 回调属性。有关回调的详细信息,请参阅Create Callbacks for Apps Created Programmatically

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

lb = uilistbox(g, ...
    "Items",["Spring","Summer","Autumn","Winter"], ...
    "ItemsData",{spring,summer,autumn,winter});
lb.Layout.Row = 2;
lb.Layout.Column = 1;
ax = uiaxes(g);
ax.Layout.Row = [1 3];
ax.Layout.Column = 2;
surf(ax,peaks)
colormap(ax,spring)

lb.ValueChangedFcn = @(src,event) listBoxValueChanged(src,event,ax);
end

function listBoxValueChanged(src,event,ax)
cmap = event.Value;
colormap(ax,cmap)
end

运行 colormapApp 函数。在列表框中选择一个项目以更改颜色图。

colormapApp

Figure contains an axes object and an object of type uigridlayout. The axes object contains an object of type surface.

自 R2023a 起

创建一个列表框,其中包含三个表示不同图像的项目。

fig = uifigure;
lb = uilistbox(fig,"Items",["Peppers","Nebula","Street"]);

用对应于列表框项目的图标创建三个样式。

s1 = uistyle("Icon","peppers.png");
s2 = uistyle("Icon","ngc6543a.jpg");
s3 = uistyle("Icon","street1.jpg");

向列表框项目添加样式以显示图标。

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

List box UI component with three items. Each item has an icon to its left and text that describes the icon.

输入参数

全部折叠

父容器,指定为使用 uifigure 函数创建的 Figure 对象或其子容器之一:TabPanelButtonGroupGridLayout。如果不指定父容器,MATLAB 会调用 uifigure 函数创建新 Figure 对象充当父容器。

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN,其中 Name 是参量名称,Value 是对应的值。名称-值参量必须出现在其他参量之后,但参量对组的顺序无关紧要。

示例: uilistbox(Items=["Model 1","Model 2","Model 3"]) 指定列表框项目。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: uilistbox("Items",["Model 1","Model 2","Model 3"]) 指定列表框项目。

注意

此处所列的属性只是可用属性中的一部分。有关完整列表,请参阅 ListBox 属性

值,指定为 Items 数组或 ItemsData 数组的元素,或指定为空元胞数组。默认情况下,ValueItems 中的第一个元素。

要不指定任何选择,请将 Value 设置为空元胞数组。

Value 指定为 Items 的元素,即可选择与该元素匹配的列表项。如果 ItemsData 非空,则 Value 必须设置为 ItemsData 的元素,而列表框将选中列表中的关联项目。

列表框项目,指定为字符向量元胞数组、字符串数组或一维分类数组。允许重复的元素。列表框显示的选项与 Items 数组中的元素数量一样多。如果将此属性指定为分类数组,MATLAB 将使用数组中的值,而不是完整的类别集。

Items 属性值的每个元素关联的数据,指定为 1×n 数值数组或 1×n 元胞数组。允许重复的元素。

例如,如果您将 Items 值设置为员工姓名,则可以将 ItemsData 值设置为对应的员工 ID 号。ItemsData 值对 App 用户不可见。

如果 ItemsData 值和 Items 值中的数组元素数量不匹配,将发生以下情况之一:

  • 如果 ItemsData 值为空,则 Items 值的所有元素都呈现给 App 用户。

  • 如果 ItemsData 值中的元素数大于 Items 值,则 Items 值的所有元素都呈现给 App 用户。MATLAB 将忽略多余的 ItemsData 元素。

  • 如果 ItemsData 值非空,但元素数少于 Items 值,只将在 ItemsData 值中具有对应元素的 Items 值的元素呈现给 App 用户。

示例: {'One','Two','Three'}

示例: [10 20 30 40]

多项目选择,指定为 'off''on',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果将此属性设置为 'on',则允许用户同时选择多个项目。

更改值后执行的回调,指定为下列值之一:

  • 函数句柄。

  • 第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参量。

  • 包含有效 MATLAB 表达式的字符向量(不推荐)。MATLAB 在基础工作区计算此表达式。

当用户从列表框中选择不同的项目时,将会执行此回调函数。如果以编程方式更改 Value 属性设置,将不会执行此回调函数。

此回调函数可以访问有关用户与列表框的交互的特定信息。MATLAB 将 ValueChangedData 对象中的此信息作为第二个参量传递给回调函数。在 App 设计工具中,该参量名为 event。您可以使用圆点表示法查询对象属性。例如,event.PreviousValue 返回列表框的上一个值。ValueChangedData 对象不可用于指定为字符向量的回调函数。

下表列出了 ValueChangedData 对象的属性。

属性
Value列表框在 App 用户最近一次与它交互之后的值
PreviousValue列表框在 App 用户最近一次与它交互之前的值
Source执行回调的组件
EventName'ValueChanged'

有关编写回调的详细信息,请参阅App 设计工具中的回调

列表框相对于父容器的位置和大小,指定为向量 [left bottom width height]。此表介绍该向量中的每个元素。

元素描述
left父容器的内部左边缘与列表框的外部左边缘之间的距离
bottom父容器的内部下边缘与列表框的外部下边缘之间的距离
width列表框的左右外部边缘之间的距离
height列表框的上下外部边缘之间的距离

所有测量值都以像素为单位。

Position 值相对于父容器的可绘制区域。可绘制区域是指容器边框内的区域,不包括装饰元素(如菜单栏或标题)所占的区域。

示例: [100 100 100 200]

提示

可以使用 scroll 函数以编程方式滚动到某个列表框项目,或者滚动到列表的顶部或底部。

版本历史记录

在 R2016a 中推出

全部展开