Main Content

GUIDE 迁移策略

在 R2019b 中,MathWorks® 宣布将在以后的版本中删除原来用于在 MATLAB® 中构建 App 的拖放式环境 GUIDE。在删除 GUIDE 后,使用 GUIDE 创建的现有 App (GUI) 可继续在 MATLAB 中运行,如果您需要更改 App 的行为,仍可编辑 App 程序文件。

要继续编辑使用 GUIDE 创建的现有 App 的布局并保持与将来的 MATLAB 版本的兼容性,请务必使用下表中列出的建议迁移策略之一。

App 开发需求迁移策略如何迁移
持续开发将您的 App 迁移到 App 设计工具。在 GUIDE 中打开 App,并选择文件 > 迁移到 App 设计工具。在“GUIDE 转换选项”对话框中,点击迁移
偶尔编辑将您的 App 导出到单个 MATLAB 文件,以使用 MATLAB 函数管理您的 App 布局和代码在 GUIDE 中打开 App,选择文件 > 导出为 MATLAB 文件。在“GUIDE 转换选项”对话框中,点击导出

将用 GUIDE 开发的 App 迁移到 App 设计工具

将使用 GUIDE 创建的 App 迁移到 App 设计工具后,您可以继续以交互方式设计 App 的布局。您还可以利用增强的 UI 组件集和自动调整布局选项等功能,使您的 App 能够响应屏幕大小的变化。您还可以创建 App 并将其作为 Web App 进行共享(需要 MATLAB Compiler™)。

对于需要重大或持续功能开发的使用 GUIDE 创建的 App,请使用此选项。

GUIDE to App Designer Migration Tool for MATLAB 在 R2018a 中首次发布,用于简化转换过程。您可通过 MATLAB 桌面版的附加功能资源管理器或通过 MATLAB Central™ 上的 File Exchange 获得该工具。

从 R2020a 开始,该迁移工具有了显著改进,可大大减少让您的 App 开始在 App 设计工具中运行所需的时间和人工代码更新次数。有关这些增强功能的详细信息,请参阅回调代码

可以采用多种方法来迁移您的 App,具体取决于您最初所用的环境。

  • 在 GUIDE 中,打开您的 App 并选择文件 > 迁移到 App 设计工具

    • 如果您尚未安装 GUIDE to App Designer Migration Tool,请点击安装支持包。这将打开附加功能资源管理器,您可以在其中安装该迁移工具。安装该工具后,请重新打开 GUIDE 转换选项对话框。

    • 安装 GUIDE to App Designer Migration Tool 后,选择正确的 FIG 文件,然后点击迁移。App 将迁移并自动在 App 设计工具中打开。

  • 在 App 设计工具中,打开任一 App 并转至设计工具选项卡。在文件部分中,点击打开 > 打开 GUIDE to App Designer Migration Tool

  • 在 MATLAB 命令行窗口中,调用 appmigration.migrateGUIDEApp 函数。您可以使用此函数批量迁移多个使用 GUIDE 创建的 App。

迁移工具的功能

该迁移工具可读入 GUIDE FIG 文件并在 MLAPP 文件中自动生成 App 设计工具等效组件和布局,以此帮助您转换 App。您的 GUIDE 回调代码和用户定义的其他函数将被复制到 MLAPP 文件中。这种半自动代码转换还会创建迁移报告,该报告为需要手动进行代码更新的部分提供操作建议。下表描述了该工具的一些功能。

迁移工具功能描述
文件转换读取 GUIDE FIG 文件和关联的代码,然后生成 App 设计工具 MLAPP 文件。App 设计工具文件名采用 guideFileName _App.mlapp 形式。
组件和 App 布局

将组件和属性配置转换为 App 设计工具的等效内容,并保留 App 的布局。

A GUIDE app and an App Designer app to calculate mass. The layout and functionality of each app is the same. There are minor visual differences, such as the color of the buttons.

回调代码在 MLAPP 文件中保留 GUIDE 回调代码和用户定义函数的副本。
教程逐步演示对迁移的 App 所做的更改。
迁移报告总结迁移工具成功完成的操作。列出针对您的 App 的任何限制或不受支持的功能,并提供建议的操作(如果有)。

回调代码

为了在您的 App 中使 GUIDE 样式回调代码与 App 设计工具 UI 组件兼容,迁移工具使用名为 convertToGUIDECallbackArguments 的函数。此函数将 App 设计工具回调参量转换为您的代码所需的 GUIDE 样式回调参量。convertToGUIDECallbackArguments 函数将添加到每个迁移的回调函数的开头。它接受 App 设计工具回调参量 appevent,并返回 GUIDE 样式回调参量 hObjecteventdatahandles。例如:

Example of a call to the convertToGUIDECallbackArguments function inside an App Designer callback

