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 Needs	Migration Strategy	How to Migrate
Ongoing development	Migrate your app to App Designer.	Open the app in GUIDE and select File > Migrate to App Designer. In the GUIDE Transition Options dialog, click Migrate.
Occasional editing	Export 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. In the GUIDE Transition Options dialog, click Export.

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™).

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

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.

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

In GUIDE, open your app and select File > Migrate to App Designer.
- If you do not already have the GUIDE to App Designer Migration Tool installed, click Install Support Package. This opens the Add-On Explorer, where you can install the migration tool. Once you have installed the tool, reopen the GUIDE Transition Options dialog.
- Once you have installed the GUIDE to App Designer Migration Tool, choose the correct FIG file and then click Migrate. The app migrates and automatically opens in App Designer.
In App Designer, open any app and go to the Designer tab. In the File section, click Open > Open GUIDE to App Designer Migration Tool.
In the MATLAB Command Window, call the appmigration.migrateGUIDEApp function. You can use this function to migrate multiple GUIDE apps as a batch.

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 Features	Description
File Conversion	Read 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 Code	Retain a copy of the GUIDE callback code and user-defined functions in the MLAPP file.
Tutorial	Step through the changes made to your migrated app.
Migration Report	Summarize 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:

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

Each of the GUIDE-style callback arguments is used for a different purpose:

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 Feature	Description	Suggested 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`.
`uistack`	Calling this function 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 `nargchk`	Helper 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.

Differences Between GUIDE and App Designer Code

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.

Difference	GUIDE	App Designer	More 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 Update UIControl Objects and Callbacks
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`	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,eventdata,handles)`	Required callback input arguments are `app` and `event`. For example, `myCallback(app,event)`	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

Update Migrated App Callback Code

Migrated apps use GUIDE-style objects and code conventions. It is a good practice to update the callback code in your migrated app to use App Designer objects and code conventions. Updating your callback code provides support for modern app building functionality and makes the app easier to maintain. To update your code, follow these steps:

Use App Designer UI components — In your callback functions, update references to the handles structure to instead use the app object. The handles structure gives access to converter objects that represent UIControl objects in your GUIDE app, whereas the app object gives access to the UI components in the App Designer app.
For example, a GUIDE-style callback sets the background color of a push button style UIControl object using this code:
```
handles.pushbutton1.BackgroundColor = 'red';
```
Update this code to set the background color of the button UI component directly:
```
app.pushbutton1.BackgroundColor = 'red';
```
Update UI component properties — Update the properties that your callback code sets. In general, UIControl objects and their equivalent UI component objects have many of the same properties. However, there are some differences in the property names or the types of values that the properties accept. To see a comparison between UIControl and UI component objects and properties, and to learn how to update your code to use UI components, see Update UIControl Objects and Callbacks.
Delete unused code — Once a callback function no longer uses the hObject, eventdata, and handles arguments, delete the line of code added by the migration tool that creates those arguments:
```
[hObject,eventdata,handles] = convertToGUIDECallbackArguments(app,event);
```

If your app creates dialog boxes using functions such as errordlg or warndlg, you can also update your code to take advantage of modern dialog boxes created specifically for app building, such as uialert and uiconfirm. For more information, see Update Dialog Boxes.

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, or right-click the FIG file in the MATLAB Current Folder browser and select Export to MATLAB-file. This brings up the GUIDE Transition Options dialog box. Verify that the correct FIG file is selected and then click Export. 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.

Generated function code to handle app creation.