UI Figure Properties
Control UI figure appearance and behavior for uifigure
-based
apps
UI figures are containers for creating apps in App Designer or programmatically with
the uifigure
function. Properties control the appearance and behavior of the
UI figure. Use dot notation to refer to a particular object and property:
fig = uifigure; fig.Name = 'My App';
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 from0
toF
. 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 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 |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB® uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
WindowStyle
— Window style
'normal'
(default) | 'modal'
| 'alwaysontop'
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 with normal window style, 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.
'alwaysontop'
— The figure displays on top of all other windows, including modal figure windows and windows from non-MATLAB applications. The other windows are still accessible.
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 theResize
orPosition
properties of the figure, then set theWindowStyle
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 theWindowStyle
property at creation time or when the figure is invisible.
UI Figure Modal Window Style Behavior
When WindowStyle
is set to 'modal'
, the UI figure window blocks keyboard and mouse interactions in a UI figure window that was created before it and has its Visible
property set to 'on'
. For instance, in this example Figure 3 is modal with respect to Figure 2 and Figure 2 is modal with respect to Figure 1.
fig1 = uifigure('Name','Figure 1'); fig1.WindowStyle = 'modal'; fig2 = uifigure('Name','Figure 2'); fig2.WindowStyle = 'modal'; fig3 = uifigure('Name','Figure 3'); fig3.WindowStyle = 'modal';
Unlike modal figures created with the figure
function, modal figures created with the uifigure
function do not block access to figures created with the figure function or the MATLAB desktop. Interactions with application windows other than MATLAB are also not blocked.
Typing Ctrl+C when a modal figure has focus causes that figure to revert to a 'normal'
WindowStyle
property setting. This allows the user to type at the command line.
UI figures with the WindowStyle
property set to 'modal'
and the Visible
property set to 'off'
do not behave modally until MATLAB makes them visible. Therefore, you can hide a modal window for later reuse, instead of destroying it.
Modal figures do not display menu children, built-in menus, or toolbars. But, it is not an error to create menus in a modal figure or to change the WindowStyle
property setting to 'modal'
on a figure with menu children. The Menu
objects exist and the figure retains them. If you reset the UI figure WindowStyle
property to 'normal'
, the menus display.
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.
Clicking the minimize, maximize, or restore button provided by the operating system sets
the WindowState
property accordingly. Pressing Ctrl+F11
(Windows® and Linux®) or Ctrl+Command+F (macOS) toggles the 'fullscreen'
state. Setting this property on a
docked figure or in MATLAB
Online™ is not supported.
UI figures cannot be minimized directly from a full screen state.
Position and Size
Position
— Location and size of UI figure, excluding borders and title bar
[left bottom width height]
Location and size of the UI figure, excluding borders 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 UI figure window. This value can be negative on systems that have more than one monitor. |
bottom | Distance from the bottom edge of the primary display to the inner bottom edge of the UI figure window. This value can be negative on systems that have more than one monitor. |
width | Distance between the right and left inner edges of the UI figure. |
height | Distance between the top and bottom inner edges of the UI figure. |
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. Distances in pixels are independent of your system resolution on Windows and Macintosh systems:
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:
To access the default uicontrol font, use
|
MATLAB measures all units from the lower left corner of the parent object.
The recommended value is 'pixels'
, because most MATLAB app building functionality measures distances in pixels.
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 thePosition
property, then MATLAB setsPosition
using the units you specify.If you specify the
Units
property after thePosition
property, MATLAB sets the position using the defaultUnits
. Then, MATLAB converts thePosition
value to the equivalent value in the units you specify.
InnerPosition
— Location and size of UI figure, excluding borders and title bar
[left bottom width height]
Location and size of UI figure, excluding borders and title bar, specified as a
four-element vector of the form [left bottom width height]
. All
measurements are in units specified by the Units
property.
This property value is identical to the Position
property
value.
Resize
— Resizable
'on'
(default) | on/off logical value
Resizable UI figure, specified as 'on'
or 'off'
, or
as numeric or logical 1
(true
) or 0
(false
). A value of 'on'
is equivalent to
true
, and 'off'
is equivalent to
false
. Thus, you can use the value of this property as a logical value.
The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState
.
When this property is set to 'on'
, the UI figure is resizable.
Otherwise, it is not resizable.
AutoResizeChildren
— Automatically resize children
'on'
(default) | 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.'off'
— Child components do not resize.
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 UIAxes
content
parula (default) | m
-by-3
array of RGB triplets
Color map for UIAxes
content, specified as an
m
-by-3
array of RGB (red, green, blue) triplets that
define m
individual colors.
Example: uifigure('Colormap',[1 0 1; 0 0 1; 1 1 0])
sets the color map
to three colors: magenta, blue, and yellow.
MATLAB accesses these colors by their row number.
Alphamap
— Transparency map for axes content
vector of 64 values between 0
and
1
(default) | vector of values between 0
and 1
Transparency map for axes content, specified as a vector of values between
0
and 1
, inclusive. The size of the vector can be
m-by-1 or 1-by-m. MATLAB accesses alpha values by their index in the vector. Alphamaps can be any
length.
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 no effect unless the figure can become the current figure (for example,
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 |
'replace' | Removes all axes objects and resets figure properties to their defaults before adding new graphics objects. Equivalent to using the |
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.
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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 UI figure
UIAxes
object | Axes
object | PolarAxes
object | graphics object
Target axes in the current UI figure, specified as a UIAxes
, Axes
, or PolarAxes
object, or a graphics object such as a HeatmapChart
.
In all UI figures for which axes children exist, there is always a current axes. The
current axes does not have to be the topmost axes, and setting an axes to be the current axes
does not restack it above all other axes. If a UI figure contains no axes, the
get(gcf,'CurrentAxes')
command returns an empty array.
Query the CurrentAxes
property to get the current axes object
without forcing the creation of an axes if one does not exist.
CurrentObject
— Current object
empty GraphicsPlaceholder
array (default) | child object of UI figure
Current object, returned as a child object of the UI figure. MATLAB sets the CurrentObject
property to the last object clicked
in the UI figure.
Clicking an object whose HandleVisibility
property is
'off'
sets the CurrentObject
property to an empty
GraphicsPlaceholder
array.
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 UI figure. The values are in units specified by the
Units
property. If the UI figure is scrollable, the coordinates are
measured from the lower-left corner of the scrollable area. The scrollable area is the area
that is bounded by the limits of the scroll bars.
The coordinates update when you do any of the following:
Press the mouse button within the UI figure.
Release the mouse button after pressing it within the UI figure.
Press the mouse button within the UI figure, and then release it outside the UI figure.
Rotate the scroll wheel within the UI figure.
Move the mouse within the figure (without pressing any buttons), as long as the
WindowButtonMotionFcn
property is not empty.
If the UI figure has a callback that responds to mouse interactions, and you trigger that callback faster than the system can execute the code, the coordinates might not reflect the actual location of the pointer. Instead, they are the location when the callback began execution.
If you use the CurrentPoint
property to plot points, the coordinate
values might contain rounding error.
CurrentCharacter
— Current character
''
(default) | character
Current character, returned as the character of the last key pressed. This property updates when the UI 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 UI
figure.
This table lists the possible SelectionType
values and the user
actions that produce those values.
Value | Corresponding Action |
---|---|
| Click the left mouse button. |
| Any of the following:
|
| Either of the following:
|
| 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 theScrollable
property of theGridLayout
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 UI figure.
Common Callbacks
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 UI figure.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.
Use the SelectionType
property to determine whether the user pressed
modifier keys.
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 UI figure has
focus. Pressing a key on a component that accepts keyboard focus (such as an edit field) does
not execute the callback unless the component is disabled. You can disable a component by
setting the Enable
or Editable
property to
'off'
. In addition, you can disable a Table
component
without graying it out by setting the Enable
property to
'inactive'
.
If the user presses multiple keys at approximately the same time, MATLAB detects all the keys.
The KeyPressFcn
callback can access specific information about the
user’s interaction with the keyboard. MATLAB passes this information in a KeyData
object as the second
argument to your callback function. This table lists the properties of the
KeyData
object.
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
| 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of the modifier keys pressed, such as
| {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key pressed, identified by the lowercase label on the key (such as
| '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 Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.
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 UI 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
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
| 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of the modifier keys pressed, such as
| {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key released, identified by the lowercase label on the key (such as
| '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 Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.
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 apps created programmatically, call
delete(f)
, wheref
is theFigure
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 displays.
SizeChangedFcn
— Size change callback
''
(default) | function handle | cell array | character vector
Size change 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 app layout when the size of this container
changes (e.g., when the user resizes the window). In it, write code to adjust the
Position
property of the child components.
Note
The SizeChangedFcn
callback will not execute unless the
AutoResizeChildren
property of this container 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:
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 theSizeChangedFcn
callback from returning an error. To delay the display of the container, set itsVisible
property to'off'
. Then, set theVisible
property to'on'
after you define the variables that yourSizeChangedFcn
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 thegcbo
function.
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:
Resizing a component up to a minimum or maximum size that you define.
Implementing non-linear resize behaviors, like changing the size of a component based on the size of the parent container.
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:
A blank area of the UI figure.
A UI component within the UI figure.
A graphics object within the UI figure that supports the
ButtonDownFcn
property.
For example, clicking an axes
object triggers the WindowButtonDownFcn
callback.
If the user clicks a UITable
component, the callback does not execute
unless the Enable
property is set to 'off'
or
'inactive'
.
See the list of properties for a specific graphics object to determine if it supports the
ButtonDownFcn
property. See Graphics Object Properties for the properties of graphics objects.
Note
The callback executes when the user clicks a uiaxes
component, even though uiaxes
components do not
support the ButtonDownFcn
property.
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
UI figure. However, if the user clicks and holds the mouse button and moves the pointer
outside the UI figure, the WindowButtonMotionFcn
callback executes while
the pointer is outside the UI figure.
For more information about specifying a callback property value as a function handle, cell array, or character vector, see Callbacks in App Designer or Create Callbacks for Apps Created Programmatically.
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 a blank area of the UI figure.
Releases the mouse button on a UI component within the UI figure.
Releases the mouse button on a graphics object within the UI figure that supports the
ButtonDownFcn
property.
For example, releasing the mouse button on an axes
object triggers the WindowButtonUpFcn
callback.
If the user releases the mouse button on a UITable
component, the
callback does not execute unless the Enable
property is set to
'off'
or 'inactive'
.
See the list of properties for a specific graphics object to determine if it supports the
ButtonDownFcn
property. See Graphics Object Properties for the properties of graphics objects.
Button-up actions are associated with button-down actions in the UI figure. The mouse pointer must be inside the UI figure when the button-down action occurs, but it can be outside the figure when the button-up action occurs.
Note
The callback executes when the user releases the mouse button on a uiaxes
component, even though uiaxes
components do not
support the ButtonDownFcn
property.
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 UI figure or a child component has focus. If the user presses multiple keys at approximately the same time, MATLAB detects all the keys.
This callback function can access specific information about the user’s interaction with
the keyboard. MATLAB passes this information in a KeyData
object as the second
argument to your callback function. This table lists the properties of the
KeyData
object.
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
| 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of the modifier keys pressed, such as
| {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key pressed, identified by the lowercase label on the key (such as
| '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 UI figure or a child component has focus.
This callback function can access specific information about the user’s interaction with
the keyboard. MATLAB passes this information in a KeyData
object as the second
argument to your callback function. This table lists the properties of the
KeyData
object.
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
| 'a' | '=' | '' | 'A' |
Modifier | A cell array containing the names of the modifier keys pressed, such as
| {1x0 cell} | {1x0 cell} | {'shift'} | {'shift'} |
Key | The key released, identified by the lowercase label on the key (such as
| '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 UI figure or any of its children have focus. However, other objects can capture scroll wheel movement and interfere with the execution of this callback.
This callback has no effect on the CurrentObject
and
SelectionType
properties.
This callback can access specific information when the user rotates the scroll wheel.
MATLAB passes this information in a ScrollWheelData
object as the
second argument to your callback function. This table lists the properties of the
ScrollWheelData
object.
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
|
VerticalScrollAmount | A constant value of |
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, theBusyAction
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
, orSizeChangedFcn
callback, then the interruption occurs regardless of theInterruptible
property value.If the running callback is currently executing the
waitfor
function, then the interruption occurs regardless of theInterruptible
property value.If the interrupting callback is owned by a
Timer
object, then the callback executes according to schedule regardless of theInterruptible
property value.
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:
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.
BeingDeleted
— Deletion status
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
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 component objects
Children of the Figure
object, returned as an empty
GraphicsPlaceholder
or a one-dimensional array of component objects. The
children can be any component, excluding another Figure
object.
You cannot add or remove a child component using the Children
property. Use this property to view the list of children or to reorder the children. The order
of the children in this array reflects the front-to-back order (stacking order) of the
components on the screen.
To add a child to this list, set the Parent
property of the child
component to the Figure
object.
HandleVisibility
— Visibility of object handle
'off'
(default) | 'callback'
| 'on'
Visibility of object handle, specified as 'off'
,
'callback'
, or 'on'
. This property provides information
about the visibility of the Figure
object in its parent's
list of children. The default value is set to 'off'
to prevent the
Figure
object from becoming the current figure (gcf
) and to prevent functions from making unwanted changes to the UI.
This table describes the effect of setting each value:
HandleVisibility Value | Description |
---|---|
'off' | The
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 This option blocks access to the object at the command line, but allows callback functions to access it. |
'on' | The |
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
''
(default) | character vector | string scalar
Name of the figure, specified as a character vector or a string scalar.
Example: uifigure('Name','Results')
sets the name of the figure to
'Results'
.
In App Designer, the default value of the Name
property is
'MATLAB App'
.
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
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
'off'
(default) | 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 you set this property to 'on'
, the title of the UI figure
includes the phrase 'Figure n'
, where n
is a
number.
Both the NumberTitle
and IntegerHandle
properties must be set to 'on'
to show the number in the title.
IntegerHandle
— Use integer handle
'off'
(default) | 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 UI figure, MATLAB can reuse its number on a new figure.
If you set the IntegerHandle
property to 'off'
,
MATLAB does not assign an integer value to the UI figure, and it sets the
Number
property to an empty array.
To show the number in the title bar, both IntegerHandle
and
NumberTitle
must be set to 'on'
.
Type
— Type of graphics object
'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.
Version History
Introduced in R2016aR2021a: 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.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)