Figure

Figure window

Description

A figure is a container for graphics or apps. Use the Figure object to modify the appearance and behavior of a figure after you create it.

Creation

There are several ways to create a Figure object:

• Create a figure configured for graphics and data exploration tasks by using the figure function. Many graphics functions create such a figure automatically.

• Create a figure configured for app building by using the uifigure function. App Designer creates such a figure automatically.

The way you create a figure affects the default property values of the Figure object. For more information, see Differences Between Figures Created Using figure and uifigure.

Properties

Window Appearance

Color — Background color

RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

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.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

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

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"
"none"	Not applicable	Not applicable	Not applicable	No color

This table lists the default color palettes for plots in the light and dark themes.

Palette	Palette Colors
"gem" — Light theme default Before R2025a: Most plots use these colors by default.
"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

WindowStyle — Window style

'docked' | 'normal' | 'modal' | 'alwaysontop'

Window style, specified as one of these values:

• 'docked' — The figure is docked into a larger container. This value is the default for figures created using the figure function; these figures are docked into a figure container by default.

  When you query the WindowStyle property, the property returns 'docked' when the figure is docked into either the desktop or a figure container. However, when you set the WindowStyle property to 'docked', the figure docks into the desktop.

• 'normal' — The figure appears in a standalone window, independent of other MATLAB^® windows. This value is the default for figures created using the uifigure function.

• 'modal' — The figure appears on top of all existing figure windows that have a normal window style, making them inaccessible as long as the top figure exists and remains modal.

  When multiple modal windows exist, the most recently created window keeps focus and stays on top of all other windows until it becomes invisible, or is returned to a normal window style, or is deleted. At that time, focus reverts to the window that last had focus.

• 'alwaysontop' — The figure appears on top of all other windows, including modal figure windows and windows from applications other than MATLAB. The other windows are still accessible.

Specifying the position of a docked figure automatically undocks the figure and sets the WindowStyle property to 'normal'.

Note

These are some important characteristics of the WindowStyle property and some recommended best practices:

• When you create figures for apps, specify the WindowStyle property. If you also want to set the Resize or Position properties of the figure, then set the WindowStyle property first.

• You can change the WindowStyle property of a figure at any time, including when the figure is visible and contains children. However on some systems, setting this property might cause the figure to flash or disappear and reappear, depending on the system's implementation of normal and modal windows. For best visual results, set the WindowStyle property at creation time or when the figure is invisible.

Modal Window Style Behavior

When WindowStyle is set to 'modal', the figure window traps all keyboard and mouse actions over all MATLAB windows as long as the windows are visible. Windows belonging to applications other than MATLAB are unaffected.

Pressing Ctrl+C when a modal figure has focus sets the WindowStyle property of that figure to 'normal'. This action allows the user to type at the command line.

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 figure's WindowStyle property to 'normal', the menus display.

WindowState — Window state

'normal' (default) | 'minimized' | 'maximized' | 'fullscreen'

Window state, specified as one of these values:

• 'normal' — The window displays in a normal state.

• 'minimized' — The window is collapsed, but you can still execute commands to get or set its properties, to add children, or to create plots in the window.

• 'maximized' — The window fills the screen. The minimize, restore, and close buttons provided by the operating system appear in the corner of the window. If the window has menus in the normal state, they are present in this state.

• 'fullscreen' — The window fills the screen. However, the minimize, restore, and close buttons provided by the operating system are hidden. If the window has menus in the normal state, they are present in this state.

Setting this property on a docked figure undocks the figure and sets the WindowState property to 'normal'.

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 the WindowState property in MATLAB Online™ is not supported.

MenuBar — Figure menu bar display

'none' (default) | 'figure'

Figure menu bar display, specified as 'none' or 'figure'. The MenuBar property enables you to display or hide the default menus at the top of a figure window. Specify 'figure' to display the menu bar. Specify 'none' to hide it.

For figures created using the figure function, setting the MenuBar property to 'figure' undocks the figure and removes the toolstrip from the window.

This property affects only default menus, and does not affect menus created using the uimenu function.

Menu bars do not appear in figures whose WindowStyle property is set to 'modal'. If a figure containing menu children is changed to 'modal', the menu children still exist in the Children property of the figure. However, the menus do not display while WindowStyle is set to 'modal'.

ToolBar — Figure toolbar display

'none' (default) | 'figure' | 'auto'

Figure toolbar display, specified as one of these values:

• 'none' — Toolbar does not display.

• 'figure' — Toolbar displays.

• 'auto' — Uses the same value as the MenuBar property.

For figures created using the figure function, setting the ToolBar property to 'figure' undocks the figure and removes the toolstrip from the window.

Toolbars do not appear in figures whose WindowStyle property is set to 'modal'. If a figure containing a toolbar is changed to 'modal', the toolbar children still exist in the Children property of the figure. However, the toolbar does not display while WindowStyle is set to 'modal'.

DockControls — Interactive figure docking

on/off logical value

Interactive figure docking, 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.

This list describes the behavior of each of the values.

• 'on' — MATLAB enables the figure dock button in the Figures toolstrip or menu bar, if the figure has one. Clicking the button docks the figure in the MATLAB desktop.

• 'off' — MATLAB disables figure dock button. You cannot set the DockControls property to 'off' if the WindowStyle is set to 'docked'.

Theme — Graphics theme

"light" | "dark" | GraphicsTheme object

Since R2025a

Graphics theme, specified as "light", "dark", or a GraphicsTheme object, and stored as a GraphicsTheme object.

Light Theme Appearance	Dark Theme Appearance

As an alternative to setting the Theme property, you can call the theme function.

To determine whether the current theme is a light or dark theme, query the Theme property to get the GraphicsTheme object. Then query the BaseColorStyle property of the GraphicsTheme object. This second query returns a value of 'light' or 'dark'.

