Figure Properties

Figures are containers for graphics or user interface
components. Figure properties control the appearance and behavior
of a particular instance of a figure. To modify aspects of a figure,
change property values.

Starting in R2014b, you can use dot notation to query and set
properties.

fig = figure;
u = fig.Units;
fig.Units = 'inches';

If you are using an earlier release, use the get and set functions
instead.

Window Appearance

MenuBar — Figure menu bar display'figure' (default) | 'none'

Figure menu bar display, specified as
'figure' or 'none'. 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.

This property affects only default menus, and does not affect menus defined
with the uimenu command.

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

Note

If you do not want to display the default menus in the figure, then set this
property to 'none' when you create the figure.

ToolBar — Figure toolbar display'auto' (default) | 'figure' | 'none'

This property affects only the default toolbar. It does not affect other
toolbars such as, the Camera Toolbar or Plot Edit Toolbar. Selecting
Figure Toolbar from the figure View menu sets this property to 'figure'.

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

Note

If you want to hide the default tool bar, then set this property to
'none' when you create the figure.

DockControls — Interactive figure docking'on' (default) | 'off'

Interactive figure docking, specified as one of the
following:

'on' — Figure can be docked in the MATLAB® desktop. The Desktop > Dock Figure menu item and the Dock Figure button in the menu bar are enabled.

You cannot set the DockControls property to
'off' if the WindowStyle is set
to 'docked'.

Setting the DockControls property is not supported in
MATLAB
Online™.

Color — Background colorRGB triplet | 'r' | 'g' | 'b' | ...

Background color, specified as an RGB triplet, or one of the color options listed in the
table. If you specify 'none', the background color appears black on
screen, but if you print the figure, the background prints as though the figure window
is transparent.

For a custom color, specify an RGB triplet. 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]. Alternatively, you can specify some common colors by
name. This table lists the long and short color name options and the equivalent RGB triplet
values.

Option

Description

Equivalent RGB Triplet

'red' or 'r'

Red

[1 0 0]

'green' or 'g'

Green

[0 1 0]

'blue' or 'b'

Blue

[0 0 1]

'yellow' or 'y'

Yellow

[1 1 0]

'magenta' or 'm'

Magenta

[1 0 1]

'cyan' or 'c'

Cyan

[0 1 1]

'white' or 'w'

White

[1 1 1]

'black' or 'k'

Black

[0 0 0]

'none'

No color

Not applicable

Data Types: double | char

WindowStyle — Window style'normal' (default) | 'modal' | 'docked'

Window style, specified as one of the following:

'normal' — The figure window is independent of other
windows, and the other windows are accessible while the figure is
displaying.

'modal' — The figure displays on top of all existing
figure windows, making them inaccessible as long as the top figure exists
and remains modal. However, any new figures created after a modal figure
will display.

When multiple modal windows exist, the most recently created window keeps
focus and stays above 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.

'docked' — The figure displays in the desktop or a
document window. When the WindowStyle property is set
to 'docked', you cannot set the
DockControls property to 'off'.
The 'docked' option is not supported in MATLAB
Online.

Note

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

When you create UI windows, always specify the
WindowStyle property. If you also want to set
the Resize, Position, or
OuterPosition 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.

Calling reset on a figure does
not change the value of the WindowStyle
property.

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.

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.

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.

'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 and tool bars
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 and tool bars in the
normal state, they are present in this state.

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 (Mac OS) toggles the 'fullscreen' state.

Setting the WindowState property on a docked figure
or in MATLAB
Online is not supported.

Position

Location and size of the drawable area, specified as a vector
of the form [left bottom width height]. This area
excludes the figure borders, title bar, menu bar, and tool bars.

This table describes each element in the Position 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 the Figure panel within the
MATLAB desktop.

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 the Figure panel within the
MATLAB desktop.

width

Distance between the right and left inner edges of the figure.

height

Distance between the top and bottom inner edges of the window.

All measurements are in units
specified by the Units property.

You cannot specify the figure Position property
when the figure is docked.

In MATLAB
Online, the bottom and left elements of the
Position vector are ignored.

To place the full window, including the borders, title bar,
menu bar, tool bars, 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 will conform to the limits instead
of the size you specified.

Starting
in R2015b, distances in pixels are independent of your system resolution
on Windows and Macintosh systems:

On Windows systems, a pixel is 1/96th of an inch.

On Macintosh systems, a pixel is 1/72nd of an
inch.

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.

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.

Location and size of the drawable area, specified as a vector of the form
[left bottom width height]. This area excludes the figure
borders, title bar, menu bar, and tool bars. All measurements are in units
specified by the Units property.

