Control UI figure appearance and behavior for uifigure-based apps (2024)

Background color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.

For a custom color, specify an RGB triplet or a hexadecimal color code.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB^® uses in many types of plots.

Window style, specified as one of the following:

UI Figure Modal Window Style Behavior

When WindowStyle is set to 'modal', the UI figure window blocks keyboard and mouse interactions in a UI figure window that was created before it and has its Visible property set to 'on'. For instance, in this example Figure 3 is modal with respect to Figure 2 and Figure 2 is modal with respect to Figure 1.

fig1 = uifigure('Name','Figure 1');fig1.WindowStyle = 'modal';fig2 = uifigure('Name','Figure 2');fig2.WindowStyle = 'modal';fig3 = uifigure('Name','Figure 3');fig3.WindowStyle = 'modal';

The modality hierarchy is not preserved if there is a combination of modal and normal figures in the hierarchy of figures.

Unlike modal figures created with the figure function, modal figures created with the uifigure function do not block access to figures created with the figure function or the MATLAB desktop. Interactions with application windows other than MATLAB are also not blocked.

Typing Ctrl+C when a modal figure has focus causes that figure to revert to a 'normal' WindowStyle property setting. This allows the user to type at the command line.

UI figures with the WindowStyle property set to 'modal' and the Visible property set to 'off' do not behave modally until MATLAB makes them visible. Therefore, you can hide a modal window for later reuse, instead of destroying it.

Modal figures do not display menu children, built-in menus, or toolbars. But, it is not an error to create menus in a modal figure or to change the WindowStyle property setting to 'modal' on a figure with menu children. The Menu objects exist and the figure retains them. If you reset the UI figure WindowStyle property to 'normal', the menus display.

Window state, specified as one of these values:

Clicking the minimize, maximize, or restore button provided by the operating system sets the WindowState property accordingly. Pressing Ctrl+F11 (Windows^® and Linux^®) or Ctrl+Command+F (macOS) toggles the 'fullscreen' state. Setting this property on a docked figure or in MATLAB Online™ is not supported.

UI figures cannot be minimized directly from a full screen state.

Units of measurement, specified as one of the values from this table.

MATLAB measures all units from the lower left corner of the parent object.

The recommended value is 'pixels', because most MATLAB app building functionality measures distances in pixels.

This property affects the Position property. If you change the Units property, consider returning its value to the default value after completing your computation to avoid affecting other functions that assume the default value.

The order in which you specify the Units and Position properties has these effects:

Location and size of UI figure, excluding borders and title bar, specified as a four-element vector of the form [left bottom width height]. All measurements are in units specified by the Units property.

This property value is identical to the Position property value.

Resizable UI figure, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

When this property is set to 'on', the UI figure is resizable. Otherwise, it is not resizable.

Color map for UIAxes content, specified as an m-by-3 array of RGB (red, green, blue) triplets that define m individual colors.

Example: uifigure('Colormap',[1 0 1; 0 0 1; 1 1 0]) sets the color map to three colors: magenta, blue, and yellow.

MATLAB accesses these colors by their row number.

Pointer symbol, specified as one of the values in the following table or as 'custom'. The appearance of the symbol is operating-system dependent.

Custom Pointer Symbol

To create a custom pointer symbol, programmatically set the Pointer property to 'custom' and use the PointerShapeCData property to define the symbol. See the PointerShapeCData property for more information.

Limitations

Pointer symbols specified by the Pointer property do not display over HTML UI components created with the uihtml function.

Custom pointer symbol, specified as a 16-by-16 matrix (for a 16-by-16 pixel pointer), or as a 32-by-32 matrix (for a 32-by-32 pixel pointer). The figure uses this pointer symbol when you set the Pointer property to 'custom'.

Each element in the matrix defines the brightness level for 1 pixel in the pointer, where the element can have one of these values:

Element (1,1) of the matrix corresponds to the pixel in the upper left corner in the pointer.

Active pixel of the pointer, specified as a two-element vector. The vector contains the row and column indices of a particular element in the PointerShapeCData matrix that corresponds to the desired active pixel. The default value of [1 1] corresponds to the pixel in the upper left corner of the pointer.

If you specify a value outside the range of the PointerShapeCData matrix, then the pointer uses the default active pixel of [1 1] instead.

This property applies only when the Pointer property is set to 'custom'.

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

To make your app start faster, set the Visible property to 'off' for all components that do not need to appear at startup.

Changing the size of an invisible container triggers the SizeChangedFcn callback when it becomes visible.

Changing the Visible property of a container does not change the values of the Visible properties of child components. This is true even though hiding the container causes the child components to be hidden.

Target axes in the current UI figure, specified as a UIAxes, Axes, or PolarAxes object, or a graphics object such as a HeatmapChart.