f = figure;
gtobject = f.Theme;
figtheme = gtobject.BaseColorStyle

ThemeMode — Graphics theme selection

"auto" (default) | "manual"

Since R2025a

Graphics theme selection, specified as one of these values:

• "auto" — Use the figure theme specified in the MATLAB Settings window. By default, the figure theme is set to MATLAB Desktop, which sets the theme of all figures to match the theme of the MATLAB desktop.

• "manual" — Use the theme specified in the Theme property and do not change it even if the MATLAB desktop theme changes.

The ThemeMode property automatically changes to "manual" when you set the theme explicitly (for example, by setting the Theme property or calling the theme function).

Position and Size

Position — Location and size of figure, excluding borders, figure tools, and title bar

[left bottom width height]

Location and size of the figure, excluding borders, figure tools, and title bar, specified as a four-element vector of the form [left bottom width height].

This table describes each element in the vector.

Element	Description
left	Distance from the left edge of the primary display to the inner left edge of the window. This value can be negative on systems that have more than one monitor. If the figure is docked, then this value is relative to its container.
bottom	Distance from the bottom edge of the primary display to the inner bottom edge of the window. This value can be negative on systems that have more than one monitor. If the figure is docked, then this value is relative to its container.
width	Distance between the right and left inner edges of the window.
height	Distance between the top and bottom inner edges of the window.

All measurements are in units specified by the Units property.

For figures that are docked into a figure container, setting the Position property undocks the figure and sets the WindowStyle property to 'normal'.

To position the full window, including the borders, figure tools, and title bar, use the OuterPosition property.

Note

The Windows operating system enforces a minimum window width and a maximum window size. If you specify a figure size outside of those limits, the displayed figure conforms to the limits instead of the size you specified.

Units — Units of measurement

'pixels' (default) | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

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

Units Value	Description
'pixels' (default)	Pixels. On Windows and Macintosh systems, the size of a pixel is 1/96th of an inch. This size is independent of your system resolution. On Linux systems, the size of a pixel is determined by your system resolution.
'normalized'	These units are normalized with respect to the parent container. The lower-left corner of the container maps to (0,0) and the upper-right corner maps to (1,1).
'inches'	Inches.
'centimeters'	Centimeters.
'points'	Points. One point equals 1/72nd of an inch.
'characters'	These units are based on the default uicontrol font of the graphics root object: Character width = width of the letter x. Character height = distance between the baselines of two lines of text. To access the default uicontrol font, use get(groot,'defaultuicontrolFontName') or set(groot,'defaultuicontrolFontName').

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

Note

App Designer supports only pixel units. To create a container that is sized relative to its parent container in App Designer, use a grid layout manager or create an app with auto-reflow. For more information, see Manage Resizable Apps in App Designer.

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:

• If you specify the Units before the Position property, then MATLAB sets Position using the units you specify.

• If you specify the Units property after the Position property, MATLAB sets the position using the default Units. Then, MATLAB converts the Position value to the equivalent value in the units you specify.

InnerPosition — Location and size of figure, excluding borders, figure tools, and title bar

[left bottom width height]

Location and size of figure, excluding borders, figure tools 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.

OuterPosition — Location and size of figure, including borders, figure tools, and title bar

[left bottom width height]

Location and size of figure, including borders, figure tools, and title bar, specified as a four-element vector of the form [left bottom width height].

This table describes each element in the vector.

Element	Description
left	Distance from the left edge of the primary display to the outer left edge of the figure window. This value can be negative on systems that have more than one monitor. If the figure is docked, then this value is relative to its container.
bottom	Distance from the bottom edge of the primary display to the outer bottom edge of the figure window. This value can be negative on systems that have more than one monitor. If the figure is docked, then this value is relative to its container.
width	Distance between the right and left outer edges of the window.
height	Distance between the top and bottom outer edges of the window.

All measurements are in units specified by the Units property.

For figures that are docked into a figure container, setting the OuterPosition property undocks the figure and sets the WindowStyle property to 'normal'.

Note

The Windows operating system enforces a minimum window width and a maximum window size. If you specify a figure size outside of those limits, the displayed figure conforms to the limits instead of the size you specified.

Resize — Resizable

'on' (default) | on/off logical value

Resizable 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 figure is resizable. Otherwise, it is not resizable.

For figures that are docked into a figure container, setting the Resize property undocks the figure and sets the WindowStyle property to 'normal'.

AutoResizeChildren — Automatically resize children

on/off logical value

Automatically resize children, 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.

• 'on' — Child components automatically resize when the container resizes. This value is the default for figures created using the uifigure function.

• 'off' — Child components do not resize. This value is the default for figures created using the figure function.

The AutoResizeChildren property affects direct children of the container, not children inside nested containers.

Some child components do not resize automatically when AutoResizeChildren is 'on'. For example, labels, buttons, and containers that contain only non-resizing components do not resize.

To customize the resize behavior, either add a grid layout manager to the container, or set the AutoResizeChildren property to 'off' and create a SizeChangedFcn callback for the container. For more information, see Manage Resizable Apps in App Designer.

To disable resizing of an app, set the Resize property of the figure to 'off'.

It is recommended to specify AutoResizeChildren as 'on' only in apps that are laid out using pixel units. Enabling automatic resizing in apps that are laid out using non-pixel units might cause unexpected behavior.

Plotting

Colormap — Color map for axes content of figure

parula (default) | m-by-3 array of RGB triplets

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