Location and size of the outer bounds, specified as a vector of the form
[left bottom width height]. This property defines the region
enclosed by the figure’s outer bounds (which includes the borders, title bar, menu
bar, and tool bars).

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 the Figure panel within the
MATLAB desktop.

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 the Figure panel within the
MATLAB desktop.

width

Distance between the right and left outer edges of the
figure.

height

Distance between the top and bottom outer edges of the
figure.

All measurements are in units specified by the
Units property.

You cannot specify the figure OuterPosition property when
the figure is docked.

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 will conform to the limits instead
of the size you specified.

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.

Rendering method used for screen display and printing, specified as one of
these values:

'opengl' — OpenGL® renderer. This option enables MATLAB to access graphics hardware if it is available on your system.
The OpenGL renderer displays objects sorted in front to back order, as
seen on the monitor. Lines always draw in front of faces when at the same
location on the plane of the monitor.

'painters' — Painters renderer. This option
works well for axes in a 2-D view. In 2-D, the Painters renderer sorts
graphics objects by child order (order specified). In 3-D, the Painters
renderer sorts objects in front to back order. However, it might not
correctly draw intersecting polygons in 3-D.

Note

The 'zbuffer' option has been removed. Use
'opengl' or 'painters'
instead.

Setting the Renderer property is not supported in
MATLAB
Online.

OpenGL Hardware and Software Implementations

OpenGL is available on all computers that run MATLAB since a software version of OpenGL is built-into MATLAB. However, if you have graphics hardware that supports a
hardware-accelerated version of OpenGL, then MATLAB automatically uses the hardware-accelerated version to increase
performance.

In some cases, MATLAB automatically uses software OpenGL even if a hardware version is available. For example, MATLAB uses the software version if it detects graphics hardware with
known driver issues or detects that you are using a virtual machine or remote
desktop on Windows.

MATLAB issues a warning if it cannot find a usable OpenGL library.

Software OpenGL Selection

To switch from hardware to software OpenGL, do the following:

On Linux systems, start MATLAB with the command matlab
-softwareopengl.

On Windows systems, execute the command opengl
software in MATLAB or start MATLAB with the command matlab
-softwareopengl.

On Macintosh systems, software OpenGL is not supported.

The following software versions are available:

On Linux systems, MATLAB uses the software implementation of OpenGL that is included in the MATLAB distribution.

On Windows, OpenGL is available as part of the operating system. If you
experience problems with OpenGL, contact your graphics driver vendor to obtain the latest
qualified version of OpenGL.

On Macintosh systems, software OpenGL is not available.

Determine OpenGL Library Version

To determine the version and vendor of the OpenGL library that MATLAB is using on your system, type the following command at the
MATLAB prompt:

opengl info

The returned information contains a line that indicates if MATLAB is using software OpenGL (Software = true) or hardware-accelerated
OpenGL (Software = false).

This command also returns a list of extensions to the OpenGL specification that are available with the particular library
MATLAB is using. Include this information if you report a bug.

Be aware that issuing the opengl info command causes
MATLAB to initialize OpenGL.

XServer Connection Lost

When using Linux, if there is a break in the connection to the XServer,
MATLAB can crash with a segmentation violation . If this happens, ensure
that the system has the latest XServer installed.

On a Linux system, you also can try upgrading the OpenGL driver or starting MATLAB with software OpenGL using this command:

matlab -softwareopengl

RendererMode — Renderer selection'auto' (default) | 'manual'

Renderer selection, specified as:

'auto' — MATLAB selects the rendering method for printing and screen display
based on the size and complexity of the graphics objects in the figure.

MATLAB sets the RendererMode property
to 'manual' if you explicitly set the
Renderer property to 'painters' or
'opengl'.

GraphicsSmoothing — Axes graphics smoothing'on' (default) | 'off'

Axes graphics smoothing, specified as 'on' or 'off'.
Smoothing reduces the appearance of jagged lines in an axes graphic. MATLAB applies
a smoothing technique to an axes graphic (and the axes rulers) if GraphicsSmoothing is
set to 'on', and either of these conditions is
true:

The Renderer property is set
to 'opengl' and your hardware card supports OpenGL.

If your axes graphic contains mostly vertical or horizontal lines, consider setting the
GraphicsSmoothing property to 'on' and
the line or lines AlignVertexCenters property to 'on'. The
smoothing technique sacrifices some sharpness for smoothness, which might be
particularly noticeable in such graphics.

Note

Graphics smoothing has no affect on text. MATLAB smooths
text regardless of the value of the GraphicsSmoothing property.

Setting the GraphicsSmoothing property is not
supported in MATLAB
Online.

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 uicontrols or a uitable, 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.

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.

Note

Starting in R2016a, the default value is 'auto'.
Previously, the default value was 'manual'.

To change the default value, use one of these techniques.

Set a print preference. Print preferences persist across MATLAB sessions. You can set the print preference to either
'auto' or 'manual', for
example:

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.

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.

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.