每个 GUIDE 样式回调参量都有不同用途:

  • hObject 是正在执行其回调的对象的句柄。对于使用 GUIDE 创建的 App 中作为 UIControlButtonGroup 对象的组件,hObjectUIControlPropertiesConverterButtonGroupPropertiesConverter 对象的句柄。创建这些对象是为了让您的 GUIDE 样式代码在您的 App 设计工具回调函数中工作。

  • eventdata 通常为空,但可以是包含关于回调事件特定信息的结构体。

  • handles 是一个包含 UI 图窗的迁移子组件的结构体,这些子组件设置了 'Tag' 属性值。在使用 GUIDE 创建的 App 中作为 UIControl 对象的子组件是迁移的 App 中的 UIControlPropertiesConverter 对象。同样,子 ButtonGroup 对象是迁移的 App 中的 ButtonGroupPropertiesConverter 对象。

UIControlPropertiesConverterButtonGroupPropertiesConverter 对象就像 GUIDE 样式代码和 App 设计工具组件及回调之间的适配器。为使用 GUIDE 创建的 App 中作为 UIControl 对象的每个组件创建一个 UIControlPropertiesConverter 对象。这些转换器对象与迁移的 App 中的 App 设计工具 UI 组件相关联。转换器对象与使用 GUIDE 创建的 App 中的原始 UIControl 具有相同的属性和值,但转换器对象将它们应用于其关联的 App 设计工具 UI 组件。

同样,对于 GUIDE 中的 ButtonGroup 对象,在 App 设计工具中会创建 ButtonGroupPropertiesConverter 对象。通过此对象,可以将 SelectedObject 属性设置为 UIControlPropertiesConverter 对象,以便按钮组 SelectionChangedFcn 回调逻辑正常工作。

特殊注意事项

有些情况需要您在迁移 App 之前或之后采取额外的步骤。下表列出了需要额外步骤或手动代码更新的常见场景和编码模式。此列表并未列出所有情形。

通过 GUIDE 创建的 App 的功能描述建议的操作
多窗口 App(即两个或更多共享数据的 App)多窗口 App 要求单独迁移每个 App。迁移后的 App 文件名后会追加 _App。必须更新其他 App 对这些 App 的调用。单独迁移每个 App。在调用方 App 中,将被调用的 App 的名称更新为新文件名。
单选按钮和单选按钮回调

迁移工具不会迁移不属于单选按钮组的单选按钮,也不会迁移单个单选按钮的回调函数。

在 App 设计工具中创建一个按钮组,并向其中添加单选按钮。要执行在单选按钮选择状态改变时的行为,请为按钮组创建 SelectionChangedFcn 回调函数。有关详细信息,请参阅 uiradiobuttonButtonGroup 属性
uistack不支持在 App 设计工具中调用此函数。在迁移之前,确定此功能对您的 App 是否至关重要。App 设计工具中没有相应的解决方法。
findobjfindallgcbo

使用 findobjfindallgcbo 来引用组件和设置属性可能会出错。UIControl 对象将被迁移到等效的 App 设计工具 UI 组件。要访问和设置这些迁移的组件的属性,您必须在 UIControlPropertiesConverter 对象上设置它。您也可以将您的代码更新为使用其关联的 App 设计工具组件、属性和值。

请改用 handles 结构体来引用组件,或将您的代码更新为使用关联的 App 设计工具组件、属性和值。
narginnargchk辅助函数会迁移到 App 方法,并使用 app 作为额外的输入参量。这可能导致不正确的 narginnargchk 逻辑。将检查值增大 1
OutputFcn(varargout)Figure 输出

App 设计工具中没有等效功能。

在实例化迁移到 App 设计工具中的 App 时,输出始终是 App 对象,而不是 Figure 对象。

如果您的 OutputFcn 函数包含对您的 App 至关重要的初始化代码,则将其添加到 OpeningFcn 的末尾。

如果您的 OutputFcn 函数指定在实例化 App(例如 Figure 对象)时将输出分配到工作区,则您需要创建实例化 App 的函数。例如:

function out = MyGUIDEApp(varargin)
    app = MyMigratedApp(varargin{:});
    out = app.UIFigure;            
end

如果您使用 GUIDE 创建的 App 使用 actxcontrol 等函数集成第三方组件,请参阅关于使用 Java 和 ActiveX 的 MATLAB App 的建议

GUIDE 和 App 设计工具代码之间的差异

App 设计工具与 GUIDE 之间的主要差异在于代码结构、回调语法以及访问 UI 组件和共享数据的方式。如果您计划向迁移的 App 添加新 App 设计工具功能,或希望更新该 App 以使用 App 设计工具代码样式和约定,了解这些差异将非常有用。下表总结了其中一些差异。

差异GUIDE App 设计工具更多信息
使用图窗和图形

