Main Content

GUIDE Migration Strategies

In R2019b, MathWorks® announced that GUIDE, the original drag-and-drop environment for building apps in MATLAB®, will be removed in a future release. After GUIDE is removed, existing GUIDE apps (GUIs) will continue to run in MATLAB, and app program files will still be editable if you need to change the behavior of an app.

To continue editing the layout of an existing GUIDE app and help maintain its compatibility with future MATLAB releases, you must use one of the suggested migration strategies listed in this table.

App Development NeedsMigration StrategyHow to Migrate
Occasional editingExport your app to a single MATLAB file to manage your app layout and code using MATLAB functions.Open the app in GUIDE and select File > Export to MATLAB-file.
Ongoing developmentMigrate your app to App Designer.Use the GUIDE to App Designer Migration Tool for MATLAB on mathworks.com.

Export GUIDE App to MATLAB File

Exporting a GUIDE app converts it into a programmatic app by recreating the GUIDE FIG and program files together in a single MATLAB program file.

Use this option if you plan to:

  • Make minor changes to the layout or behavior of your app.

  • Develop your app programmatically, not interactively.

To export your app, open it in GUIDE and select File > Export to MATLAB-file. MATLAB creates a program file with _export appended to the file name. The new file contains your original callback code plus auto-generated functions that handle the creation and layout of the app. An example of these added functions is shown here.

Migrate GUIDE App to App Designer

Migrating your GUIDE app to App Designer allows you to continue developing the layout of your app interactively. It also allows you to take advantage of features like an enhanced UI component set and auto-reflow options to make your app responsive to changes in screen size. And it gives you the ability to create and share your app as a web app (requires MATLAB Compiler™).

The GUIDE to App Designer Migration Tool for MATLAB was first released in R2018a to ease the conversion process. It is available through the Add-On Explorer in the MATLAB desktop or through File Exchange on MATLAB Central™ .

Starting in R2020a, the migration tool has significant improvements that drastically reduce the time, and the number of manual code updates, required to get your app running in App Designer. For details about these enhancements, see Callback Code.

Use this option for GUIDE apps that require significant or ongoing feature development.

There are several ways to migrate your app, depending on which environment you begin in.

  • From the GUIDE Quick Start dialog, click the Open Existing GUI tab. Then, select a FIG file and click Migrate to App Designer. This opens the GUIDE to App Designer Migration Tool if it is already installed. If it is not already installed, a dialog box prompts you to download and install it first. In the migration tool, verify that the correct FIG file is selected for migration and then click Migrate. The app migrates and automatically opens in App Designer.

  • From App Designer, go to the Designer tab. In the File section, click Open > Open GUIDE to App Designer Migration Tool.

Features of the Migration Tool

The migration tool helps you convert your apps by reading in a GUIDE FIG file and automatically generating the App Designer equivalent components and layout in an MLAPP file. Your GUIDE callback code and other user-defined functions are copied into the MLAPP file. This semi-automated code conversion also creates a migration report that suggests actions for any manual code updates that are needed. Some features of the tool are described in this table.

Migration Tool FeaturesDescription
File ConversionRead in a GUIDE FIG file and associated code and then generate an App Designer MLAPP file. The App Designer file name takes the form guideFileName_App.mlapp.
Components and App Layout

Convert components and property configurations to App Designer equivalents, and preserve the layout of the app.

Callback CodeRetain a copy of the GUIDE callback code and user-defined functions in the MLAPP file.
TutorialStep through the changes made to your migrated app.
Migration ReportSummarize the actions successfully completed by the migration tool. List any limitations or unsupported functionality, specific to your app, with suggested actions if available.

Callback Code

In order to make your GUIDE-style callback code compatible with the App Designer UI components in your app, the migration tool uses a function called convertToGUIDECallbackArguments. This function converts App Designer callback arguments into the GUIDE-style callback arguments that your code requires. The convertToGUIDECallbackArguments function is added to the beginning of each migrated callback function. It takes the App Designer callback arguments app and event and returns the GUIDE-style callback arguments hObject, eventdata, and handles. For example:

hObject is the handle of the object whose callback is executing. For components from your GUIDE app that were UIControl or ButtonGroup objects, hObject is a handle to a UIControlPropertiesConverter or ButtonGroupPropertiesConverter object. These objects are created to make your GUIDE-style code work in your App Designer callback functions.

eventdata is usually empty, but can be a structure containing specific information about the callback event.

handles is a structure that contains the migrated child components of the UI figure that have a 'Tag' property value set. Child components that were UIControl objects in your GUIDE app are UIControlPropertiesConverter objects in the migrated app. Similarly, child ButtonGroup objects are ButtonGroupPropertiesConverter objects in the migrated app.

