Main Content

uispinner

创建微调器组件

全页折叠

语法

spn = uispinner
spn = uispinner(parent)
spn = uispinner(___,Name,Value)

说明

spn = uispinner 在新图窗窗口中创建一个微调器，并返回 Spinner 对象。MATLAB® 调用 uifigure 函数来创建该图窗。

spn = uispinner(parent) 在指定的父容器中创建微调器。父容器可以是使用 uifigure 函数创建的 Figure 或其子容器之一。

示例

spn = uispinner(___,Name,Value) 使用一个或多个 Name,Value 对组参量指定 Spinner 属性。可将此选项与上述语法中的任何输入参量组合一起使用。

示例

示例

全部折叠

fig = uifigure;
spn = uispinner(fig);

Spinner in a UI figure window. The spinner has a value of 0 and buttons to increment and decrement the value.

在面板中创建微调器。

fig = uifigure;
pnl = uipanel(fig);
spn = uispinner(pnl);

Spinner in a panel in a UI figure window

创建一个微调器，限制 App 用户只能输入 0 到 100（含 0 和 100）之间的值。

创建一个微调器。

fig = uifigure;
spn = uispinner(fig);

确定范围。返回的值表明上限和下限不受限制。

limits = spn.Limits
limits =

  -Inf   Inf

将范围设置为 0 到 100。

spn.Limits = [0 100];

创建一个微调器，允许 App 用户输入大于 -5 且小于或等于 10 的值。

fig = uifigure;
spn = uispinner(fig,'Limits', [-5  10],...
            'LowerLimitInclusive','off',...
            'UpperLimitInclusive','on',...
            'Value', 5);

运行代码。如果您在微调器中输入的值超出该范围，MATLAB 将自动显示一条消息，指出存在的问题。MATLAB 然后会将值还原为上一个有效值。

创建一个微调器，允许 App 用户输入任意值，但始终只显示两位小数。请注意，MATLAB 会存储 App 用户输入的确切值。

fig = uifigure;
spn = uispinner(fig,'ValueDisplayFormat', '%.2f');

运行代码，然后在微调器中输入 5.555。在微调器外点击。微调器显示 5.55。

MATLAB 存储的原始值为 5.555。

在微调器中点击，将显示最初键入的值。

创建一个微调器和一个滑块控件。当 App 用户更改微调器值时，滑块将更新以匹配该值。

请将以下代码保存到 MATLAB 路径中的 spinnerValue.m 中。以下代码将创建一个图窗窗口，其中包含一个滑块控件和一个微调器。当 App 用户更改微调器值时，ValueChangedFcn 将更新微调器，以反映滑块值。

function spinnervalue
fig = uifigure('Position',[100 100 370 280]);

sld = uislider(fig,...
    'Position',[90 220 120 3]);

spn = uispinner(fig,...
    'Position',[100 140 100 22],...
    'Limits',sld.Limits,...
    'ValueChangedFcn',@(spn,event) updateSlider(spn,sld));
end

% Create ValueChangedFcn callback
function updateSlider(spn,sld)
sld.Value = spn.Value;
end

运行 spinnerValue。

点击并按住微调器中的向上箭头，当值达到 24 时释放鼠标按键。滑块将移动，以指示微调器值。

UI figure window with a slider and a spinner. Both the slider and the spinner have values of 24.

创建一个微调器和一个滑块控件。当 App 用户更改微调器值时，滑块将不断更新以匹配该值。

请将以下代码保存到 MATLAB 路径中的 showChangingValue.m 中。以下代码将创建一个图窗窗口，其中包含一个滑块控件和一个微调器。当 App 用户更改微调器值时，ValueChangingFcn 将不断更新滑块，以反映不断变化的微调器值。

function showChangingValue
fig = uifigure('Position',[100 100 370 280]);
sld = uislider(fig,...
    'Position',[90 220 120 3]);

spn = uispinner(fig,...
    'Position',[100 140 100 22],...
    'Limits',sld.Limits,...
    'ValueChangingFcn',@(spn,event) spinnerChanging(event,sld));
end

% Create ValueChangingFcn callback
function spinnerChanging(event,sld)
sld.Value = event.Value;
end

运行 showChangingValue。

点击并按住微调器中的向上箭头，当值达到 24 时释放鼠标按键。滑块将随着微调器值的变化而移动。

UI figure window with a slider and a spinner. Both the slider and the spinner have values of 24.

编写 ValueChangedFcn 回调，以确定值相对于上一个微调器值是增加还是减少。将信号灯的颜色设置为值增加时显示绿色，值减少时显示红色。

请将以下代码保存到 MATLAB 路径中的 upOrDown.m 中。

function upOrDown
fig = uifigure(...
    'Position',[100 100 190 170]);

lmp = uilamp(fig,...
    'Position',[90 50 20 20],...
    'Color','green');

spn = uispinner(fig,...
    'Position',[50 100 100 22],...
    'ValueChangedFcn',@(spn,event) spinnerValueChanged(event,lmp));
end

% Create ValueChangedFcn that uses event data
function spinnerValueChanged(event,lmp)
newValue = event.Value;
previousValue = event.PreviousValue;
difference = newValue-previousValue;
if difference > 0
    lmp.Color = 'green';
else
    lmp.Color = 'red';
end
end

运行 upOrDown。

当您每次更改微调器值时，ValueChangedFcn 都会确定值是增加还是减少，并相应地设置信号灯的颜色。

UI figure window with a spinner and a lamp. The value of the spinner is 8, and the lamp is red.

输入参数

全部折叠