GUIDE 调用 figure 函数创建 App 窗口。

GUIDE 调用 axes 函数创建坐标区以显示绘图。

支持所有 MATLAB 图形函数。无需指定目标坐标区。

App 设计工具调用 uifigure 函数创建 App 窗口。

App 设计工具调用 uiaxes 函数创建坐标区以显示绘图。

支持大多数 MATLAB 图形函数。

在 App 设计工具中显示图形
使用组件

GUIDE 使用 uicontrol 函数创建大多数组件。可用的组件较少。

App 设计工具使用自己的专用函数创建每个 UI 组件。可用的组件较多,包括 TreeGaugeTabGroupDatePicker

App 构建组件
Update UIControl Objects and Callbacks
访问组件属性

GUIDE 使用 setget 访问组件属性,并使用 handles 指定组件。

例如,
name = get(handles.Fig,'Name')

App 设计工具支持 setget,但建议使用圆点表示法访问组件属性,并使用 app 指定组件。

例如,
name = app.UIFigure.Name

App 设计工具中的回调
管理 App 代码

代码被定义为可以调用局部函数的主函数。所有代码均可编辑。

代码被定义为 MATLAB 类。只有回调、辅助函数和自定义属性可以编辑。

在 App 设计工具的代码视图中管理代码
编写回调

所需的回调输入参量是 handleshObjecteventdata

例如,
myCallback(hObject,eventdata,handles)

所需的回调输入参量是 appevent

例如,
myCallback(app,event)

App 设计工具中的回调
共享数据

要存储数据以及在回调和函数之间共享数据,请使用 UserData 属性、handles 结构体或者 guidatasetappdatagetappdata 函数。

例如,
handles.currSelection = selection;
guidata(hObject,handles);

要存储数据以及在回调和函数之间共享数据,请使用自定义属性创建变量。

例如,
app.currSelection = selection

在用 App 设计工具创建的 App 内共享数据

更新迁移的 App 回调代码

迁移的 App 使用 GUIDE 样式对象和代码约定。最好在迁移的 App 中更新回调代码以使用 App 设计工具对象和代码约定。更新您的回调代码可支持现代 App 构建功能,并使 App 更易于维护。要更新您的代码,请按照以下步骤操作:

  1. 使用 App 设计工具 UI 组件 - 在回调函数中,更新对 handles 结构体的引用,改用 app 对象。通过 handles 结构体可访问转换器对象,这些对象表示使用 GUIDE 创建的 App 中的 UIControl 对象,而通过 app 对象可访问在 App 设计工具中创建的 App 中的 UI 组件。

    例如,GUIDE 样式回调能使用以下代码来设置普通按钮样式的 UIControl 对象的背景颜色:

    handles.pushbutton1.BackgroundColor = 'red';

    更新以下代码以直接设置按钮 UI 组件的背景颜色:

    app.pushbutton1.BackgroundColor = 'red';

  2. 更新 UI 组件属性 - 更新回调代码设置的属性。通常,UIControl 对象和与其等效的 UI 组件对象之间具有许多相同的属性。但是,它们在属性名称或属性接受的值的类型方面存在一些差异。要查看 UIControl 和 UI 组件对象和属性之间的比较,并了解如何更新您的代码以使用 UI 组件,请参阅Update UIControl Objects and Callbacks

  3. 删除未使用的代码 - 一旦回调函数不再使用 hObjecteventdatahandles 参量,请删除由创建这些参量的迁移工具添加的代码行:

    [hObject,eventdata,handles] = convertToGUIDECallbackArguments(app,event);

如果您的 App 使用了 errordlgwarndlg 等函数创建对话框,您也可以更新代码,比如使用 uialertuiconfirm 函数,创建专门用于 App 构建的现代对话框。有关详细信息,请参阅Update Dialog Boxes

将使用 GUIDE 创建的 App 导出到 MATLAB 文件

导出使用 GUIDE 创建的 App 时,通过在单个 MATLAB 程序文件中重新创建 GUIDE FIG 和程序文件,可将其转换为编程式 App。

如果您计划执行以下操作,请使用此选项:

  • 对 App 的布局或行为稍作修改。

  • 以编程方式(而不是以交互方式)开发 App。

要导出您的 App,请在 GUIDE 中打开它,然后选择文件 > 导出为 MATLAB 文件,或右键点击 MATLAB 当前文件夹浏览器中的 FIG 文件,然后选择导出为 MATLAB 文件。这将显示“GUIDE 转换选项”对话框。确认选择了正确的 FIG 文件,然后点击导出。MATLAB 将创建一个文件名后追加了 _export 的程序文件。新文件包含您的原始回调代码以及用来处理 App 创建和布局的自动生成的函数。下面显示了这些增加的函数的示例。

Generated function code to handle app creation.

另请参阅

相关主题