In all UI figures for which axes children exist, there is always a current axes. The current axes does not have to be the topmost axes, and setting an axes to be the current axes does not restack it above all other axes. If a UI figure contains no axes, the get(gcf,'CurrentAxes') command returns an empty array.

Query the CurrentAxes property to get the current axes object without forcing the creation of an axes if one does not exist.

Current object, returned as a child object of the UI figure. MATLAB sets the CurrentObject property to the last object clicked in the UI figure.

Clicking an object whose HandleVisibility property is 'off' sets the CurrentObject property to an empty GraphicsPlaceholder array.

Current point, returned as a two-element vector. The vector contains the (x, y) coordinates of the mouse pointer, measured from the lower-left corner of the UI figure. The values are in units specified by the Units property. If the UI figure is scrollable, the coordinates are measured from the lower-left corner of the scrollable area. The scrollable area is the area that is bounded by the limits of the scroll bars.

The coordinates update when you do any of the following:

If the UI figure has a callback that responds to mouse interactions, and you trigger that callback faster than the system can execute the code, the coordinates might not reflect the actual location of the pointer. Instead, they are the location when the callback began execution.

If you use the CurrentPoint property to plot points, the coordinate values might contain rounding error.

Mouse selection type, returned as 'normal', 'extend', 'alt', or 'open'. This property provides information about the last mouse button press that occurred in the UI figure.

This table lists the possible SelectionType values and the user actions that produce those values.

Button down callback, specified as one of these values:

This callback executes when the user clicks a blank area of the UI figure.

For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Use the SelectionType property to determine whether the user pressed modifier keys.

Key-press callback, specified as one of these values:

This callback function executes when the user presses a key while the UI figure or a child component has focus. Pressing a key on a component that accepts keyboard focus (such as an edit field) does not execute the callback unless the component is disabled. You can disable a component by setting the Enable or Editable property to 'off'. In addition, you can disable a Table component without graying it out by setting the Enable property to 'inactive'.

If the user presses multiple keys at approximately the same time, MATLAB detects all the keys.

The KeyPressFcn callback can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of the KeyData object.

For more information about specifying callback property values and using callback arguments, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

The CurrentCharacter property also returns character information.

Key-release callback, specified as one of these values

This callback function executes when the user releases a key while the UI figure or a child component has focus. Releasing a key on a component that accepts keyboard focus (such as an edit field) does not execute the callback unless the component is disabled. You can disable a component by setting the Enable or Editable property to 'off'. In addition, you can disable a Table component without graying it out by setting the Enable property to 'inactive'.

This callback function can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of the KeyData object.

For more information about specifying callback property values and using callback arguments, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Close request callback, specified as one of these values:

For more information about specifying a callback property value as a function handle, cell array, or character vector, see Specify a Callback Function.

MATLAB executes this callback when the app user attempts to close the app. For example, you can code the callback to display a dialog box that asks the app user to confirm or cancel the close operation.

The default value of the CloseRequestFcn callback, 'closereq', unconditionally deletes the figure, destroying the window.

Consider calling the delete function to close the Figure in the CloseRequestFcn callback:

If the CloseRequestFcn callback does not contain a delete command, MATLAB never closes the window. You can always call the delete function to force the window to close.

Example: Code CloseRequestFcn to Display Dialog Box

This example shows how to code the close request function to display a confirmation dialog box asking the user to confirm the close operation. Save the code to a writable folder on your system.

function myCloseReq(src,event)selection = uiconfirm(src,'Close this figure?',... 'Confirm Close'); switch selection case 'OK' delete(src) case 'Cancel' return endend

Now, create a figure and specify myCloseReq for the CloseRequestFcn. Notice that the function handle does not explicitly refer to any input arguments, but the function declaration includes two input arguments. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

uifigure('CloseRequestFcn',@myCloseReq);

Close the figure window and the confirmation dialog box displays.

Window button down callback, specified as one of these values:

This callback executes when the user clicks:

For example, clicking an axes object triggers the WindowButtonDownFcn callback.

If the user clicks a UITable component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

See the list of properties for a specific graphics object to determine if it supports the ButtonDownFcn property. See Graphics Object Properties for the properties of graphics objects.

For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Window button motion callback, specified as one of these values:

Typically, this callback function executes whenever the user moves the pointer within the UI figure. However, if the user clicks and holds the mouse button and moves the pointer outside the UI figure, the WindowButtonMotionFcn callback executes while the pointer is outside the UI figure.

For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Window button up callback, specified as one of these values:

This callback executes when the user:

For example, releasing the mouse button on an axes object triggers the WindowButtonUpFcn callback.

If the user releases the mouse button on a UITable component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

See the list of properties for a specific graphics object to determine if it supports the ButtonDownFcn property. See Graphics Object Properties for the properties of graphics objects.

Button-up actions are associated with button-down actions in the UI figure. The mouse pointer must be inside the UI figure when the button-down action occurs, but it can be outside the figure when the button-up action occurs.