The UIControlPropertiesConverter and ButtonGroupPropertiesConverter objects act like adapters between the GUIDE-style code and the App Designer components and callbacks. A UIControlPropertiesConverter object is created for each component in your GUIDE app that was a UIControl object. These converter objects are associated with an App Designer UI component in your migrated app. The converter object has the same properties and values as the original UIControl from your GUIDE app, but it applies them to its associated App Designer UI component.

Similarly, for ButtonGroup objects from GUIDE, a ButtonGroupPropertiesConverter object is created in App Designer. This object makes it possible to set the SelectedObject property to a UIControlPropertiesConverter object so that button group SelectionChangedFcn callback logic will function.

Special Considerations

There are some circumstances that require you to take extra steps before or after you migrate your app. This table lists common scenarios and coding patterns that require extra steps or manual code updates. This is not intended to be a comprehensive list.

GUIDE App FeatureDescriptionSuggested Actions
Multiwindow apps (that is, two or more apps that share data)Multiwindow apps require each app to be migrated separately. Migrated app file names are appended with _App. Calls to these apps from other apps must be updated.Migrate each app separately. In the calling app, update the name of the app that is being called to the new file name.
Radio buttons and radio button callbacks

The migration tool does not migrate radio buttons that are not parented to a radio button group, or callback functions for individual radio buttons.

Create a button group in App Designer and add radio buttons to it. To execute behavior when radio button selection is changed, create a SelectionChangedFcn callback function for the button group. For more information, see uiradiobutton and ButtonGroup Properties.
clf, gco, movie, and uistackCalling these functions in App Designer is not supported.Determine if this functionality is critical to your app before migrating. There is no workaround in App Designer.
findobj, findall, and gcbo

Using findobj, findall, or gcbo to reference components and set properties can error. UIControl objects are migrated to the equivalent App Designer UI component. To access and set properties on these migrated components, you must set it on the UIControlPropertiesConverter objects. Or, you can update your code to use its associated App Designer component, properties, and values.

Reference components using the handles structure instead, or update your code to use the associated App Designer component, properties, and values.
nargin and nargchkHelper functions are migrated to app methods and have app as an additional input argument. This can cause incorrect nargin or nargchk logic.Increment check values by 1.
OutputFcn(varargout) and Figure output

There is no equivalent functionality in App Designer.

When you instantiate a migrated App Designer app, the output is always the app object, not the Figure object.

If your OutputFcn function includes initialization code that is critical to your app, then add it to the end of the OpeningFcn instead.

If your OutputFcn function specifies output to be assigned to the workspace when you instantiate the app, such as the Figure object, then you need to create a function that instantiates the app. For example:

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

If your GUIDE app integrates third-party components using functions like actxcontrol, see Recommendations for MATLAB Apps Using Java and ActiveX.

Aids for Adding New Features or Fully Adopting App Designer Code Style

App Designer and GUIDE have different code structures, callback syntaxes, and techniques for accessing UI components and sharing data. Understanding these differences is useful if you plan to add new App Designer features to your migrated app or want to update it to use App Designer code style and conventions. This table summarizes some of these differences.

DifferenceGUIDE App DesignerMore Information
Using Figures and Graphics

GUIDE calls the figure function to create the app window.

GUIDE calls the axes function to create axes for displaying plots.

All MATLAB graphics functions are supported. There is no need to specify the target axes.

App Designer calls the uifigure function to create the app window.

App Designer calls the uiaxes function to create axes for displaying plots.

Most MATLAB graphics functions are supported.

Display Graphics in App Designer
Using Components

GUIDE creates most components with the uicontrol function. Fewer components are available.

App Designer creates each UI component with its own dedicated function. More components are available, including Tree, Gauge, TabGroup, and DatePicker.

App Building Components
Accessing Component Properties

GUIDE uses set and get to access component properties, and uses handles to specify a component.

For example,
name = get(handles.Fig,'Name')

App Designer supports set and get, but encourages the use of dot notation to access component properties, and uses app to specify a component.

For example,
name = app.UIFigure.Name

Write Callbacks in App Designer
Managing App Code

The code is defined as a main function that can call local functions. All code is editable.

The code is defined as a MATLAB class. Only callbacks, helper functions, and custom properties are editable.

Manage Code in App Designer Code View
Writing Callbacks

Required callback input arguments are handles, hObject, and eventdata.

For example,
myCallback(hObject,evendata,handles)

Required callback input arguments are app and event.

For example,
myCallback(app,event)

Write Callbacks in App Designer
Sharing Data

To store and share data between callbacks and functions, use the UserData property, the handles structure, or the guidata, setappdata, or getappdata function.

For example,
handles.currSelection = selection;
guidata(hObject,handles);

To store and share data between callbacks and functions, use custom properties to create variables.

For example,
app.currSelection = selection

Share Data Within App Designer Apps

Related Topics