Main Content

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

matlab.ui.componentcontainer.ComponentContainer 类

包: matlab.ui.componentcontainer

用于开发自定义 UI 组件对象的基类

描述

matlab.ui.componentcontainer.ComponentContainer 是您用于创建自己的自定义 UI 组件对象类的基类。定义此基类的子类时,可以使用 ComponentContainer 属性和方法来构建 UI 组件对象。在您的类定义文件的第一行指定以下语法以直接从 ComponentContainer 类继承,其中 MyComponent 是您的对象的名称:

classdef MyComponent < matlab.ui.componentcontainer.ComponentContainer

matlab.ui.componentcontainer.ComponentContainer 类是 handle 类。

类属性

Abstract
true
ConstructOnLoad
true
HandleCompatible
true

有关类属性的信息,请参阅类属性

属性

全部展开

颜色和样式

背景颜色,指定为 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

以下是 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

属性:

GetAccess
public
SetAccess
public
Dependent
true
GetObservable
true
SetObservable
true
交互性

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

  • 'on' - 显示对象。

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

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

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

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

属性:

GetAccess
public
SetAccess
public
Dependent
true
GetObservable
true
SetObservable
true

上下文菜单,指定为使用 uicontextmenu 函数创建的 ContextMenu 对象。当右键点击不包含任何基础 UI 组件或图形对象的组件区域时,将使用此属性显示上下文菜单。

要在右键点击自定义 UI 组件的任何部分时显示上下文菜单,请编写代码,以便每当设置自定义组件的 ContextMenu 属性时都设置所有基础 UI 组件和图形对象的 ContextMenu 属性。

示例:具有上下文菜单的组件

以下代码将创建一个简单的自定义 UI 组件,其中使用网格布局管理器来放置标签和按钮。每当用户创建 SimpleComponent 类实例并将一个上下文菜单赋给该组件时,update 方法中的代码就会将同一上下文菜单赋给底层 GridLayoutButtonLabel 对象。

classdef SimpleComponent < matlab.ui.componentcontainer.ComponentContainer

    properties (Access = private, Transient, NonCopyable)
        GridLayout matlab.ui.container.GridLayout
        Button matlab.ui.control.Button
        Label matlab.ui.control.Label
    end
    
    methods (Access=protected)
        function setup(obj)
            % Set component size
            obj.Position = [100 100 220 50];
            % Create grid
            obj.GridLayout = uigridlayout(obj,[1 2]);
            % Create components
            obj.Label = uilabel(obj.GridLayout,...
                "Text","My component");
            obj.Button = uibutton(obj.GridLayout);
        end
        
        function update(obj)
            obj.GridLayout.ContextMenu = obj.ContextMenu;
            obj.Label.ContextMenu = obj.ContextMenu;
            obj.Button.ContextMenu = obj.ContextMenu;
        end
    end
end

创建一个 SimpleComponent 对象并指定上下文菜单。右键点击组件和标签上的空白区域。将显示上下文菜单。

fig = uifigure;
cm = uicontextmenu(fig);
m1 = uimenu(cm);
SimpleComponent(fig,"ContextMenu",cm);

属性:

GetAccess
public
SetAccess
public
NonCopyable
true
Transient
true
GetObservable
true
SetObservable
true
位置

UI 组件的大小和位置,不包括轴标签和刻度线等装饰元素的边距。以 [left bottom width height] 形式的向量指定此属性。

注意

当 UI 组件的父级是 GridLayout 时,设置此属性不起作用。

属性:

GetAccess
public
SetAccess
public
Dependent
true

测量单位,指定为 'pixels'

属性:

GetAccess
public
SetAccess
public
Dependent
true
GetObservable
true
SetObservable
true

布局选项,指定为 GridLayoutOptions 对象。此属性为网格布局容器的子级组件指定选项。如果组件不是网格布局容器的子级(例如,它是图窗或面板的子级),则此属性为空且不起作用。但是,如果组件是网格布局容器的子级,则可以通过在 GridLayoutOptions 对象上设置 RowColumn 属性,将组件放置在网格的所需行和列中。