For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Window key-press callback, specified as one of these values:

This callback function executes when the user presses a key while the UI figure or a child component has focus. If the user presses multiple keys at approximately the same time, MATLAB detects all the keys.

This callback function can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of the KeyData object.

For more information about specifying callback property values and using callback arguments, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

The CurrentCharacter property also returns character information.

Window key-release callback, specified as one of these values

This callback function executes when the user releases a key while the UI figure or a child component has focus.

This callback function can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of the KeyData object.

For more information about specifying callback property values and using callback arguments, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Window scroll wheel callback, specified as one of these values:

This callback executes when the user moves the scroll wheel while the UI figure or any of its children have focus. However, other objects can capture scroll wheel movement and interfere with the execution of this callback.

This callback has no effect on the CurrentObject and SelectionType properties.

This callback can access specific information when the user rotates the scroll wheel. MATLAB passes this information in a ScrollWheelData object as the second argument to your callback function. This table lists the properties of the ScrollWheelData object.

For more information about specifying callback property values and using callback arguments, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.

Example: App for Changing x-Axis Limits

This example shows how to create an app that displays a plot. The user can scroll to change the limits of the x-axis. Copy and paste the following code into the editor and run it.

function scroll_wheel% Shows how to use WindowScrollWheelFcn property% f = uifigure('WindowScrollWheelFcn',@figScroll,'Name','Scroll Wheel Demo'); x = 0:.1:40; y = 4.*cos(x)./(x+2); a = axes(f); h = plot(a,x,y); title(a,'Rotate the scroll wheel') function figScroll(~,event) if event.VerticalScrollCount > 0 xd = h.XData; inc = xd(end)/20; x = [0:.1:xd(end)+inc]; re_eval(x) elseif event.VerticalScrollCount < 0 xd = h.XData; inc = xd(end)/20; % Don't let xd = 0 x = [0:.1:xd(end)-inc+.1]; re_eval(x) end end function re_eval(x) y = 4.*cos(x)./(x+2); h.YData = y; h.XData = x; a.XLim = [0 x(end)]; drawnow endend

Notice that the function handle for figScroll does not explicitly refer to any input arguments, but the function declaration includes two input arguments. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

This property is read-only.

Parent object, returned as a root object.

Children of the Figure object, returned as an empty GraphicsPlaceholder or a one-dimensional array of component objects. The children can be any component, excluding another Figure object.

You cannot add or remove a child component using the Children property. Use this property to view the list of children or to reorder the children. The order of the children in this array reflects the front-to-back order (stacking order) of the components on the screen.

To add a child to this list, set the Parent property of the child component to the Figure object.

Visibility of object handle, specified as 'off', 'callback', or 'on'. This property provides information about the visibility of the Figure object in its parent's list of children. The default value is set to 'off' to prevent the Figure object from becoming the current figure (gcf) and to prevent functions from making unwanted changes to the UI.

This table describes the effect of setting each value:

Objects are valid even if their HandleVisibility property is set to 'off'. If you have access to an object, you can set and get its properties, and pass it to any function that operates on objects.

Icon source or file, specified as a character vector, a string scalar, or an m-by-n-by-3 truecolor image array. If you specify a file name, it can be an image file name on the MATLAB path or a full path to an image file. If you plan to share an app with others, put the image file on the MATLAB path to facilitate app packaging.

Supported image formats include JPEG, PNG, GIF, and m-by-n-by-3 truecolor image array. For more information about truecolor image arrays, see Working with Image Types in MATLAB. Animated GIF files display only the first frame.

If sufficient space is not available to display the icon completely at full size, MATLAB scales down the image to fit.

Example: 'icon.png' specifies an icon file on the MATLAB path.

Example: 'C:\Documents\icon.png' specifies a full path to an image file.

Example: fig = uifigure('Icon','peppers.png') creates a UI figure using the specified icon image file.

This property is read-only.

Number of the figure, returned as an integer or empty array.

If the IntegerHandle property is set to 'off', the Number property is empty.

If IntegerHandle is 'on', the Number property is an integer. When you delete the figure, MATLAB reuses the number for the next figure.

Number title, specified as 'off' or 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

When you set this property to 'on', the title of the UI figure includes the phrase 'Figure n', where n is a number.

Both the NumberTitle and IntegerHandle properties must be set to 'on' to show the number in the title.

Use integer handle, specified as 'off' or 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

If you set the IntegerHandle property to 'on', MATLAB finds the lowest integer value that is not used by an existing figure and sets the Number property to that value. If you delete a UI figure, MATLAB can reuse its number on a new figure.

If you set the IntegerHandle property to 'off', MATLAB does not assign an integer value to the UI figure, and it sets the Number property to an empty array.

To show the number in the title bar, both IntegerHandle and NumberTitle must be set to 'on'.

This property is read-only.

Type of graphics object, returned as 'figure'.