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 theuipanel
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. WhenHandleVisibility
is'callback'
, theFigure
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 thefigure
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 andSizeChangedFcn
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.
Code | App |
---|---|
Panels in a 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"; | |
Panels in a 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"; | |
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:
In your
figure
-based app, after laying out the object, set the value of itsUnits
property to"pixels"
, and then query the value of itsPosition
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.Positionp2PixelPosition = p2.Position
p1PixelPosition = 1 1 225 300p2PixelPosition = 226 1 225 300
In your
uifigure
-based app, set thePosition
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";
Related Topics
- Update figure-Based Apps to Use uifigure
- Update UIControl Objects and Callbacks
- Update Dialog Boxes