Main Content

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:

  1. 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.

  2. Update UIControl Objects and Callbacks — Replace calls to uicontrol with analogous UI component functions, and update component properties and callbacks.

  3. 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.

Categoryfigure Configurationuifigure ConfigurationExplanation of Difference
Menu and toolbarThe 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 valueThe 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 behaviorResizing 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 unitsBy 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

As of R2022a, 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.

CategoryNot SupportedSuggested Actions
Controls created using uicontrolUser interface controls created using the uicontrol function are not supported in figures created using the uifigure function.

Update your app to use the corresponding function to create a UI component in a uifigure-based app. For example, use the uibutton function to create a push button.

For more information, see Update UIControl Objects and Callbacks.

Menu and toolbarFigures created using the uifigure function do not have the option to specify MenuBar and ToolBar properties. The default menu and toolbar in figures created using the figure function is not supported.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 BorderWidth, HighlightColor, and ShadowColor properties

  • Specifying the BorderType property as 'etchedin', 'etchedout', 'beveledin', or 'beveledout'

  • 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. There is no workaround in uifigure-based apps.
Modal dialog boxesThe '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.

Related Topics