例如,以下代码将一个图像组件放置在其父网格的第三行第二列中。

g = uigridlayout([4 3]);
im = uiimage(g);
im.ImageSource = 'peppers.png';
im.ScaleMethod = 'fill';
im.Layout.Row = 3;
im.Layout.Column = 2;

要使该图像跨多个行或列,请将 RowColumn 属性指定为二元素向量。例如,此图像横跨列 23

im.Layout.Column = [2 3];

属性:

GetAccess
public
SetAccess
public
回调

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

  • 函数句柄。

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

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

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

  • 该组件首次变得可见。

  • 该组件在大小改变时可见。

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

属性:

GetAccess
public
SetAccess
public
Dependent
true
AbortSet
true
GetObservable
true
SetObservable
true
NonCopyable
true

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

  • 函数句柄。

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

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

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

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

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

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

属性:

GetAccess
public
SetAccess
public
Dependent
true
AbortSet
true
GetObservable
true
SetObservable
true
NonCopyable
true

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

  • 函数句柄。

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

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

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

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

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

属性:

GetAccess
public
SetAccess
public
Dependent
true
AbortSet
true
GetObservable
true
SetObservable
true
NonCopyable
true
回调执行控件

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

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

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

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

每当 MATLAB 调用回调时,回调都会试图中断正在运行的回调(如果存在)。运行中回调所属对象的 Interruptible 属性决定着是否允许中断。

  • 'on' 允许其他回调中断对象的回调。中断发生在 MATLAB 处理队列的下一个位置,例如当存在 drawnowfigureuifiguregetframewaitforpause 命令时。

    • 如果运行中回调包含以上命令之一,则 MATLAB 将在该时刻停止执行回调并执行中断回调。当中断回调完成时,MATLAB 将恢复执行运行中回调。

    • 如果运行中回调不包含以上命令之一,则 MATLAB 执行完当前回调,不会出现任何中断。

  • 'off' 阻止所有中断尝试。由中断回调所属的对象的 BusyAction 属性决定是放弃该中断回调还是将其放入队列中。

注意

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

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

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

  • Timer 对象根据排定时间执行,而不管 Interruptible 属性值如何。

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

属性:

GetAccess
public
SetAccess
public
GetObservable
true
SetObservable
true

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

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

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

无论何时 MATLAB 调用回调,该回调都会试图中断运行中回调。运行中回调所属对象的 Interruptible 属性决定着是否允许中断。如果不允许中断,则中断回调所属对象的属性 BusyAction 将决定是放弃该回调还是将回调放入队列中。以下是 BusyAction 属性的可能值:

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

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

属性:

GetAccess
public
SetAccess
public
GetObservable
true
SetObservable
true

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

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

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

属性:

GetAccess
public
SetAccess
protected
GetObservable
true
SetObservable
true
父级/子级

组件的父容器,指定为 FigurePanelTabGridLayout 对象。

属性:

GetAccess
public
SetAccess
public
Transient
true
Dependent
true
NonCopyable
true
GetObservable
true
SetObservable
true

UI 组件子级,以空 GraphicsPlaceholder 数组形式返回。自定义 UI 组件没有子级。设置此属性不会产生任何影响。

属性:

GetAccess
public
SetAccess
public
Transient
true
Dependent
true
NonCopyable
true

对象句柄的可见性,指定为 'on''callback''off'

此属性控制对象在其父级的子级列表中的可见性。当对象未显示在其父级的子级列表中时,通过搜索对象层次结构或查询属性来获取对象的函数不会返回该对象。这些函数包括 getfindobjclfclose。对象即使在不可见时也有效。如果可以访问某个对象,则可以设置和获取其属性,并将其传递给针对对象进行运算的任意函数。

