Update figure-Based Apps to Use uifigure

Update `figure`-Based Apps to Use `uifigure`

MATLAB^® provides two functions to create a figure window: figure and uifigure. While both of these functions create a Figure object, there are some differences in the way that this object is configured and the capabilities it supports. Figures created using the uifigure function are configured primarily for app building, whereas figures created using the figure function are configured primarily for data exploration and visualization.

The uifigure function is the recommended function to use when building new apps programmatically, and is the function that App Designer uses to create apps. The figure function will continue to be supported, but there are many new app building capabilities that can be used only with UI figures. This page provides an overview of the differences between Figure objects created using the figure function and the uifigure function, and information about how to update your app to take advantage of the uifigure-based app building capabilities.

Overview for Updating Your App

To update your figure-based app to use uifigure and take advantage of the additional capabilities in UI figures, follow these steps:

Update App Figure and Containers — Replace calls to figure with uifigure, and update the properties of the Figure object and other app containers, such as Panel and TabGroup objects.
Update UIControl Objects and Callbacks — Replace calls to uicontrol with analogous UI component functions, and update component properties and callbacks.
Update Dialog Boxes — Replace calls to dialog box functions such as errordlg and warndlg with dialog box functions configured for app building such as uialert.

Capabilities Only Available with UI Figures

Some benefits of updating your app to use the uifigure function include:

Additional component types — UI figures support additional modern app building components, such as:
- Trees
- Spinners
- Hyperlinks
- Instrumentation components such as gauges and switches
- HTML UI components that let you embed third-party visualizations in your app
Modern layout and resize options — UI figures support grid layout managers and component auto-resize behavior as an alternative to manually specifying the Position property and writing resize code in a SizeChangedFcn callback. Using these alternatives can greatly simplify app layout code.
Additional capabilities for existing components — Components in UI figures support additional customization options, including:
- Making containers scrollable
- Styling individual table cells to change the color and font, and to add icons and format text
- Displaying table array data in table UI components

To see a list of all components supported in uifigure-based apps, see App Building Components.

Differences Between `figure`-Based and `uifigure`-Based Apps

The major differences between figure-based apps and uifigure-based apps are due to differences in the underlying Figure object configuration and unsupported functionality. Understanding these differences will help you update your figure-based app to use uifigure.

Differences in Default Configuration

Because figures created using the uifigure function are configured for app building instead of data exploration, there are some differences in the default configuration of those Figure objects when compared to figures created using the figure function. This table lists the major differences.

Category	`figure` Configuration	`uifigure` Configuration	Explanation of Difference
Menu and toolbar	The figure window has a default menu and toolbar with common data exploration functionality.	The UI figure window does not have a default menu and toolbar.	The functionality that the menu and toolbar provide is less relevant for app building than for data exploration. You can create your own custom menu and toolbar for the apps you create by using the `uimenu` and `uitoolbar` functions.
`HandleVisibility` value	The `HandleVisibility` of the figure is `'on'` by default.	The `HandleVisibility` of the UI figure is `'off'` by default.	The value of the `HandleVisibility` property controls whether the figure or the objects it contains can become the current object (for example, using `gcf` or `gca`). Many graphics functions implicitly use `gcf` or `gca` to determine the target for operations such as plotting data. The `HandleVisibility` of a UI figure is `'off'` by default so that functions do not make unwanted changes to the user interface.
Resize behavior	Resizing the figure window has no effect on the size of controls and containers such as `UIControl`, `Table`, and `Panel` objects by default.	The UI figure has a property named `AutoResizeChildren` that is set to `'on'` by default. When `AutoResizeChildren` is `'on'`, MATLAB automatically resizes objects in the UI figure window whenever the UI figure window is resized. You can set `AutoResizeChildren` to `'off'` to disable this resize behavior.	Resizing UI components when a user resizes a UI figure window enables app use at any window size. The auto-resize behavior in UI figures provides a lightweight default behavior in addition to other resize management options such as grid layout managers.
Container location, size, and units	By default, `Panel`, `ButtonGroup`, and `TabGroup` objects parented to the figure have `Units` set to `'normalized'` and occupy the full size of the figure window.	All containers and UI components parented to the UI figure have a set default location and size, specified in pixel units.	Using pixel units to manually specify the position of containers and UI components provides the most control over your app layout. If you want to automatically resize containers or components based on the size of their parent in a UI figure, create a grid layout manager using the `uigridlayout` function.

Unsupported Functionality in UI Figures

Some functionality that is supported in figures created using the figure function is not supported in figures created using the uifigure function. This table lists common scenarios and coding patterns that require extra steps or manual code changes when updating your apps to use uifigure.

Category	Not Supported	Suggested Actions
Controls created using `uicontrol`	User interface controls created using the `uicontrol` function are not supported in figures created using the `uifigure` function.	Update your app to use supported UI components. For example, use the `uibutton` function to create a push button. For more information, see Update UIControl Objects and Callbacks.
Menu and toolbar	Figures created using the `uifigure` function do not have the option to specify `MenuBar` and `ToolBar` properties.	Recreate the relevant behavior or design your own custom menu and toolbar by using the `uimenu` and `uitoolbar` functions.
Container border properties	Certain options for configuring `Panel` and `ButtonGroup` objects are available only when the object is parented to a figure created using the `figure` function: Specifying the `BorderType` property as `'etchedin'`, `'etchedout'`,`'beveledin'`, or `'beveledout'` Specifying the `ShadowColor` property Specifying the `TitlePosition` property as`'leftbottom'`, `'centerbottom'`, or `'rightbottom'`	Determine if this functionality is critical to your app before updating your app to use `uifigure`. Consider customizing container borders using supported properties, such as `BorderColor` and `BorderWidth`.
Modal dialog boxes	The `'modal'` option for `errordlg`, `warndlg`, `helpdlg`, `msgbox`, and `waitbar` has no effect when the dialog box is created for a `uifigure`-based app.	Replace calls to these functions with dialog box functions such as `uialert`, `uiconfirm`, and `uiprogressdlg`. These dialog boxes are created for use in `uifigure`-based apps and support modal options. For more information, see Update Dialog Boxes.