Main Content

Update App Figure and Containers

Step 1 of 3 in Update figure-Based Apps to Use uifigure

MATLAB® provides two functions to create a figure window: figure and uifigure. 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.

The first step in updating an app that uses the figure and uicontrol functions is to update your app figure and containers. You can do this by replacing calls to figure with uifigure and then updating your container layout. Most UI containers can be parented to a figure created using either the figure or the uifigure function, and so this step often requires minimal updates to your code.

Replace Calls to figure with uifigure

To transition your app to use modern app building functionality, first replace all calls to the figure function in your app code with calls to the uifigure function:

fig = uifigure;

Specify Target Object

After updating the figure creation function calls, if you plot data or create objects in your app without explicitly specifying the target object for the operation, running your code can create additional, unexpected figure windows. To address this behavior, further update your app code using one of these options:

  • Specify the target or parent object in function calls — This is the best practice to avoid unexpected behavior. Most app building and graphics functions have an option for specifying the parent or target. For example, this code creates a panel in a UI figure by returning the Figure object as a variable and then providing that variable as the first input to the uipanel function.

    fig = uifigure;
pnl = uipanel(fig);

  • Set the HandleVisibility property value of the UI figure to 'callback' — Use this option when your code that relies on objects in your app becoming the current object is invoked only from within callback functions in your app. When HandleVisibility is 'callback', the Figure object is visible only from within callbacks or functions invoked by callbacks, and not from within functions invoked from the Command Window.

  • Set the HandleVisibility property value of the UI figure to 'on' — Use this option to specify that the UI figure behavior is the same as the default behavior for figures created with the figure function. This option is not recommended because it can result in unexpected changes to the app UI.

Adjust Container Positions

Objects such as Panel, TabGroup, and ButtonGroup objects can be parented to figures created using either the figure or uifigure function. In general, these objects behave the same way in a uifigure-based app as they do in a figure-based app. However, some container objects have differences in default Position and Units properties.

If your app contains panels, tab groups, or button groups that are mispositioned after you transition to using the uifigure function, you have multiple options to update your code:

  • Use a Grid Layout Manager — Use this option if you want to refactor your app layout using modern layout tools. You can use a grid layout manager to align and specify the resize behavior of UI components by laying them out in a grid, which can greatly simplify your layout and resize code.

  • Specify Container Positions — Use this option if you want to quickly update your positioning code or if you want to continue to manage the layout of your app using the Position property and SizeChangedFcn callbacks.

Use a Grid Layout Manager

To manage your app layout and resize behavior relative to the size of the figure window, use a grid layout manager. Create a grid layout manager in your UI figure by using the uigridlayout function, and parent your app components and containers to the grid layout manager. For more information about using a grid layout manager to lay out your app, see Lay Out Apps Programmatically.

This table shows an example of a figure-based app with two panels laid out using the Position property, and the updated uifigure-based app laid out using a grid layout manager.

CodeApp

Panels in a figure-based app, laid out using the Position property

f = figure;
f.Position = [500 500 450 300];

p1 = uipanel(f);
p1.Position = [0 0 0.5 1];
p1.BackgroundColor = "red";

p2 = uipanel(f);
p2.Position = [0.5 0 0.5 1];
p2.BackgroundColor = "blue";

A red and a blue panel in a row in a figure window

Panels in a uifigure-based app, laid out using a grid layout manager

f = uifigure;
f.Position = [500 500 450 300];

gl = uigridlayout(f,[1 2]);
gl.Padding = [0 0 0 0];
gl.ColumnSpacing = 0;

p1 = uipanel(gl);
p1.Layout.Row = 1;
p1.Layout.Column = 1;
p1.BackgroundColor = "red";

p2 = uipanel(gl);
p2.Layout.Row = 1;
p2.Layout.Column = 2;
p2.BackgroundColor = "blue";

A red and a blue panel in a row in a UI figure window

Specify Container Positions

Alternatively, you can continue to use the Position property to lay out your app. While Panel, TabGroup, and ButtonGroup objects that are parented to a figure created using the figure function use normalized units for their Position by default, these containers in a UI figure use pixel units by default instead. Pixel units are recommended for app building because most MATLAB app building functionality measures distances in pixels.

Follow these steps to update the property values of the Panel, TabGroup, and ButtonGroup objects in your app to use pixel units:

  1. In your figure-based app, after laying out the object, set the value of its Units property to "pixels", and then query the value of its Position property.

    For example, this code creates two panels laid out using normalized units, converts the units to pixels, and displays the corresponding pixel position values.

    f = figure;
f.Position = [500 500 450 300];

p1 = uipanel(f);
p1.Position = [0 0 0.5 1];
p1.BackgroundColor = "red";

p2 = uipanel(f);
p2.Position = [0.5 0 0.5 1];
p2.BackgroundColor = "blue";

p1.Units = "pixels";
p2.Units = "pixels";

p1PixelPosition = p1.Position
p2PixelPosition = p2.Position

    p1PixelPosition =

     1     1   225   300


p2PixelPosition =

   226     1   225   300

  2. In your uifigure-based app, set the Position property of each object to the equivalent pixel-based position.

    f = uifigure;
f.Position = [500 500 450 300];

p1 = uipanel(f);
p1.Position = [1 1 225 300];
p1.BackgroundColor = "red";

p2 = uipanel(f);
p2.Position = [226 1 225 300];
p2.BackgroundColor = "blue";

    A red and a blue panel in a row in a UI figure window

Related Topics

Update figure-Based Apps to Use uifigure
Next