Example: figure('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.

Color maps affect the rendering of objects created with the surface, image, and patch functions, but generally do not affect other graphics objects.

When you set the Colormap property of the figure, then axes and charts in the figure use the same colormap.

Alphamap — Transparency map for axes content

array of 64 values from 0 to 1 (default) | array of finite alpha values from 0 to 1

Transparency map for axes content, specified as an array of finite alpha values that progress linearly from 0 to 1. The size of the array can be m-by-1 or 1-by-m. MATLAB accesses alpha values by their index in the array. Alphamaps can be any length.

Alphamaps affect the rendering of objects created with the surface, image, and patch functions, but do not affect other graphics objects.

When you set the Alphamap property of the figure, then axes and charts in the figure use the same alpha map.

NextPlot — Directive on how to add next plot

'add' (default) | 'new' | 'replace' | 'replacechildren'

Directive on how to add next plot, specified as 'add', 'new', 'replace', or 'replacechildren'.

This property has an effect only if the figure can become the current figure (that is, if the HandleVisibility property of the figure is "on").

This table describes the effect of each value.

Property Value	Effect
'new'	Creates a new figure and uses it as the current figure.
'add'	Adds new graphics objects without clearing or resetting the current figure.
'replacechildren'	Removes all axes objects that are not hidden before adding new objects. Does not reset figure properties. Equivalent to using the clf command.
'replace'	Removes all axes objects and resets figure properties to their defaults before adding new graphics objects. Equivalent to using the clf reset command.

Consider using the newplot function to handle the NextPlot property. For more information, see the axes NextPlot property and Prepare Figures and Axes for Graphs.

Printing and Exporting

PaperPosition — Figure size and location on page when printing or saving

four-element vector of the form [left bottom width height]

Figure size and location on page when printing or saving, specified as a four-element vector of the form [left bottom width height].

• left and bottom values — Control the distance from the lower left corner of the page to the lower left corner of the figure. These values are ignored when saving a figure to a nonpage format, such as a PNG or EPS format.

• width and height values — Control the figure size. If the width and height values are too large, then the figure might not reach the specified size. If the figure does not reach the specific size, then any UI components on the figure, such as a UI control or a UI table, might not save or print as expected.

The PaperUnits property determines the units of measurement of the PaperPosition values. Consider setting the PaperUnits property to 'normalized'. This setting enables MATLAB to automatically size the figure to occupy the same relative amount of the printed page, regardless of the page size.

Example: figure('PaperPosition',[.25 .25 8 6]) set the figure’s size and location for printing to [.25 .25 8 6].

PaperPositionMode — Directive to use displayed figure size when printing or saving

'auto' (default) | 'manual'

Directive to use displayed figure size when printing or saving, specified as either 'auto' or 'manual'.

• 'auto' — Printed or saved figure size matches the displayed figure size. The width and height values of the PaperPosition property equal the figure size on the display. The left and bottom values center the figure. If the figure size changes on the display, the PaperPosition property automatically updates to the appropriate size and location values.

• 'manual' — Printed or saved figure size might not match the displayed figure size. Use this option if you want to print or save the figure using a size that differs from the display, or if you do not want the figure centered on the printed or saved page. Set the PaperPosition property to the desired size and location. If the figure size changes on the display, the PaperPosition property does not automatically update.

To generate output that has the same size and resolution (DPI) as the displayed figure, set the PaperPositionMode property of the figure to 'auto' and save the figure using print with the -r0 option. The -r0 option ensures that the output resolution is the same as the display resolution. If the resolutions are different, then the generated output size matches the displayed figure size in measured units (inches, centimeters, points), but not in pixels. For example, if the display resolution is 100 DPI, then a 4-by-5 inch figure is 400-by-500 pixels. If the output resolution is 200 DPI, then the printed or saved figure is the same size in inches, but 800-by-1000 pixels.

PaperSize — Custom page size

two-element vector of the form [width height]

Custom page size when printing the figure or saving it to a paged format (PDF and PostScript^® formats), specified as a two-element vector of the form [width height]. In the United States, the default value is [8.5 11]. In Europe and Asia, the default value is [21 29.7].

Note

If you are saving the figure to a file, the PaperSize property only affects PDF and PostScript file formats. Other file formats ignore this property. Use the PaperPosition property to control the size of the saved figure.

The PaperUnits property determines the units of measurement for the PaperSize property. You cannot set the PaperSize property if the PaperUnits property is set to 'normalized'. Attempting to do so results in an error.

Specifying the PaperSize property sets the PaperType property to the corresponding type, if one exists, or to 'custom' otherwise.

PaperUnits — Units used for PaperSize and PaperPosition

'inches' | 'centimeters' | 'normalized' | 'points'

Units used for PaperSize and PaperPosition, specified as one of these values:

• 'inches' — Value in inches. This is the default when the locale is the United States.

• 'normalized' — Normalized units. The lower left corner of the page maps to (0,0) and the upper right corner maps to (1,1).

• 'centimeters' — Value in centimeters. This is the default when the locale is Europe or Asia.

• 'points' — Value in points. One point equals 1/72 of an inch.

Note

If you change the value of the PaperUnits property, it is good practice to return the property to its original value after completing your computation so as not to affect other functions that assume the PaperUnits property has not changed.

PaperOrientation — Orientation of page

'portrait' (default) | 'landscape'

Orientation of page when printing figure or saving it to a paged format (PDF and PostScript formats), specified as one of these values:

• 'portrait' — Orient the longest page dimension vertically.

• 'landscape' — Orient the longest page dimension horizontally.

See the orient function for more information.

Note

When using File > Save As, only PDF and full-page PS formats use the PaperOrientation property. Other formats ignore these values.

PaperType — Standard page sizes

'usletter' | 'uslegal' | 'tabloid' | 'a0' | 'a1' | 'a2' | 'a3' | ...

Standard page sizes when printing the figure or saving it to a paged format (PDF and PostScript formats), specified as one of the values in this table. Specifying the PaperType property sets the PaperSize property to the corresponding page size.

Value	Page Size (Width x Height)
'usletter'	8.5-by-11 in (default in US)
'uslegal'	8.5-by-14 in
'tabloid'	11-by-17 in
'a0'	84.1-by-118.9 cm
'a1'	59.4-by-84.1 cm
'a2'	42-by-59.4 cm
'a3'	29.7-by-42 cm
'a4'	21-by-29.7 cm (default in Europe and Asia)
'a5'	14.8-by-21 cm
'b0'	102.9-by-145.6 cm
'b1	72.8-by-102.8 cm
'b2'	51.4-by-72.8 cm
'b3'	36.4-by-51.4 cm
'b4'	25.7-by-36.4 cm
'b5'	18.2-by-25.7 cm
'arch-a'	9-by-12 in
'arch-b'	12-by-18 in
'arch-c'	18-by-24 in
'arch-d'	24-by-36 in
'arch-e'	36-by-48 in
'a'	8.5-by-11 in
'b'	11-by-17 in
'c'	17-by-22 in
'd'	22-by-34 in
'e'	34-by-43 in
'<custom>'	Custom page size. Specifying a non-standard page size using the PaperSize property sets PaperType to this value.

Mouse Pointer

Pointer — Pointer symbol

'arrow' (default) | 'ibeam' | 'crosshair' | 'watch' | 'topl' | 'custom' | ...

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

Value	Resulting Symbol (System Dependent)
'arrow'
'ibeam'
'crosshair'
'watch' (busy system)
'topl' or 'botr'
'topr' or 'botl'
'circle'
'cross'
'fleur'
'left' or 'right'
'top' or 'bottom'
'hand'

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.

PointerShapeCData — Custom pointer symbol

16-by-16 matrix (default) | 32-by-32 matrix

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:

• 1 — Black pixel.

• 2 — White pixel.

• NaN — Transparent pixel, such that underlying screen shows through.

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

PointerShapeHotSpot — Active pixel of pointer

[1 1] (default) | two-element vector

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

Interactivity

Visible — State of visibility

'on' (default) | on/off logical value

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.

• 'on' — Display the object.

• 'off' — Hide the object without deleting it. You still can access the properties of an invisible UI component.

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.

CurrentAxes — Target axes in current figure

Axes object | UIAxes object | PolarAxes object | graphics object

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

In all 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 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.

CurrentObject — Current object

empty GraphicsPlaceholder array (default) | child object of figure

Current object, returned as a child object of the figure. MATLAB sets the CurrentObject property to the last object clicked in the figure. This object is the front-most object in the view.

The HitTest property of the child object controls whether that object can become the CurrentObject.

Clicking an object whose HandleVisibility property is 'off' sets the CurrentObject property to an empty GraphicsPlaceholder array. To avoid returning the empty array when users click a hidden object, set HitTest property of the hidden object to 'off'.

Use the gco command as an alternative for getting the value of this property.

CurrentPoint — Current point

two-element vector

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 figure. The values are in units specified by the Units property. If the 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:

• Press the mouse button within the figure.

• Release the mouse button after pressing it within the figure.

• Press the mouse button within the figure, and then release it outside the figure.

• Rotate the scroll wheel within the figure.

• Move the mouse within the figure (without pressing any buttons), as long as the WindowButtonMotionFcn property is not empty.

If the 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.

CurrentCharacter — Current character

'' (default) | character

Current character, returned as the character of the last key pressed. This property updates when the figure has focus while the user presses a key.

SelectionType — Mouse selection type

'normal' (default) | 'extend' | 'alt' | 'open'

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

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

Value	Corresponding Action
'normal'	Click the left mouse button.
'extend'	Any of the following: Shift-click the left mouse button. Click the middle mouse button. Click both left and right mouse buttons.
'alt'	Either of the following: Control-click the left mouse button. Click the right mouse button.
'open'	Double-click any mouse button.

Scrollable — Ability to scroll

'off' (default) | on/off logical value

Ability to scroll, 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.

Setting this property to 'on' enables scrolling within the container. However, there are additional requirements:

• The child components in the container must occupy a larger area than the container can display at one time.

• Components that do not fit in the container must be above or to the right of the container. You cannot scroll to components that are below or to the left of the container.

• If the container contains a grid layout manager, the Scrollable property of the container has no effect. To enable scrolling, instead set the Scrollable property of the GridLayout object to 'on'.

Certain types of charts and axes do not support scrollable containers. However, you can place the chart or axes in a nonscrollable panel, and then place the panel in the scrollable container. For more information, see Display Graphics in App Designer.

ContextMenu — Context menu

empty GraphicsPlaceholder array (default) | ContextMenu object

Context menu, specified as a ContextMenu object created with the uicontextmenu function. Use this property to display a context menu when you right-click on a figure.

Common Callbacks

ThemeChangedFcn — Theme changed callback

'' (default) | function handle | cell array | character vector

Since R2025a

Theme changed callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the theme of the figure changes. For example, this callback executes in all of these situations:

• When you programmatically change the theme by calling the theme function or setting the Theme property of the Figure object

• When you change the figure theme using the Figure toolstrip

• When you apply a different theme in the MATLAB settings that changes the figure theme

This callback function can access specific information about the figure theme change. MATLAB passes this information in a ThemeChangedData object as the second argument to your callback function, often specified as event. You can query the object’s properties using dot notation. For example, event.Theme returns the new figure theme as a GraphicsTheme object. The ThemeChangedData object is not available to callback functions specified as character vectors.

This table lists the properties of the ThemeChangedData object.

Property	Value
Theme	New figure theme, returned as a GraphicsTheme object. Query the BaseColorStyle property of the GraphicsTheme object to return the new theme type as "light" or "dark". themeobj = event.Theme; themeval = themeobj.BaseColorStyle;
PreviousTheme	Previous figure theme, returned as a GraphicsTheme object. Query the BaseColorStyle property of the GraphicsTheme object to return the previous theme type as "light" or "dark". themeobj = event.PreviousTheme; themeval = themeobj.BaseColorStyle;
Source	Figure object that executes the callback
EventName	'ThemeChanged'

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

ButtonDownFcn — Button down callback

'' (default) | function handle | cell array | character vector

Button down callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

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

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

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

CreateFcn — Creation function

'' (default) | function handle | cell array | character vector

Object creation function, specified as one of these values:

• Function handle.

• Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callbacks in App Designer.

This property specifies a callback function to execute when MATLAB creates the object. MATLAB initializes all property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Setting the CreateFcn property on an existing component has no effect.

If you specify this property as a function handle or cell array, you can access the object that is being created using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

DeleteFcn — Deletion function

'' (default) | function handle | cell array | character vector

Object deletion function, specified as one of these values:

• Function handle.

• Cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector, see Callbacks in App Designer.

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being deleted using the first argument of the callback function. Otherwise, use the gcbo function to access the object.

Keyboard Callbacks

KeyPressFcn — Key-press callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user presses a key while the figure has focus. Pressing a key on a UI 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 or UIControl 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.

Property	Description	Examples:
		a	=	Shift	Shift-a
Character	The character that appears as a result of pressing the key or keys. Pressing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.	'a'	'='	''	'A'
Modifier	A cell array containing the names of the modifier keys pressed, such as 'control', 'alt', or 'shift'. If no modifier keys are pressed, the cell array is empty.	{1x0 cell}	{1x0 cell}	{'shift'}	{'shift'}
Key	The key pressed, identified by the lowercase label on the key (such as 'pageup'), or a descriptive word (such as 'space').	'a'	'equal'	'shift'	'a'
Source	The object that has focus when the key is pressed.	Figure object	Figure object	Figure object	Figure object
EventName	The action that caused the callback function to execute.	'KeyPress'	'KeyPress'	'KeyPress'	'KeyPress'

For more information about specifying callback property values and using callback arguments, see Specify a Callback Function.

The CurrentCharacter property also returns character information.

KeyReleaseFcn — Key-release callback

'' (default) | function handle | cell array | character vector

Key-release callback, specified as one of these values

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user releases a key while the figure 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 or UIControl 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.

Property	Description	Examples:
		a	=	Shift	Shift-a
Character	The character that corresponds to the key or keys that are released. Pressing and releasing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.	'a'	'='	''	'A'
Modifier	A cell array containing the names of the modifier keys pressed, such as 'control', 'alt', or 'shift'. If no modifier keys are released, the cell array is empty.	{1x0 cell}	{1x0 cell}	{'shift'}	{'shift'}
Key	The key released, identified by the lowercase label on the key (such as 'pageup'), or a descriptive word (such as 'space').	'a'	'equal'	'shift'	'a'
Source	The object that has focus when the key is released.	Figure object	Figure object	Figure object	Figure object
EventName	The action that caused the callback function to execute.	'KeyRelease'	'KeyRelease'	'KeyRelease'	'KeyRelease'

For more information about specifying callback property values and using callback arguments, see Specify a Callback Function.

Window Callbacks

CloseRequestFcn — Close request callback

'closereq' (default) | function handle | cell array | character vector

Close request callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

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:

• In App Designer, call delete(app).

• For other figures, call delete(f), where f is the Figure object.

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 
end
end

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

SizeChangedFcn — Size changed callback

'' (default) | function handle | cell array | character vector

Size changed callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

Define this callback to customize the layout of the figure contents when the size of the figure changes (for example, when you resize the window). In the callback, write code to adjust the Position property of the child components.

Note

The SizeChangedFcn callback will not execute unless the AutoResizeChildren property of the figure is set to 'off'. In App Designer, you can make the SizeChangedFcn executable by selecting the container and clearing the AutoResizeChildren check box in the component tab of the Component Browser.

The SizeChangedFcn callback executes when:

• The figure becomes visible for the first time.

• The figure is visible while its size changes.

• The figure becomes visible for the first time after its size changes. This situation occurs when the size changes while the figure is invisible, and then it becomes visible later.

Other important points to consider when defining a SizeChangedFcn callback:

• Consider delaying the display of the figure until after all the variables that the SizeChangedFcn uses are defined. This practice can prevent the SizeChangedFcn callback from returning an error. To delay the display of the figure, set its Visible property to 'off'. Then, set the Visible property to 'on' after you define the variables that your SizeChangedFcn callback uses.

• If your figure contains nested containers, they resize from the inside out.

• To access the figure that is resizing from within the SizeChangedFcn, refer to the source object (the first input argument in the callback).

Alternate ways to specify resize behavior are to create a GridLayout object or use the auto-reflow options in App Designer. These options can be easier to use than SizeChangedFcn callbacks. However, there are some advantages that SizeChangedFcn callbacks have over these options. For example, you can use a SizeChangedFcn callback to:

• Resize a component up to a minimum or maximum size that you define.

• Implement non-linear resize behavior.

WindowButtonDownFcn — Window button down callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the user clicks any of these locations:

• A blank area of the figure

• A UI component within the figure

• A graphics object within the figure that supports the ButtonDownFcn property

• A UIAxes object

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

If the user clicks a Table component, the callback does not execute unless the Enable property of the table 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.

WindowButtonMotionFcn — Window button motion callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

Typically, this callback function executes whenever the user moves the pointer within the figure. However, if the user clicks and holds the mouse button and moves the pointer outside the figure, the WindowButtonMotionFcn callback executes while the pointer is outside the 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.

WindowButtonUpFcn — Window button up callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the user releases the mouse button on any of these locations:

• A blank area of the figure

• A UI component within the figure

• A graphics object within the figure that supports the ButtonDownFcn property

• A UIAxes object

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

If the user releases the mouse button on a Table component, the callback does not execute unless the Enable property of the table 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 figure. The mouse pointer must be inside the 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.

WindowKeyPressFcn — Window key-press callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user presses a key while the 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.

Property	Description	Examples:
		a	=	Shift	Shift-a
Character	The character that appears as a result of pressing the key or keys. Pressing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.	'a'	'='	''	'A'
Modifier	A cell array containing the names of the modifier keys pressed, such as 'control', 'alt', or 'shift'. If no modifier keys are pressed, the cell array is empty.	{1x0 cell}	{1x0 cell}	{'shift'}	{'shift'}
Key	The key pressed, identified by the lowercase label on the key (such as 'pageup'), or a descriptive word (such as 'space').	'a'	'equal'	'shift'	'a'
Source	The object that has focus when the key is pressed.	Figure object	Figure object	Figure object	Figure object
EventName	The action that caused the callback function to execute.	'WindowKeyPress'	'WindowKeyPress'	'WindowKeyPress'	'WindowKeyPress'

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.

WindowKeyReleaseFcn — Window key-release callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback function executes when the user releases a key while the 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.

Property	Description	Examples:
		a	=	Shift	Shift-a
Character	The character that corresponds to the key or keys that are released. Pressing and releasing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.	'a'	'='	''	'A'
Modifier	A cell array containing the names of the modifier keys pressed, such as 'control', 'alt', or 'shift'. If no modifier keys are released, the cell array is empty.	{1x0 cell}	{1x0 cell}	{'shift'}	{'shift'}
Key	The key released, identified by the lowercase label on the key (such as 'pageup'), or a descriptive word (such as 'space').	'a'	'equal'	'shift'	'a'
Source	The object that has focus when the key is released.	Figure object	Figure object	Figure object	Figure object
EventName	The action that caused the callback function to execute.	'WindowKeyRelease'	'WindowKeyRelease'	'WindowKeyRelease'	'WindowKeyRelease'

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

WindowScrollWheelFcn — Window scroll wheel callback

'' (default) | function handle | cell array | character vector

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

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the user moves the scroll wheel while the 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.

Property	Contents
VerticalScrollCount	A positive or negative number that indicates the direction and number of scroll wheel clicks. Scrolling down returns 1. Scrolling up returns -1.
VerticalScrollAmount	A constant value of 3.
Source	Object that executes the callback.
EventName	'WindowScrollWheel'.

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
   end
end

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.

Callback Execution Control

Interruptible — Callback interruption

'on' (default) | on/off logical value

Callback interruption, 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.

This property determines if a running callback can be interrupted. There are two callback states to consider:

• The running callback is the currently executing callback.

• The interrupting callback is a callback that tries to interrupt the running callback.

MATLAB determines callback interruption behavior whenever it executes a command that processes the callback queue. These commands include drawnow, figure, uifigure, getframe, waitfor, and pause.

If the running callback does not contain one of these commands, then no interruption occurs. MATLAB first finishes executing the running callback, and later executes the interrupting callback.

If the running callback does contain one of these commands, then the Interruptible property of the object that owns the running callback determines if the interruption occurs:

• If the value of Interruptible is 'off', then no interruption occurs. Instead, the BusyAction property of the object that owns the interrupting callback determines if the interrupting callback is discarded or added to the callback queue.

• If the value of Interruptible is 'on', then the interruption occurs. The next time MATLAB processes the callback queue, it stops the execution of the running callback and executes the interrupting callback. After the interrupting callback completes, MATLAB then resumes executing the running callback.

Note

Callback interruption and execution behave differently in these situations:

• If the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

• If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

• If the interrupting callback is owned by a Timer object, then the callback executes according to schedule regardless of the Interruptible property value.

Note

When an interruption occurs, MATLAB does not save the state of properties or the display. For example, the object returned by the gca or gcf command might change when another callback executes.

BusyAction — Callback queuing

'queue' (default) | 'cancel'

Callback queuing, specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

• The running callback is the currently executing callback.

• The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property determines callback queuing behavior only when both of these conditions are met:

• The running callback contains a command that processes the callback queue, such as drawnow, figure, uifigure, getframe, waitfor, or pause.

• The value of the Interruptible property of the object that owns the running callback is 'off'.

Under these conditions, the BusyAction property of the object that owns the interrupting callback determines how MATLAB handles the interrupting callback. These are possible values of the BusyAction property:

• 'queue' — Puts the interrupting callback in a queue to be processed after the running callback finishes execution.

• 'cancel' — Does not execute the interrupting callback.

HitTest — Ability to become current object

'on' (default) | on/off logical value

Ability to become current object, 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.

• 'on' — Sets the current object to the Figure object when the user clicks the figure. Both the CurrentObject property of the Figure and the gco function return the Figure as the current object.

• 'off' — The current object does not update when the user clicks the figure.

BeingDeleted — Deletion status

Read-only: on/off logical value

This property is read-only.

Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState.

MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

Check the value of the BeingDeleted property to verify that the object is not about to be deleted before querying or modifying it.

Parent/Children

Parent — Parent object

Read-only: root object

This property is read-only.

Parent object, returned as a root object.

Children — Children of Figure object

empty GraphicsPlaceholder array (default) | 1-D array of objects

Children of the Figure object, returned as an empty GraphicsPlaceholder or a 1-D array of objects.

You cannot add or remove a child object 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 objects on the screen.

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

Objects with their HandleVisibility property set to 'off' are not listed in the Children property.

HandleVisibility — Visibility of figure object

'off' | 'callback' | 'on'

Visibility of figure object, specified as 'off', 'callback', or 'on'. This property provides information about the visibility of the Figure object in its parent's list of children.

This table describes the effect of setting each value.

HandleVisibility Value	Description
'off'	This value is the default for figures created using the uifigure function. The Figure object is not visible from callback functions or functions that execute in the Command Window. In addition, the object is: Not visible in the lists returned by the graphics root Children or CurrentFigure properties. Not returned by functions that access objects by searching the object hierarchy or querying object properties. These functions include gcf, gco, get, findobj, clf, and close. This option prevents callback functions and functions invoked from the command line from targeting the object and making unintended changes to the UI.
'callback'	The Figure object is visible only from within callbacks or functions invoked by callbacks, but not from within functions invoked from the Command Window. In addition, the object is not visible in the lists returned by the graphics root Children or CurrentFigure properties. This option blocks access to the object at the command line, but allows callback functions to access it.
'on'	This value is the default for figures created using the figure function. The Figure object is always visible.

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.

Identifiers

Name — Name

character vector | string scalar

Name of the figure, specified as a character vector or a string scalar.

In figures created using the figure function, the default name is 'Figure n', where n is an integer. When you specify the Name property, the title of the figure becomes 'Figure n: name'. If you want only the Name value to appear, set IntegerHandle or NumberTitle to 'off'.

In figures created programmatically using the uifigure function, the default name is ''.

In App Designer, the default name is 'MATLAB App'.

Example: figure("Name","Results") sets the name of the figure to "Results".

Icon — Icon source or file

'' (default) | character vector | string scalar | m-by-n-by-3 truecolor image array

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.

Number — Number

Read-only: integer | []

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.

NumberTitle — Use number title

on/off logical value

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 both the NumberTitle and IntegerHandle properties are set to 'on', the title of the figure includes the phrase 'Figure n', where n is a number.

IntegerHandle — Use integer handle

on/off logical value

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

FileName — Filename

character vector | string scalar

Filename for saving the figure, specified as a character vector or a string scalar. Apps created using GUIDE use this property to store the name of the UI layout file associated with the app.

Type — Type of graphics object

Read-only: 'figure'

This property is read-only.

Type of graphics object, returned as 'figure'.

Tag — Object identifier

'' (default) | character vector | string scalar

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value to serve as an identifier for an object. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

UserData — User data

[] (default) | array

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data instead of using the UserData property. For more information, see Share Data Within App Designer Apps.

Object Functions

scroll	Scroll to location within UI component
focus	Give focus to UI component

Examples

Change Figure Size

Create a default UI figure.

fig = uifigure;

Get the location, width, and height of the figure.

fig.Position

ans =

   681   559   560   420

This means that the figure window is positioned 681 pixels to the right and 559 pixels above the bottom left corner of the primary display, and is 560 pixels wide and 420 pixels tall.

Halve the figure width and height by adjusting the third and fourth elements of the position vector.

fig.Position(3:4) = [280 210];

More About

Differences Between Figures Created Using figure and uifigure

The default configuration of a Figure object depends on how the figure is created. Differences in the default configuration exist because figures created using the uifigure function are configured for app building, whereas figures created using the figure function are configured for data exploration and visualization. This table lists the major differences.

Category	figure Configuration	uifigure Configuration	Explanation for Difference
Window grouping	The figure is docked in a figure container, and you can navigate between different figures using tabs or by tiling figures in the figure container. The WindowStyle property is 'docked'.	The UI figure is undocked as its own standalone window without a figure container. The WindowStyle property is 'normal'.	The figure container provides a way to manage, edit, and lay out multiple figure windows to compare data and graphics. This functionality is less relevant for apps.
Figure tools	The figure has a toolstrip with common data exploration functionality by default.	The UI figure does not have a toolstrip, toolbar, or menu bar by default.	The functionality that the figure toolstrip provides is more relevant for data exploration than for apps. In UI figures, you can create a custom toolbar and menu by using the uitoolbar and uimenu functions.
Figure size	The figure is a larger size by default.	The UI figure is a smaller size by default.	The figure is sized to provide a good starting point for the types of tasks it is designed for. You can modify the size of a figure by setting its Position property.
Ability to become current figure	The HandleVisibility property is 'on' by default. The figure and the objects it contains can become the current object.	The HandleVisibility property is 'off' by default. The UI figure and the objects it contains cannot become the current object.	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 property of a UI figure is 'off' by default so that functions do not make unwanted changes to the app interface.
Resize behavior	The AutoResizeChildren property is 'off' by default. Resizing the figure window has no effect on the size of controls and containers that use pixel units by default, such as Table and UIControl objects.	The AutoResizeChildren property is 'on' by default. MATLAB automatically resizes UI components in the UI figure window whenever the window is resized.	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	Panel, ButtonGroup, and TabGroup objects parented to the figure occupy the full size of the figure window, and have Units set to 'normalized'.	All containers and UI components parented to the UI figure have a set default location and size, and have Units set to 'pixels'.	Most data exploration functionality uses normalized units, whereas most app building functionality uses pixel units. In an app, 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.

Version History

Introduced before R2006a

R2025a: Control figure theme using Theme and ThemeChangedFcn properties

Choose a theme for a figure by setting the Theme property. When you set this property, the ThemeMode property automatically changes from "auto" to "manual" so that your theme is preserved.

You can write a callback function that executes when the theme changes by setting the ThemeChangedFcn property to a function handle.

R2025a: Figures created using figure function are docked into figure container

When you call the figure function or a graphics function that creates a figure, the figure appears as a tab in a figure container. This figure grouping provides improved window management and the ability to compare and arrange figures.

As a result of this change, these default property values differ from previous releases.

Property	Default Value (R2024b and earlier)	Default Value (Starting in R2025a)
WindowStyle	'normal'	'docked'
Position, InnerPosition, and OuterPosition	The first two elements of the position vector are relative to the left and bottom edges of the primary display.	The first two elements of the position vector are always [1 1] because the location is returned relative to the figure container.

These actions undock a figure from the figure container:

• Setting the WindowStyle property to 'normal'

• Setting a Figure property that modifies the size, location, or window behavior of the figure, such as Position, Resize, or WindowState

In addition, the figure appears with a toolstrip instead of a menu bar and toolbar. The figure toolstrip provides improved options for interacting with plots and data in a figure.

However, apps and saved figures that modify the figure menu bar or toolbar (for example, by setting the ToolBar property of the Figure object) continue to display the menu bar and toolbar instead of the toolstrip. If you have a figure that relies on menu bar or toolbar functionality, you can specify that the figure display the menu bar or toolbar instead of the toolstrip by setting the figure MenuBar or ToolBar properties.

f = figure;
f.MenuBar = "figure";
f.ToolBar = "figure";

R2025a: Set additional properties for figures

Figure objects created using the figure function include these additional properties:

• AutoResizeChildren

• Scrollable

• Icon

In addition, you can set the WindowStyle property to "alwaysontop".

Figure objects created using the uifigure function include these additional properties:

• MenuBar

• ToolBar

• DockControls

In addition, you can set the WindowStyle property to "docked".

R2025a: Scroll event data for WindowScrollWheelFcn callback returns updated scroll count values

When you specify a WindowScrollWheelFcn callback function for a figure created using the figure function, the callback event data returns different values in some cases. This table describes the differences.

Event Data Property	R2024b and Earlier	Starting in R2025a
VerticalScrollCount	A positive or negative number that indicates the direction and number of scroll wheel clicks. Scrolling down returns a positive value. Scrolling up returns a negative value. The vertical scroll count is the sum of all scroll wheel clicks that occurred since the last time the callback executed. Typically, the value is 1 or -1. However, the scroll count can have a larger magnitude if the WindowScrollWheelFcn callback takes a long time to return, or if the user spins the scroll wheel very fast.	A positive or negative number that indicates the direction of scrolling. Scrolling down returns 1. Scrolling up returns -1.
VerticalScrollAmount	The number of lines scrolled for each click of the scroll wheel. Typically, the value is 3, but some systems might return a different value depending on how the mouse is configured.	3

R2025a: Modal figures block all MATLAB windows

When you create a modal figure by specifying the figure WindowStyle property as "modal", the figure window blocks interaction with all MATLAB windows, including other figure windows and the MATLAB desktop. In previous releases, modal figures created using the uifigure function did not block the MATLAB desktop.

If you need to interact with the MATLAB desktop while a modal figure is in focus, press Ctrl+C. This action causes the figure WindowStyle property to change from 'modal' to 'normal'.

R2025a: Default background color has changed slightly

The default Color property value in the light theme has changed slightly. Starting in R2025a, the default value is [0.9608 0.9608 0.9608]. Previously, the default value was [0.94 0.94 0.94].

R2025a: GraphicsSmoothing property has no effect

The GraphicsSmoothing property has no effect and will be removed in a future release. Now, all graphics are smooth regardless of the value of the property.

Previously, you could specify this property as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" or logical 1 (true) enabled smoothing to reduce the appearance of jagged lines in plots. A value of "off" or logical 0 (false) disabled the smoothing.

R2025a: Renderer and RendererMode properties have no effect

The Renderer and RendererMode properties have no effect and will be removed in a future release. Setting the renderer is no longer necessary.

Previously, you could set the Renderer property to one of these values:

• "opengl" — OpenGL^® renderer. This option enabled MATLAB to access graphics hardware if it was available on your system.

• "painters" — Painters renderer. This option worked well for axes in a 2-D view. In 2-D, the Painters renderer sorted graphics objects by child order (order specified). In 3-D, the Painters renderer sorted objects in front to back order.

The RendererMode property had two possible values, "auto" and "manual". A value of "auto" enabled MATLAB to select a rendering method for printing and screen display based on the size and complexity of the graphics objects in the figure. A value of "manual" restricted the renderer to the one specified in the Renderer property.

This change was announced in R2022a.

R2025a: InvertHardcopy property has no effect

The InvertHardcopy property has no effect. Now, if you call the print or saveas function to export a figure, the default background color corresponds to the theme of the figure. The background is white if the figure has a light theme. The background is dark gray (almost black) if the figure has a dark theme. If you set the Color property of the figure before calling print or saveas, the output uses the color you specify regardless of the theme.

If you call the print function to print a hard copy, the background color is white (no ink) by default. If you set the Color property of the figure, the output uses that color.

Previously, you could specify the InvertHardcopy property as "on" or "off", or as numeric or logical 1 (true) or 0 (false). A value of "on" or logical 1 (true) changed the figure background and axes background colors to white. A value of "off" or logical 0 (false) used the same colors as the colors on the display.

R2021a: Create UI figures that remain in the foreground

To keep a specific UI figure window in front of other windows, set the WindowStyle property to 'alwaysontop'. Unlike modal figures, UI figure windows with this property setting do not restrict keyboard and mouse interactions.

R2020b: Create modal UI figures

To restrict keyboard and mouse interactions to a specific UI figure window, set the WindowStyle property to 'modal'.

R2020b: Specify custom icons

To add a custom icon to a UI figure window, set the Icon property to an image file or an m-by-n-by-3 truecolor array.

R2020a: UIContextMenu property is not recommended

Starting in R2020a, using the UIContextMenu property to assign a context menu to a graphics object or UI component is not recommended. Use the ContextMenu property instead. The property values are the same.

There are no plans to remove support for the UIContextMenu property at this time. However, the UIContextMenu property no longer appears in the list returned by calling the get function on a graphics object or UI component.

R2016a: PaperPositionMode default value changed to 'auto'

The default value of the PaperPositionMode property has changed to 'auto'. Previously, the default value was 'manual'.

To change the default value, set the default value of the root object. Setting this value affects only new figures in the current MATLAB session, for example:

set(groot,'defaultFigurePaperPositionMode','manual')