'off' — Use the same colors as the colors on
the display. To change the figure background color on the display, use
the Color property of the figure. To change the axes
background color, use the Color property of the
axes.

Custom pointer symbol, specified as a
32-by-32 matrix (for a 32-by-32 pixel
pointer) or as a 16-by-16 matrix (for a
16-by-16 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. Element (1,1) of the matrix corresponds to the pixel
in the upper left corner in the pointer. Set the matrix elements to one of these values:

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

Target axes in the current figure, specified as an Axes object, a 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 objectchild 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 pointtwo-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.

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),
provided that 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.

Selected — Selection state (not recommended)'off' (default) | 'on'

Note

The behavior of the Selected property changed in R2014b,
and it is not recommended. It no longer has any effect on
Figure objects. This property might be removed in a
future release.

Context menu, specified as a ContextMenu object. Use this property
to display a context menu when the user right-clicks on a UI component. Create the
context menu using the uicontextmenu function.

Visible — Figure visibility'on' (default) | 'off'

Figure visibility, specified as 'on' or 'off'.
The Visible property determines whether the figure displays on the screen. If the Visible property
of a figure is set to 'off',
the entire figure is invisible, but you can still
specify and access its properties.

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

Note

Changing the Visible property of a figure does not change the Visible property
of its child components even though hiding the figure prevents
its children from displaying.

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

Use the gcbo function in your
CreateFcn code to get the component object that is being
created.

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

The DeleteFcn property specifies a callback function to execute
when MATLAB deletes the component (for example, when the user closes the window).
MATLAB executes the DeleteFcn callback before destroying the
properties of the component object. If you do not specify the
DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your
DeleteFcn code to get the component object that is being
deleted.

Keyboard Callbacks

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 object has focus. If the user presses a key on a
UIControl or Table component, the
callback does not execute unless the Enable property is set
to 'off'.

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
this object.

Property

Description

Character

The character that appears as a result of pressing the
key or keys.

Pressing certain keys or modifying keys
with the Ctrl key might put unprintable
characters in the Character
property.

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 object has focus. If the user releases a key on a
UIControl or Table component, the
callback does not execute unless the Enable property is set
to 'off'.

The KeyReleaseFcn 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
this object.

This callback executes whenever a user attempts to close a figure window. You
can, for example, display a dialog box to ask a user to confirm or cancel the
close operation or to prevent users from closing a figure that contains a
UI.

The basic mechanism is:

A user issues the close or close
all command from the command line, closes the figure from the
computer window manager menu, or closes the figure by quitting MATLAB.

The close operation executes the function defined by the figure
CloseRequestFcn property. The default function is
closereq.

The closereq function unconditionally deletes the
current figure, destroying the window. The closereq
function takes advantage of the fact that the close
command makes each figure specified as an argument the current figure before
calling its respective close request function.

The closereq function honors the
ShowHiddenHandles property setting during figure deletion
and does not delete hidden figures.

Unless the close request function calls the delete or close function, MATLAB never closes the figure. (You can call delete(f)
from the command line if you have created a window with a nondestructive close
request function.)

Example: Code CloseRequestFcn to Display Dialog Box

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

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 app layout when the size of this
container changes (e.g., when the user resizes the window).

The SizeChangedFcn callback executes when:

This container becomes visible for the first time.

This container is visible while its size changes.

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

Other important points to consider when defining a
SizeChangedFcn callback:

Consider delaying the display of this container 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 container,
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 app contains nested containers, they resize from the inside
out.

To access the container that is resizing from within the
SizeChangedFcn, refer to the source object (the
first input argument in the callback) or use the gcbo function.

Tip

As an easy alternative to specifying a
SizeChangedFcn callback, you can set the
Units property of all the objects you put inside a
container to 'normalized'. Doing so makes those
components scale proportionally with the container.

Example: Edit Field With Constant Height

Use the SizeChangedFcn callback to constrain the
size of UI components. For instance, the following code creates a UI
that has an edit field at the top of the window. As the user resizes the
window, the sbar function restricts its height to 20
pixels. The function also sets the edit field’s width to the width of
the figure.

If you are using R2014b or later, use dot notation to set and query
properties:

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 anywhere in the figure or one of
its child objects. If the user clicks a UIControl or
Table component, the callback does not execute unless the
Enable property is set to 'off'.

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.

Example: Simple Drawing App

This example shows how to create a drawing app that uses the
WindowButtonMotionFcn callback. Copy and paste the
following code into the editor and run it. Then use the mouse to draw a set of
connected line segments:

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 anywhere in the
figure or one of its child objects. If the user releases the mouse button on a
UIControl or Table component, the
callback does not execute unless the Enable property is set
to 'off'.

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

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 object 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
this object.

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 object 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
this object.

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 if its children have focus. However, other objects can capture scroll wheel
movement and interfere with the execution of this callback.

