Main Content

本页的翻译已过时。点击此处可查看最新英文版本。

uilistbox

创建列表框组件

说明

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

示例

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

示例

lb = uilistbox(___,Name,Value) 使用一个或多个 Name,Value 对组参数指定 ListBox 属性。可以将此选项与前面语法中的任何输入参数组合一起使用。

示例

全部折叠

在图窗窗口中创建一个列表框。

fig = uifigure('Position', [100 100 300 250]);
lbx = uilistbox(fig);

创建一个列表框。

fig = uifigure;
lbx = uilistbox(fig);

确定列表框是否允许多选。

multi = lbx.Multiselect
multi =

     off

允许多选。

lbx.Multiselect = 'on';

创建一个列表框,以便在用户选择列表中的某个项目时执行相应操作。

将以下代码以 selectlistbox.m 文件保存到 MATLAB 路径上。

此代码将创建一个 App,其中包含一个列表框和一个文本区域。ValueChangedFcn 回调将更新文本区域以显示列表框选项。

function selectlistbox

fig = uifigure('Position',[100 100 350 275]);

% Create text area
txt = uitextarea(fig,...
    'Position',[125 90 100 22],...
    'Value','First');

% Create list box
lbox = uilistbox(fig,...
    'Position',[125 120 100 78],...
    'Items',{'First','Second','Third'},... 
    'ValueChangedFcn', @updateEditField); 

% ValueChangedFcn callback
function updateEditField(src,event) 
    txt.Value = src.Value;
end

end

运行 selectlistbox 并从列表中选择一个选项。

创建一个列表框,其中的每个项目都有关联的数值。当用户选择列表框中的项目时,编辑字段将显示关联的数值。

将以下代码以 dataselection.m 文件保存到 MATLAB 路径上。此代码将创建一个 App,其中包含一个列表框和一个数值编辑字段。列表中的每一项都有与其关联的温度。当用户选择列表中的项目时,ValueChangedFcn 回调将在编辑字段中显示相应的温度。

function dataselection
fig = uifigure('Position',[100 100 350 275]);

% Create Numeric Edit Field
ef = uieditfield(fig,'numeric',...
    'Position',[125 90 100 22]);

% Create List Box
lbox = uilistbox(fig,...
    'Items', {'Freezing', 'Warm', 'Hot', 'Boiling'},...
    'ItemsData', [0, 25, 40, 100],...
    'Position',[125 120 100 78],...
    'ValueChangedFcn', @selectionChanged);

% ValueChangedFcn callback
function selectionChanged(src,event)
    % Display list box data in edit field
    ef.Value = src.Value;
end

end

运行 dataselection 并选择列表中的项目。数值编辑字段将更新以反映与所选项相关联的温度。

创建一个 App,其中包含一个列表框,允许选择多个项目。编写 ValueChangedFcn 回调以便在列表框下方的文本区域中显示所选项。

将以下代码以 multiselect.m 文件保存到 MATLAB 路径上。

function multiselect
fig = uifigure('Position',[100 100 350 275]);

% Create Text Area
txt = uitextarea(fig,...
    'Position',[125 80 100 50]);

% Create List Box
lbox = uilistbox(fig,...
    'Position',[125 150 100 78],...
    'Multiselect','on',...
    'ValueChangedFcn',@selectionChanged);

% ValueChangedFcn callback
function selectionChanged(src,event)
    txt.Value = src.Value;
end

end

运行 multiselect,然后从列表中选择项目。文本区域显示您选择的内容。

输入参数

全部折叠

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

名称-值对组参数

指定可选的、以逗号分隔的 Name,Value 对组参数。Name 为参数名称,Value 为对应的值。Name 必须放在引号中。您可采用任意顺序指定多个名称-值对组参数,如 Name1,Value1,...,NameN,ValueN 所示。

示例: 'Items',{'Model 1','Model 2', 'Model 3', 'Model 4'} 从上到下指定 App 用户可以看到的列表框选项。

此处所列的属性只是可用属性中的一部分。有关完整列表,请参阅 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 中推出