父容器，指定为使用 uifigure 函数创建的 Figure 对象或其子容器之一：Tab、Panel、ButtonGroup 或 GridLayout。如果不指定父容器，MATLAB 会调用 uifigure 函数创建新 Figure 对象充当父容器。

名称-值参数

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

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

示例: 'Value',150 指定在微调器中显示数字 50。

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

微调器值，指定为数值。

当 App 用户键入或更改微调器中的值时，值为字符向量。当 App 用户按下 Enter 键或者更改焦点时，MATLAB 会将 App 用户输入的值转换为双精度数字。

如果出现以下情况，MATLAB 将拒绝该值：

  • 它无法将字符向量转换为数值标量。

  • 值是 NaN、空白或复数。

  • 值是数学表达式，如 1+2。

  • 值小于或大于 Limits 属性指定的值。

如果 MATLAB 拒绝 App 用户输入的值，将会显示一个工具提示，说明对值的要求。微调器立即还原为以前的值，而且不会运行 ValueChangedFcn。

示例: 10

数据类型: double

值的显示格式，指定为字符向量或字符串标量。

MATLAB 使用 sprintf 以指定的格式显示值。

您可以混合使用文本和格式化操作符。例如：

spin = uispinner('ValueDisplayFormat','%.0f MS/s');

生成的微调器组件如下所示：

Spinner with text "0 MS/s"

当 App 用户点击微调器字段时，字段将显示不带文本的值。

Spinner with text "0"

有关支持的格式化操作符的完整列表，请参阅 sprintf。

由 App 用户输入的小数值的舍入方法，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 如果生成无效值，MATLAB 将对值进行舍入并执行 ValueChangedFcn 回调。如果生成的值超出 Limits 的下限或上限，MATLAB 将把值舍入到 Limits 之内的最接近值，然后执行回调。

  • 'off' - MATLAB 不会将小数值舍入为整数。

如果以编程方式将 RoundFractionalValues 属性值从 'off' 更改为 'on'，MATLAB 将按照下列规则执行操作：

  • 如果舍入现有值之后得到的整数位于 Limits 属性指定的范围内，MATLAB 将对现有值进行向上舍入。

  • 如果舍入现有值之后得到的整数小于下限值，MATLAB 将对现有值进行向上舍入。

  • 如果舍入现有值之后得到的整数大于上限值，MATLAB 将对现有值进行向下舍入。

  • 如果指定的范围导致无法生成位于该范围内的有效整数，MATLAB 将把 RoundFractionalValues 属性值设置回 'off' 并显示一条错误消息。

当 App 用户按向上和向下箭头时，Value 属性相应增加或减少的数量。

微调器的最小值和最大值，指定为二元素数值数组。第一个值必须小于或等于第二个值。将数组元素设置为 -Inf 或 Inf 分别指定无最小值或无最大值。

如果您更改 Limits，使得 Value 小于新的下限值，MATLAB 将把 Value 设置为新范围内的最小值。例如，假设 Limits 为 [0 100]，Value 为 20。如果 Limits 更改为 [50 100]（包含边界值），MATLAB 将把 Value 设置为 50。

同样，如果您更改 Limits，使得 Value 大于新的上限值，MATLAB 会将 Value 设置为新的上限值（假定范围包含边界值）。

示例: [-Inf 200]

示例: [-100 Inf]

示例: [-100 200]

数据类型: double

下限值的包含性，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 值必须等于或大于下限值。

  • 'off' - 值必须大于下限值。

上限值的包含性，指定为 'on' 或 'off'，或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true，'off' 等效于 false。因此，您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 值必须等于或小于上限值。

  • 'off' - 值必须小于上限值。

例如，如果您希望数值输入介于 0 和 1 之间，不含 0 和 1，请执行以下所有操作：

  • 将 Limits 属性值设置为 [0 1]。

  • 将 UpperLimitInclusive 属性设置为 'off'。

  • 将 LowerLimitInclusive 属性设置为 'off'。

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

  • 函数句柄。

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

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

当用户更改焦点，或者在更改微调器值之后按 Enter 键时，将会执行此回调。不管用户是通过键入值还是通过按箭头键来更改微调器值，都会执行此回调。如果以编程方式更改微调器值，将不会执行此回调。

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

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

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

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

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

  • 函数句柄。

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

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

当用户点击并按住微调器上的向上或向下箭头时，将会执行此回调函数。如果以编程方式更改 Value 属性，将不会执行此回调函数。

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

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

属性值
Value微调器在 App 用户与它交互时的当前值
Source执行回调的组件
EventName'ValueChanging'

在 App 用户释放箭头键之前，Spinner 的 Value 属性不会更新。因此，要获取按下箭头键时的值，您的代码必须获取 ValueChangingData 对象的 Value 属性。

注意

请避免从其自己的 ValueChangingFcn 回调中更新 Spinner 对象的 Value 属性，因为这可能导致意外行为。要更新微调器值以响应用户输入，请改用 ValueChangedFcn 回调。

回调按照如下方式执行：

  • 如果 App 用户点击微调器中的向上或向下箭头，回调将执行一次。例如，假设微调器值为 2，Step 值为 1。如果 App 用户点击向上箭头，回调将执行一次。

  • 如果 App 用户按住微调器中的向上或向下箭头，回调将重复执行。例如，如果 App 用户点击并按住向上箭头，回调将执行多次，直到 App 用户释放向上箭头为止。

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

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

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

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

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

示例: [100 100 100 22]

版本历史记录

在 R2016a 中推出

另请参阅

函数

属性

工具