Executing this callback has no effect on the CurrentObject
and SelectionType properties.

The WindowScrollWheelFcn 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 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.

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.

Callback Execution Control

Interruptible — Callback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'.
The Interruptible 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.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running
callback (if one exists). The Interruptible property of the object
owning the running callback determines if interruption is allowed:

A value of 'on' allows other callbacks to interrupt
the object's callbacks. The interruption occurs at the next point where
MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

If the running callback contains one of these commands, then
MATLAB stops the execution of the callback at this point
and executes the interrupting callback. MATLAB resumes executing the running callback when the
interrupting callback completes.

If the running callback does not contain one of these
commands, then MATLAB finishes executing the callback without
interruption.

A value of 'off' blocks all interruption attempts. The
BusyAction property of the object owning the
interrupting callback determines if the interrupting callback is discarded
or put into a queue.

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.

Timer objects execute according to
schedule regardless of the Interruptible property
value.

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

See Interrupt Callback Execution for an example that shows
how the Interruptible and BusyAction properties
affect the behavior of a program.

BusyAction — Callback queuing'queue' (default) | 'cancel'

Callback queuing specified as 'queue' (default)
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 of the source of
the interrupting callback determines how MATLAB handles its execution.
The BusyAction property has these values:

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

'cancel' — Do not execute
the interrupting callback.

Whenever MATLAB invokes a callback, that callback always
attempts to interrupt an executing callback. The Interruptible property
of the object whose callback is running determines if interruption
is allowed. If Interruptible is set to:

on — Interruption occurs
at the next point where MATLAB processes the queue. This is the
default.

off — The BusyAction property
(of the object owning the interrupting callback) determines if MATLAB enqueues
or ignores the interrupting callback.

See Interrupt Callback Execution for an example that shows
how the BusyAction and Interruptible properties
affect the behavior of a program.

HitTest — Ability to become current object'on' (default) | 'off'

Ability to become current object, specified as
'on' or 'off':

'on' — Sets the current object to the
Figure when the user clicks the component in the
running app. 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 in the running app.

BeingDeleted — Deletion status'off' | 'on'

This property is read-only.

Deletion status, returned as 'off' or 'on'. 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/Child

Parent — Figure parentroot object

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

You cannot add or remove children using the
Children property. Use this property to view the list of children or to
reorder the children. The order of the children reflects the front-to-back order (stacking
order) of the components on the screen. MATLAB might not allow you to change the order of certain objects. For example,
UIControl and Legend objects are always in front of
Axes objects.

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

Objects with the HandleVisibility property
set to 'off' do not list in the Children
property.

This property determines whether a figure is in its parent’s
(the root’s) list of children. HandleVisibility is useful for
preventing command-line users from accidentally drawing into, or deleting a figure
that contains only user interface components (such as a dialog box).

If an object is not in its parent's list of children, functions that find
objects by searching the object hierarchy or querying properties cannot return
that object. Such functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

When the HandleVisibility property value is restricted
using the 'callback' or 'off' settings, the
object does not appear in the parent object Children
property, figures do not appear in the root CurrentFigure
property, objects do not appear in the root CallbackObject
property or in the figure CurrentObject
property, and axes do not appear in their parent CurrentAxes
property.

Set the root ShowHiddenHandles
property to 'on' to make all objects visible, regardless of
their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).

Identifiers

Name — Name'' (default) | character vector | string scalar

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

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

By default, the 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'.

Number — Numberinteger | []

This property is read-only.

Number of the figure, returned as an integer or empty array. You can refer to a figure
using this value. For example, figure(2) makes the figure with a
Number property value of 2 the current
figure.

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' (default) | 'off'

Number title, specified as 'on' or 'off'.
When you set this property to 'on', the title of the figure
includes the phrase 'Figure n', where n is
the value of the Number property.

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

IntegerHandle — Use integer handle'on' (default) | 'off'

Use integer handle, specified as 'on' or
'off'.

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 figure number in the title bar, both
IntegerHandle and NumberTitle must be
set to 'on'.

FileName — File namecharacter vector | string scalar

File name for saving the figure, specified as a character vector or a string
scalar. GUIDE uses this property to store the name of the UI layout file that it
saves.

Example: figure('FileName','myfile.fig') sets the file name
to myfile.fig.

Type — Type of Figure object 'figure'

This property is read-only.

Type of Figure object, returned as 'figure'.
Use this property to find all objects of a given type within a plotting
hierarchy.

Tag — Figure identifier' ' (default) | character vector

Object
identifier, specified as a character vector or string scalar. You can specify a unique
Tag value to serve as an identifier for any component object in your
app. 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.