HandleVisibility 值描述
'on'对象始终可见。
'callback'对象对于回调或回调调用的函数可见,但对于命令行调用的函数不可见。此选项阻止通过命令行访问对象,但允许回调函数访问它。
'off'对象始终不可见。该选项用于防止另一函数无意中对 UI 进行更改。将 HandleVisibility 设置为 'off' 可在执行该函数时暂时隐藏对象。

属性:

GetAccess
public
SetAccess
public
Dependent
true
GetObservable
true
SetObservable
true
标识符

UI 组件对象的类型,以包含组件名称的字符向量形式返回。

属性:

GetAccess
public
SetAccess
protected
NonCopyable
true
Transient
true

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

属性:

GetAccess
public
SetAccess
public
Dependent
true
GetObservable
true
SetObservable
true

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

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

属性:

GetAccess
public
SetAccess
public
Transient
true
GetObservable
true
SetObservable
true

方法

全部展开

示例

全部折叠

定义名为 IPAddressComponent 的类,该类创建一个自定义组件,用于输入四个值来构成 IP 地址。

要定义该类,请创建包含以下类定义的名为 IPAddressComponent.m 的文件,该文件具有如下特性:

  • 存储 IP 地址的 Value 公共属性。

  • NumericFieldGridLayout 私有属性,它们在一个水平行中放置四个数值编辑字段。

  • 一个 setup 方法,用于初始化 NumericFieldGridLayout

  • 一个 update 方法,用于在 IP 地址发生变化时更新 NumericField 值。

  • 一个 handleNewValue 方法,它基于 4 个数值编辑字段的值设置 Value 属性。

classdef IPAddressComponent < matlab.ui.componentcontainer.ComponentContainer
    % IPAddressComponent a set of 4 edit fields for IP Address input
    properties
        Value (1,4) {mustBeNonnegative, mustBeInteger, mustBeLessThanOrEqual(Value, 255)} = [192 168 1 2];
    end
    
    events (HasCallbackProperty, NotifyAccess = protected)
        ValueChanged % ValueChangedFcn callback property will be generated
    end

    
    properties (Access = private, Transient, NonCopyable)
        NumericField (1,4) matlab.ui.control.NumericEditField
        GridLayout matlab.ui.container.GridLayout
    end
    
    methods (Access=protected)
        function setup(obj)
            % Set the initial position of this component
            obj.Position = [100 100 150 22];
            
            % Layout
            obj.GridLayout = uigridlayout(obj,[1,5], ...
                'RowHeight',{22},'ColumnWidth',{30,30,30,30,22},...
                'Padding',0,'ColumnSpacing',2);
            
            % Building blocks
            for k = 1:4
                obj.NumericField(k) = uieditfield(obj.GridLayout, 'numeric',...
                    'Limits', [0 255], 'RoundFractionalValues', true, ...
                    'FontName', 'Courier New', 'FontWeight', 'bold', ...
                    'ValueChangedFcn',@(o,e) obj.handleNewValue());
            end
          
        end
        
        function update(obj)
            % Update view
            for k = 1:4
                obj.NumericField(k).Value = obj.Value(k);
            end
        end
    end
       
    methods (Access=private)
        function handleNewValue(obj)
            obj.Value = [obj.NumericField.Value];  
            
            % Execute the event listeners and the ValueChangedFcn callback property
            notify(obj,'ValueChanged');
        end
    end
end

接下来,通过调用由 ComponentContainer 类提供的 IPAddressComponent 构造函数方法来创建组件,并将对象返回为 h。指定一个函数,当组件值更改时,该函数在命令行窗口中显示新 IP 地址。

 h = IPAddressComponent;
 h.ValueChangedFcn = @(o,e) disp(['Value changed to: ', num2str(h.Value)]);

在编辑字段中输入 IP 地址 192.168.1.10。MATLAB 在命令行窗口中显示更新后的 IP 地址。

详细信息

全部展开

版本历史记录

在 R2020b 中推出