Main Content

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

UI Figure 属性

控制基于 uifigure 的 App 的 UI 图窗的外观和行为

UI 图窗是在 App 设计工具中或通过 uifigure 函数以编程方式创建 App 的容器。可以通过属性控制 UI 图窗的外观和行为。使用圆点表示法引用特定的对象和属性:

fig = uifigure;
fig.Name = 'My App'; 

窗口外观

全部展开

背景颜色,指定为 RGB 三元组、十六进制颜色代码或下表中列出的颜色选项之一。

对于自定义颜色,请指定 RGB 三元组或十六进制颜色代码。

  • RGB 三元组是包含三个元素的行向量,其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内,例如 [0.4 0.6 0.7]

  • 十六进制颜色代码是字符串标量或字符向量,以井号 (#) 开头,后跟三个或六个十六进制数字,范围可以是 0F。这些值不区分大小写。因此,颜色代码 "#FF8800""#ff8800""#F80""#f80" 是等效的。

此外,还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。

颜色名称短名称RGB 三元组十六进制颜色代码外观
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

"none"不适用不适用不适用无颜色

以下是 MATLAB® 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。

RGB 三元组十六进制颜色代码外观
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

窗口样式,指定为下列值之一:

  • 'normal' - 此图窗窗口独立于其他窗口,并且在显示图窗时可以访问其他窗口。

  • 'modal' - 该图窗以正常窗口样式显示在所有现有图窗窗口的上方,并使这些窗口变得无法访问(只要顶层图窗存在并保持模态)。但是,任何在模态图窗之后创建的新图窗都会显示出来。

    存在多个模态窗口时,最新创建的窗口将会保持焦点并位于所有其他窗口之上,直到变得不可见、恢复为正常窗口样式或被删除。此时,焦点会重新回到上次具有焦点的窗口。

  • 'alwaysontop' - 图窗显示在所有其他窗口的顶部,包括模态图窗窗口和来自非 MATLAB 应用程序的窗口。其他窗口仍可访问。

注意

以下是 WindowStyle 属性的一些重要特性和一些推荐的最佳做法:

  • 创建 UI 窗口时,应始终指定 WindowStyle 属性。如果还想要设置图窗的 ResizePosition 属性,先要设置 WindowStyle 属性。

  • 您可以随时更改图窗的 WindowStyle 属性,包括图窗可见并包含子图窗的情况。但是,在某些系统上,设置该属性可能会导致图窗闪烁或者消失后重新显示,具体取决于系统的正常窗口和模态窗口的实现。为实现最佳视觉效果,应在创建时或图窗不可见时设置 WindowStyle 属性。

UI 图窗模态窗口样式行为

WindowStyle 设置为 'modal' 时,UI 图窗窗口会阻止在它之前创建的 UI 图窗窗口中的键盘和鼠标交互,并将其 Visible 属性设置为 'on'。例如,在此示例中,图窗 3 相对于图窗 2 为模态图窗,图窗 2 相对于图窗 1 为模态图窗。

fig1 = uifigure('Name','Figure 1');
fig1.WindowStyle = 'modal';

fig2 = uifigure('Name','Figure 2');
fig2.WindowStyle = 'modal';

fig3 = uifigure('Name','Figure 3');
fig3.WindowStyle = 'modal';
如果图窗层次结构中有模态图窗和普通图窗的组合,则不会保留模态层次结构。

与使用 figure 函数创建的模态图窗不同,使用 uifigure 函数创建的模态图窗不会阻止用户访问用 figure 函数或 MATLAB 桌面创建的图窗。也不会阻止与 MATLAB 以外的应用程序窗口的交互。

模态图窗获得焦点时键入 Ctrl+C 会导致图窗恢复到 'normal' WindowStyle 属性设置。这样用户可以在命令行键入内容。

WindowStyle 属性设置为 'modal' 并且 Visible 属性设置为 'off' 的 UI 图窗在 MATLAB 使它们变得可见之前不会以模态方式运行。因此,您可以隐藏模态窗口供以后重用,而不用销毁它。

模态图窗不显示菜单子级、内置菜单或工具栏。但是,在模态图窗中创建菜单或在具有菜单子级的图窗上将 WindowStyle 属性设置更改为 'modal' 并不是错误。Menu 对象会存在,而且图窗会保留它们。如果您将 UI 图窗的 WindowStyle 属性重置为 'normal',则会显示菜单。

窗口状态,指定为下列值之一:

  • 'normal' - 窗口显示为正常状态。

  • 'minimized' - 窗口被折叠,但您仍可以执行命令来获取或设置其属性、添加子级或在窗口中创建绘图。

  • 'maximized' - 窗口填满屏幕。操作系统提供的最小化、还原和关闭按钮出现在窗口的角落。如果正常状态下的窗口包含菜单,则它们在此状态下也会显示。

  • 'fullscreen' - 窗口填满屏幕。但是,操作系统提供的最小化、还原和关闭按钮将被隐藏。如果正常状态下的窗口包含菜单,则它们在此状态下也会显示。

点击操作系统提供的最小化、最大化或还原按钮将对 WindowState 属性进行相应的设置。按下 Ctrl+F11(Windows® 和 Linux®)或 Ctrl+Command+F (macOS) 可切换 'fullscreen' 状态。不支持对已停靠的图窗或在 MATLAB Online™ 中设置此属性。

UI 图窗不能直接从全屏状态最小化。

位置和大小

全部展开

UI 图窗的位置和大小,不包括边框和标题栏,指定为 [left bottom width height] 形式的四元素向量。

此表介绍该向量中的每个元素。

元素描述
left从主画面左边缘到 UI 图窗窗口的内部左边缘的距离。在具有多个监视器的系统上,该值可能为负数。
bottom从主画面下边缘到 UI 图窗窗口的内部下边缘的距离。在具有多个监视器的系统上,该值可能为负数。
widthUI 图窗的左右内部边缘之间的距离。
heightUI 图窗的上下内部边缘之间的距离。

测量单位,指定为下表中的值之一。

单位值描述
'pixels'(默认值)

像素。

以像素为单位的距离不依赖 Windows 和 Macintosh 系统上的系统分辨率:

  • 在 Windows 系统上,一个像素是 1/96 英寸。

  • Macintosh 系统上,一个像素是 1/72 英寸。

在 Linux 系统上,一个像素的大小由系统分辨率确定。

'normalized'这些单位依据父容器进行归一化。容器的左下角映射到 (0,0),右上角映射到 (1,1)
'inches'英寸。
'centimeters'厘米。
'points'磅。1 磅等于 1/72 英寸。
'characters'

这些单位基于图形根对象的默认 uicontrol 字体:

  • 字符宽度 = 字母 x 的宽度。

  • 字符高度 = 两个文本行的基线之间的距离。

要访问默认的 uicontrol 字体,请使用 get(groot,'defaultuicontrolFontName')set(groot,'defaultuicontrolFontName')

MATLAB 从父对象的左下角测量所有单位。

推荐值为 'pixels',因为大多数 MATLAB App 构建功能都以像素为单位测量距离。

注意

App 设计工具仅支持像素单位。要在 App 设计工具中创建大小相对于其父容器而调整的容器,请使用网格布局管理器或创建具有自动调整布局功能的 App。有关详细信息,请参阅在 App 设计工具中管理可调整大小的 App

此属性会影响 Position 属性。如果更改 Units 属性,请考虑在完成计算后将其值还原为默认值,以免影响采用默认值的其他函数。

指定 UnitsPosition 属性的顺序具有以下影响:

  • 如果您在 Position 属性之前指定 Units,则 MATLAB 会使用您指定的单位来设置 Position

  • 如果您在 Position 属性之后指定 Units 属性,则 MATLAB 会使用默认的 Units 来设置 position。然后,MATLAB 将 Position 值转换为以您指定的单位表示的等价值。

UI 图窗的位置和大小,不包括边框和标题栏,指定为 [left bottom width height] 形式的四元素向量。所有测量值都采用 Units 属性指定的单位。

此属性值等同于 Position 属性值。

可调整大小的 UI 图窗,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

当此属性设置为 'on' 时,UI 图窗可调整大小。否则将无法调整其大小。

自动调整子组件的大小,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 当容器调整大小时,子组件会自动调整大小。

  • 'off' - 子组件不调整大小。

AutoResizeChildren 属性影响容器的直接子组件,而不影响嵌套容器内的子组件。

AutoResizeChildren'on' 时,某些子组件不会自动调整大小。例如,仅包含非调整大小组件的标签、按钮和容器不会调整大小。

要自定义调整大小行为,请向容器添加网格布局管理器,或将 AutoResizeChildren 属性设置为 'off' 并为容器创建一个 SizeChangedFcn 回调。有关详细信息,请参阅在 App 设计工具中管理可调整大小的 App

要禁用 App 的大小调整,请将图窗的 Resize 属性设置为 'off'

建议仅在以像素为单位进行布局的 App 中将 AutoResizeChildren 指定为 'on'。在不以像素为单位进行布局的 App 中启用自动调整大小可能导致意外行为。

绘图

全部展开

UIAxes 内容的颜色图,指定为由 RGB(红色、绿色、蓝色)三元组组成的 m×3 数组,这些三元组定义 m 种单独的颜色。

示例: uifigure('Colormap',[1 0 1; 0 0 1; 1 1 0]) 将颜色图设置为三种颜色:品红色、蓝色和黄色。

MATLAB 按行号访问这些颜色。

坐标区内容的透明度映射,指定为由介于 01(包含这两个边界值)之间的值组成的向量。该向量的大小可以是 m×1 或 1×m。MATLAB 通过 alpha 值在向量中的索引访问 alpha 值。Alphamap 可以为任意长度。

鼠标指针

全部展开

指针符号,指定为下表中的值之一,或指定为 'custom'。符号的外观与操作系统相关。

生成的符号(与系统相关)

'arrow'

Arrow mouse pointer symbol

'ibeam'

I-beam mouse pointer symbol

'crosshair'

Crosshair mouse pointer symbol

'watch'(系统忙)

Busy system mouse pointer symbol

'topl''botr'

Bidirectional arrow mouse pointer symbol that points to the top left and to the bottom right

'topr''botl'

Bidirectional arrow mouse pointer symbol that points to the top right and to the bottom left

'circle'

Circle mouse pointer symbol

'cross'

Cross mouse pointer symbol

'fleur'

Mouse pointer symbol with four arrows pointing up, right, down, and left

'left''right'

Bidirectional arrow mouse pointer symbol that points to the left and right

'top' 'bottom'

Bidirectional arrow mouse pointer symbol that points up and down

'hand'

Hand mouse pointer symbol

自定义指针符号

要创建自定义指针符号,请以编程方式将 Pointer 属性设置为 'custom' 并使用 PointerShapeCData 属性定义符号。有关详细信息,请参阅 PointerShapeCData 属性。

局限性

Pointer 属性指定的指针符号不会显示在使用 uihtml 函数创建的 HTML UI 组件上。

自定义指针符号,指定为 16×16 矩阵(对于 16×16 像素指针)或指定为 32×32 矩阵(对于 32×32 像素指针)。当您将 Pointer 属性设置为 'custom' 时,图窗将使用此指针符号。

矩阵中的每个元素分别为指针中的 1 个像素定义亮度级别,其中元素可以具有以下值之一:

  • 1 - 黑色像素。

  • 2 - 白色像素。

  • NaN - 透明像素,这样底层屏幕内容就能显示出来。

矩阵的元素 (1,1) 与指针左上角的像素对应。

指针的活动像素,指定为二元素向量。该向量包含 PointerShapeCData 矩阵中特定元素的行和列索引,该元素与所需的活动像素对应。默认值 [1 1] 对应于指针左上角的像素。

如果您指定的值位于 PointerShapeCData 矩阵范围外,则指针将改用默认活动像素 [1 1]

仅当 Pointer 属性设置为 'custom' 时,此属性才适用。

交互性

全部展开

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

  • 'on' - 显示对象。

  • 'off' - 隐藏对象而不删除它。您仍然可以访问不可见 UI 组件的属性。

要使您的 App 更快地启动,请将不需要在启动时出现的所有组件的 Visible 属性设置为 'off'

更改不可见的容器的大小将在该容器变得可见时触发 SizeChangedFcn 回调。

更改容器的 Visible 属性不会改变其子组件的 Visible 属性值。即使隐藏容器会导致子组件隐藏也是如此。

当前 UI 图窗中的目标坐标区,指定为 UIAxesAxesPolarAxes 对象,或图形对象,如 HeatmapChart

在存在坐标区子级的所有 UI 图窗中,始终存在当前坐标区。当前坐标区不必是最顶层的坐标区,并且将坐标区设置为当前坐标区不会将其重新叠放在所有其他坐标区上。如果 UI 图窗不包含坐标区,则 get(gcf,'CurrentAxes') 命令返回一个空数组。

查询 CurrentAxes 属性来获取当前坐标区对象,而不强制创建不存在的坐标区。

当前对象,以 UI 图窗的子对象形式返回。MATLAB 将 CurrentObject 属性设置为在 UI 图窗中点击的最后一个对象。

点击其 HandleVisibility 属性为 'off' 的对象会将 CurrentObject 属性设置为空 GraphicsPlaceholder 数组。

当前点,以二元素向量形式返回。该向量包含鼠标指针的 (x, y) 坐标,从 UI 图窗左下角开始测量。值采用 Units 属性指定的单位。如果 UI 图窗是可滚动的,则坐标从可滚动区域的左下角开始测量。可滚动区域是由滚动条限定的区域。

执行以下任一操作时坐标都会更新:

  • 在 UI 图窗中按下鼠标按键。

  • 在 UI 图窗中按下鼠标按键后释放鼠标按键。

  • 在 UI 图窗中按下鼠标按键,然后在 UI 图窗外将其释放。

  • 在 UI 图窗内旋转滚轮。

  • WindowButtonMotionFcn 属性不为空的情况下,在图窗内移动鼠标(不按任何按键)。

如果 UI 图窗具有响应鼠标交互的回调,并且您触发该回调的速度比系统执行代码的速度更快,则坐标可能不会反映指针的实际位置,而是反映回调开始执行时的位置。

如果您使用 CurrentPoint 属性绘制各点,则坐标值可能包含舍入误差。

当前字符,以按下的最后一个键的字符形式返回。当 UI 图窗具有焦点且用户按下某个键时,此属性会更新。

鼠标选择类型,返回为 'normal''extend''alt''open'。此属性提供有关 UI 图窗中发生的最后一次按下鼠标按键的信息。

下表列出了可能的 SelectionType 值以及生成这些值的用户操作。

对应的操作

'normal'

点击鼠标左键。

'extend'

以下任一操作:

  • Shift-点击鼠标左键。

  • 点击鼠标中键。

  • 同时点击鼠标左键和右键。

'alt'

下列任一操作:

  • Control-点击鼠标左键。

  • 点击鼠标右键。

'open'

双击任何鼠标按键。

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

将此属性设置为 'on' 可以在容器内滚动。但是,还有其他要求:

  • 容器中子组件占用的区域必须大于容器一次可显示的区域。

  • 在容器内无法容纳的组件必须位于容器的上方或右侧。您不能滚动到容器下方或左侧的组件。

  • 如果容器包含网格布局管理器,则容器的 Scrollable 属性不起作用。要启用滚动,请改为将 GridLayout 对象的 Scrollable 属性设置为 'on'

某些类型的图和坐标区不支持可滚动容器。但是,您可以将图或坐标区放在不可滚动的面板中,然后将该面板放在可滚动的容器中。有关详细信息,请参阅在 App 设计工具中显示图形

上下文菜单,指定为使用 uicontextmenu 函数创建的 ContextMenu 对象。使用此属性可在您右键点击 UI 图窗时显示上下文菜单。

常见回调

全部展开

按钮按下回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户点击 UI 图窗的空白区域时,将执行此回调。

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

使用 SelectionType 属性确定用户是否按下了修改键。

对象创建函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调

此属性指定要在 MATLAB 创建对象时执行的回调函数。MATLAB 将在执行 CreateFcn 回调之前初始化所有属性值。如果不指定 CreateFcn 属性,则 MATLAB 执行默认的创建函数。

对现有组件设置 CreateFcn 属性没有任何作用。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参量访问正在创建的对象。否则,使用 gcbo 函数访问该对象。

对象删除函数,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调

此属性指定在 MATLAB 删除对象时要执行的回调函数。MATLAB 在销毁对象的属性之前执行 DeleteFcn 回调。如果不指定 DeleteFcn 属性,则 MATLAB 执行默认的删除函数。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参量访问要删除的对象。否则,使用 gcbo 函数访问该对象。

键盘回调

全部展开

按键回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户在 UI 图窗或子组件具有焦点的情况下按下一个键时,将执行此回调函数。在接受键盘焦点的组件(例如编辑字段)上按下一个键时不会执行回调,除非该组件被禁用。您可以通过将 EnableEditable 属性设置为 'off' 来禁用组件。此外,通过将 Enable 属性设置为 'inactive',可以在不灰显的情况下禁用 Table 组件。

如果用户几乎在同一时间按下多个键,MATLAB 将检测所有键。

KeyPressFcn 回调可以访问有关用户与键盘交互的特定信息。MATLAB 将 KeyData 对象中的此信息作为第二个参量传递给回调函数。下表列出了 KeyData 对象的属性。

属性描述

示例:

  

a

=

Shift

Shift-a

Character

作为按下一个或多个键的结果而显示的字符。

按特定键或使用 Ctrl 键修改某些键可能会在此属性中返回无法打印的字符。

单独按特定键(例如 CtrlAltShift)不会生成 Character 数据。

'a''=''''A'
Modifier

包含按下的修改键名称的元胞数组,如 'control''alt''shift'。如果未按下修改键,则元胞数组为空。

{1x0 cell}{1x0 cell}{'shift'}{'shift'}
Key

按下的键,通过键上的小写字母标签(如 'pageup')或描述性字词(如 'space')标识。

'a''equal''shift''a'
Source按下该键时具有焦点的对象。Figure 对象Figure 对象Figure 对象Figure 对象
EventName导致回调函数执行的操作。'KeyPress''KeyPress''KeyPress''KeyPress'

有关指定回调属性值和使用回调参量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

CurrentCharacter 属性还返回字符信息。

释放键回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户在 UI 图窗或子组件具有焦点的情况下释放一个键时,将执行此回调函数。在接受键盘焦点的组件(例如编辑字段)上释放一个键时不会执行回调,除非该组件被禁用。您可以通过将 EnableEditable 属性设置为 'off' 来禁用组件。此外,通过将 Enable 属性设置为 'inactive',可以在不灰显的情况下禁用 Table 组件。

此回调函数可以访问有关用户与键盘的交互的特定信息。MATLAB 将 KeyData 对象中的此信息作为第二个参量传递给回调函数。下表列出了 KeyData 对象的属性。

属性描述

示例:

  

a

=

Shift

Shift-a

Character

与释放的一个或多个键对应的字符。

按特定键或使用 Ctrl 键修改某些键可能会在此属性中返回无法打印的字符。

单独按下并释放特定键(例如 CtrlAltShift)不会生成 Character 数据。

'a''=''''A'
Modifier

包含按下的修改键名称的元胞数组,如 'control''alt''shift'。如果未释放修改键,则元胞数组为空。

{1x0 cell}{1x0 cell}{'shift'}{'shift'}
Key

释放的键,通过键上的小写字母标签(如 'pageup')或描述性字词(如 'space')标识。

'a''equal''shift''a'
Source释放键时具有焦点的对象。Figure 对象Figure 对象Figure 对象Figure 对象
EventName导致回调函数执行的操作。'KeyRelease''KeyRelease''KeyRelease''KeyRelease'

有关指定回调属性值和使用回调参量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

窗口回调

全部展开

关闭请求回调,指定为下列值之一:

  • 函数句柄。

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

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

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅Specify a Callback Function

MATLAB 在 App 用户尝试关闭 App 时执行此回调。例如,您可以通过编码让回调例程显示一个对话框,要求 App 用户确认或取消关闭操作。

CloseRequestFcn 回调的默认值 'closereq' 会无条件地删除图窗,从而销毁窗口。

CloseRequestFcn 回调中考虑调用 delete 函数以关闭 Figure

  • 在 App 设计工具中,调用 delete(app)

  • 对于以编程方式创建的 App,调用 delete(f),其中 fFigure 对象。

如果 CloseRequestFcn 回调不包含 delete 命令,则 MATLAB 永远不会关闭窗口。您始终可以调用 delete 函数以强制关闭窗口。

示例:用来显示对话框的代码 CloseRequestFcn

此示例说明如何为关闭请求函数编码以显示要求用户确认关闭操作的确认对话框。将该代码保存到您系统上的可写入文件夹中。

function myCloseReq(src,event)
selection = uiconfirm(src,'Close this figure?',...
    'Confirm Close'); 
switch selection 
    case 'OK'
        delete(src)
    case 'Cancel'
        return 
end
end

现在,创建一个图窗,并为 CloseRequestFcn 指定 myCloseReq。请注意,函数句柄不会显式引用任何输入参量,但函数声明中包含两个输入参量。MATLAB 在回调执行时自动传递这些参量。第一个参量是触发回调的 UI 组件,第二个参量为回调函数提供事件数据。

uifigure('CloseRequestFcn',@myCloseReq);

关闭图窗窗口并显示确认对话框。

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

  • 函数句柄。

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

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

定义此回调在此容器的大小更改时(例如,当用户调整窗口大小时)自定义 App 布局。在其中编写代码来调整子组件的 Position 属性。

注意

除非此容器的 AutoResizeChildren 属性设置为 'off',否则 SizeChangedFcn 回调将不会执行。在 App 设计工具中,您可以通过选择容器并清除组件浏览器的组件选项卡中的 AutoResizeChildren 复选框,使 SizeChangedFcn 可执行。

SizeChangedFcn 回调在下列情况下执行:

  • 此容器首次变得可见。

  • 此容器在大小改变时可见。

  • 此容器在大小改变后首次变得可见。如果容器在大小改变时不可见,但后来变得可见,就属于这种情况。

定义 SizeChangedFcn 回调时要考虑的其他重要事项:

  • 考虑将此容器推迟到 SizeChangedFcn 使用的所有变量都定义之后再显示。此做法可避免 SizeChangedFcn 回调返回错误。要延迟显示容器,请将其 Visible 属性设置为 'off'。然后,在定义您的 SizeChangedFcn 回调使用的变量之后将 Visible 属性设置为 'on'

  • 如果您的 App 包含嵌套容器,它们从里向外调整大小。

  • 要访问从 SizeChangedFcn 中调整大小的容器,请指向源对象(回调中的第一个输入参量)或使用 gcbo 函数。

指定调整大小行为的替代方法是创建 GridLayout 对象或使用 App 设计工具中的自动调整布局选项。这些选项比 SizeChangedFcn 回调更容易使用。然而,与这些选项相比,SizeChangedFcn 回调有一些优势。例如:

  • 将组件调整到您定义的最小或最大大小。

  • 实现非线性调整大小行为,例如根据父容器的大小更改组件的大小。

窗口内按键按下回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户点击下列各项时执行此回调:

  • UI 图窗的空白区域。

  • UI 图窗中的 UI 组件。

  • UI 图窗中支持 ButtonDownFcn 属性的图形对象。

例如,点击 axes 对象将触发 WindowButtonDownFcn 回调。

如果用户点击 UITable 组件,回调不会执行,除非 Enable 属性设置为 'off''inactive'

请参阅特定图形对象的属性的列表,以确定它是否支持 ButtonDownFcn 属性。有关图形对象的属性,请参阅图形对象属性

注意

当用户点击 uiaxes 组件时,即使 uiaxes 组件不支持 ButtonDownFcn 属性,也会执行回调。

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

窗口内按键移动回调,指定为下列值之一:

  • 函数句柄。

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

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

通常,用户在 UI 图窗内移动指针时会执行此回调函数。但是,如果用户点击并按住鼠标按键并且将指针移到 UI 图窗之外,则在指针位于 UI 图窗之外时将执行 WindowButtonMotionFcn 回调。

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

窗口内按键弹起回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户执行下列操作时会执行此回调:

  • 在 UI 图窗的空白区域上释放鼠标按键。

  • 在 UI 图窗内的 UI 组件上释放鼠标按键。

  • 在支持 ButtonDownFcn 属性的 UI 图窗中的图形对象上释放鼠标按键。

例如,在 axes 对象上释放鼠标按键会触发 WindowButtonUpFcn 回调。

如果用户在 UITable 组件上释放鼠标按键,回调不会执行,除非 Enable 属性设置为 'off''inactive'

请参阅特定图形对象的属性的列表,以确定它是否支持 ButtonDownFcn 属性。有关图形对象的属性,请参阅图形对象属性

按键弹起操作与 UI 图窗中的按键按下操作相关联。当按键按下操作发生时,鼠标指针必须位于 UI 图窗内部,但在按键弹起操作发生时,它可以在图窗外部。

注意

当用户在 uiaxes 组件上释放鼠标按键时,即使 uiaxes 组件不支持 ButtonDownFcn 属性,也会执行回调。

有关将回调属性值指定为函数句柄、元胞数组或字符向量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

窗口按键回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户在 UI 图窗或子组件具有焦点的情况下按下一个键时,将执行此回调函数。如果用户几乎在同一时间按下多个键,MATLAB 将检测所有键。

此回调函数可以访问有关用户与键盘的交互的特定信息。MATLAB 将 KeyData 对象中的此信息作为第二个参量传递给回调函数。下表列出了 KeyData 对象的属性。

属性描述

示例:

  

a

=

Shift

Shift-a

Character

作为按下一个或多个键的结果而显示的字符。

按特定键或使用 Ctrl 键修改某些键可能会在此属性中返回无法打印的字符。

单独按特定键(例如 CtrlAltShift)不会生成 Character 数据。

'a''=''''A'
Modifier

包含按下的修改键名称的元胞数组,如 'control''alt''shift'。如果未按下修改键,则元胞数组为空。

{1x0 cell}{1x0 cell}{'shift'}{'shift'}
Key

按下的键,通过键上的小写字母标签(如 'pageup')或描述性字词(如 'space')标识。

'a''equal''shift''a'
Source按下该键时具有焦点的对象。Figure 对象Figure 对象Figure 对象Figure 对象
EventName导致回调函数执行的操作。'WindowKeyPress''WindowKeyPress''WindowKeyPress''WindowKeyPress'

有关指定回调属性值和使用回调参量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

CurrentCharacter 属性还返回字符信息。

窗口释放键回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户在 UI 图窗或子组件具有焦点的情况下释放一个键时,将执行此回调函数。

此回调函数可以访问有关用户与键盘的交互的特定信息。MATLAB 将 KeyData 对象中的此信息作为第二个参量传递给回调函数。下表列出了 KeyData 对象的属性。

属性描述

示例:

  

a

=

Shift

Shift-a

Character

与释放的一个或多个键对应的字符。

按特定键或使用 Ctrl 键修改某些键可能会在此属性中返回无法打印的字符。

单独按下并释放特定键(例如 CtrlAltShift)不会生成 Character 数据。

'a''=''''A'
Modifier

包含按下的修改键名称的元胞数组,如 'control''alt''shift'。如果未释放修改键,则元胞数组为空。

{1x0 cell}{1x0 cell}{'shift'}{'shift'}
Key

释放的键,通过键上的小写字母标签(如 'pageup')或描述性字词(如 'space')标识。

'a''equal''shift''a'
Source释放键时具有焦点的对象。Figure 对象Figure 对象Figure 对象Figure 对象
EventName导致回调函数执行的操作。'WindowKeyRelease''WindowKeyRelease''WindowKeyRelease''WindowKeyRelease'

有关指定回调属性值和使用回调参量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

窗口滚轮回调,指定为下列值之一:

  • 函数句柄。

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

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

当用户在 UI 图窗或其任一子组件具有焦点的情况下移动滚轮时,将执行此回调。但是,其他对象可以捕获滚轮移动和干扰此回调的执行。

此回调对 CurrentObjectSelectionType 属性没有影响。

当用户旋转滚轮时,此回调可以访问特定信息。MATLAB 将 ScrollWheelData 对象中的此信息作为第二个参量传递给回调函数。下表列出了 ScrollWheelData 对象的属性。

属性

内容

VerticalScrollCount

正数或负数,表示滚轮点击的方向和数量。向下滚动返回正值。向上滚动返回负值。

垂直滚动计数是自上次执行回调以来发生的所有滚轮点击的总次数。通常,值为 1-1。但是,如果 WindowScrollWheelFcn 回调需要很长时间才能返回或者用户转动滚轮的速度太快,则滚动计数的值会大一些。

VerticalScrollAmount

常量值 3

Source

执行回调的对象。

EventName'WindowScrollWheel'.

有关指定回调属性值和使用回调参量的详细信息,请参阅App 设计工具中的回调Create Callbacks for Apps Created Programmatically

示例:用于更改 x 坐标轴范围的 App

以下示例说明如何创建一个用于显示绘图的 App。用户转动鼠标滚轮即可更改 x 轴的范围。将以下代码复制并粘贴到编辑器中并运行它。

function scroll_wheel
% Shows how to use WindowScrollWheelFcn property
%
   f = uifigure('WindowScrollWheelFcn',@figScroll,'Name','Scroll Wheel Demo');
   x = 0:.1:40;
   y = 4.*cos(x)./(x+2);
   a = axes(f); 
   h = plot(a,x,y);
   title(a,'Rotate the scroll wheel')

   function figScroll(~,event)
      if event.VerticalScrollCount > 0 
         xd = h.XData;
         inc = xd(end)/20;
         x = [0:.1:xd(end)+inc];
         re_eval(x)
      elseif event.VerticalScrollCount < 0 
         xd = h.XData;
         inc = xd(end)/20;
         % Don't let xd = 0
         x = [0:.1:xd(end)-inc+.1]; 
         re_eval(x)
      end
   end

   function re_eval(x)
      y = 4.*cos(x)./(x+2);
      h.YData = y;
      h.XData = x;
      a.XLim = [0 x(end)];
      drawnow
   end
end

请注意,figScroll 的函数句柄不会显式引用任何输入参量,但函数声明中包含两个输入参量。MATLAB 在回调执行时自动传递这些参量。第一个参量是触发回调的 UI 组件,第二个参量为回调函数提供事件数据。

回调执行控件

全部展开

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

此属性确定是否可以中断运行中回调。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

每次执行处理回调队列的命令时,MATLAB 都会确定回调中断行为。这些命令包括 drawnowfigureuifiguregetframewaitforpause

如果运行中回调不包含上述命令之一,则不会发生中断。MATLAB 首先完成执行运行中回调,然后执行中断回调。

如果运行中回调确实包含上述命令之一,则由运行中回调所属对象的 Interruptible 属性来确定是否发生中断:

  • 如果 Interruptible 的值为 'off',则不会发生中断。此时,由中断回调所属对象的 BusyAction 属性确定中断回调是被丢弃还是添加到回调队列中。

  • 如果 Interruptible 的值为 'on',则发生中断。下次 MATLAB 处理回调队列时,它会停止运行中回调的执行,并执行中断回调。在中断回调完成后,MATLAB 将继续执行运行中回调。

注意

回调的中断和执行在以下情况下会有不同的表现:

  • 如果中断回调是 DeleteFcnCloseRequestFcnSizeChangedFcn 回调,则无论是否存在 Interruptible 属性值都会发生中断。

  • 如果运行中回调当前正在执行 waitfor 函数,则无论是否存在 Interruptible 属性值都会发生中断。

  • 如果中断回调由 Timer 对象所有,则回调将根据调度执行,而不考虑 Interruptible 属性值。

注意

发生中断时,MATLAB 不保存属性状态或显示内容。例如,gcagcf 命令返回的对象可能会在另一个回调执行时发生改变。

回调排队,指定为 'queue''cancel'BusyAction 属性决定 MATLAB 如何处理中断回调的执行。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

BusyAction 属性仅在同时满足以下两个条件时才确定回调排队行为:

在这些情况下,由中断回调所属对象的 BusyAction 属性确定 MATLAB 如何处理中断回调。以下是 BusyAction 属性的可能值:

  • 'queue' - 将中断回调放入队列中,以便在运行中回调执行完毕后进行处理。

  • 'cancel' - 不执行中断回调。

此 属性 为只读。

删除状态,以 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值形式返回。

DeleteFcn 回调开始执行时,MATLAB 会将 BeingDeleted 属性设置为 'on'BeingDeleted 属性将一直保持 'on' 设置状态,直到组件对象不再存在为止。

在查询或修改对象之前,请先检查其 BeingDeleted 属性的值,以确认它不是待删除项。

父级/子级

全部展开

此 属性 为只读。

父对象,以根对象形式返回。

Figure 对象的子级,以空 GraphicsPlaceholder 或一维组件对象数组形式返回。子级可以是任何组件,但不包括另一个 Figure 对象。

不能使用 Children 属性添加或删除子组件。使用该属性查看子级列表或对子级重新排序。子级在该数组中的顺序反映了组件在屏幕上的前后顺序(堆叠顺序)。

要向该列表中添加子级,请将子组件的 Parent 属性设置为 Figure 对象。

对象句柄的可见性,指定为 'off''callback''on'。此属性提供有关 Figure 对象在其父级的子级列表中的可见性的信息。默认值设置为 'off',以防止 Figure 对象成为当前图窗 (gcf),并防止函数对 UI 进行不必要的更改。

下表说明设置每个值的作用:

HandleVisibility 值描述
'off'

Figure 对象句柄对于回调函数或在命令行窗口中执行的函数不可见。此外,对象句柄:

  • 在图形根 ChildrenCurrentFigure 属性返回的列表中不可见。

  • 不会由通过搜索对象层次结构或查询对象属性来访问对象的函数返回。这些函数包括 gcfgcogetfindobjclfclose

此选项防止回调函数和从命令行调用的函数以对象为目标,并对 UI 进行无意中的更改。

'callback'

Figure 对象句柄仅在回调或回调所调用的函数中可见,在从命令行窗口调用的函数中不可见。此外,对象句柄在图形根 ChildrenCurrentFigure 属性返回的列表中不可见。

此选项阻止通过命令行访问对象,但允许回调函数访问对象。

'on'

Figure 对象句柄始终可见。

即使对象的 HandleVisibility 属性设置为 'off',这些对象仍然有效。如果可以访问某个对象,则可以设置和获取其属性,并将其传递给针对对象进行操作的任意函数。

标识符

全部展开

图窗的名称,指定为字符向量或字符串标量。

示例: uifigure('Name','Results') 将图窗的名称设置为 'Results'

在 App 设计工具中,Name 属性的默认值为 'MATLAB App'

图标源或文件,指定为字符向量、字符串标量或 m×n×3 真彩色图像数组。如果指定文件名,它可以是 MATLAB 路径中的图像文件名或图像文件的完整路径。如果您计划与他人共享某个 App,请将图像文件放在 MATLAB 路径中以便于打包 App。

支持的图像格式包括 JPEG、PNG、GIF 和 m×n×3 真彩色图像数组。有关真彩色图像数组的详细信息,请参阅图像类型。动画 GIF 文件只显示第一帧。

如果没有足够的空间显示完整大小的图标,MATLAB 会缩小图像以适应空间。

示例: 'icon.png' 指定 MATLAB 路径中的图标文件。

示例: 'C:\Documents\icon.png' 指定图像文件的完整路径。

示例: fig = uifigure('Icon','peppers.png') 使用指定的图标图像文件创建一个 UI 图窗。

此 属性 为只读。

图窗的编号,以整数或空数组形式返回。您可以使用该值表示图窗。例如,figure(2) 使 Number 属性值为 2 的图窗成为当前图窗。

如果 IntegerHandle 属性设置为 'off',则 Number 属性为空。

如果 IntegerHandle'on',则 Number 属性是整数。删除该图窗时,MATLAB 会对下一个图窗重用该编号。

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

将此属性设置为 'on' 时,UI 图窗的标题包含短语 'Figure n',其中 n 是数字。

NumberTitleIntegerHandle 属性都必须设置为 'on' 才能显示标题中的数字。

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

如果将 IntegerHandle 属性设置为 'on',则 MATLAB 会查找现有图窗不使用的最小整数值并将 Number 属性设置为该值。如果删除某 UI 图窗,MATLAB 可以将该图窗的编号重新用于新图窗。

如果将 IntegerHandle 属性设置为 'off',则 MATLAB 不会为 UI 图窗分配整数值,而是会将 Number 属性设为空数组。

要显示标题栏中的数字,IntegerHandleNumberTitle 都必须设置为 'on'

此 属性 为只读。

图形对象的类型,以 'figure' 形式返回。

对象标识符,指定为字符向量或字符串标量。您可以指定唯一的 Tag 值作为对象的标识符。如果需要访问您代码中其他位置的对象,可以使用 findobj 函数基于 Tag 值搜索对象。

用户数据,指定为任何 MATLAB 数组。例如,您可以指定标量、向量、矩阵、元胞数组、字符数组、表或结构体。使用此属性存储对象上的任意数据。

如果您在 App 设计工具中工作,请在该 App 中创建公共或私有属性以共享数据,而不是使用 UserData 属性。有关详细信息,请参阅在用 App 设计工具创建的 App 内共享数据

版本历史记录

在 R2016a 中推出

全部展开