Main Content

UI Figure Properties

Control UI figure appearance and behavior for uifigure-based apps

expand all in page

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

expand all

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 character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, 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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
'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 applicableNot applicableNot applicableNo color

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

RGB TripletHexadecimal Color CodeAppearance
[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'

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 the Resize or Position properties of the figure, then set the WindowStyle property first.

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

UI Figure Modal Window Style Behavior

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

fig1 = uifigure('Name','Figure 1');
fig1.WindowStyle = 'modal';

fig2 = uifigure('Name','Figure 2');
fig2.WindowStyle = 'modal';

fig3 = uifigure('Name','Figure 3');
fig3.WindowStyle = 'modal';
The modality hierarchy is not preserved if there is a combination of modal and normal figures in the hierarchy of figures.

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

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

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

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

Window state, specified as one of these values:

  • '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 (Mac OS) 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

expand all

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.

ElementDescription
leftDistance 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.
bottomDistance 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.
widthDistance between the right and left inner edges of the UI figure.
heightDistance between the top and bottom inner edges of the UI figure.

Units of measurement, specified as 'pixels'.

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

This property value is identical to the Position property value.

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

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

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.

To customize the resize behavior, 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'.

Plotting

expand all

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.

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.

Mouse Pointer

expand all

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

Value

Resulting Symbol (System Dependent)

'arrow'

'ibeam'

'crosshair'

'watch' (busy system)

'topl' or 'botr'

'topr' or 'botl'

'circle'

'cross'

'fleur'

'left' or 'right'

'top' or 'bottom'

'hand'

Custom Pointer Symbol

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

Limitations

  • The pointer symbol values 'circle', 'cross', and 'custom' are not supported in the Microsoft Edge® web browser.

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

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

Each element in the matrix defines the brightness level for 1 pixel in the pointer. 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:

  • 1 — Black pixel.

  • 2 — White pixel.

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

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

expand all

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.

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

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

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

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

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

Current point, returned as a two-element vector. The vector contains the (x, y) coordinates of the mouse pointer, measured in pixels from the lower-left corner of the UI figure. 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.

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.

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

'normal'

Click the left mouse button.

'extend'

Any of the following:

  • Shift-click the left mouse button.

  • Click the middle mouse button.

  • Click both left and right mouse buttons.

'alt'

Either of the following:

  • Control-click the left mouse button.

  • Click the right mouse button.

'open'

Double-click any mouse button.

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.

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.

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

expand all

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 Write Callbacks in App Designer.

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

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

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

expand all

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 UI figure or a child component has focus. Pressing a key on a component that accepts keyboard focus (such as an edit field) does not execute the callback unless the component is disabled. You can disable a component by setting the Enable or Editable property to 'off'.

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.

PropertyDescription
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 return unprintable characters in this property.

Pressing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.

Modifier

Cell array containing the names of the modifier keys pressed, such as control, alt, or shift. If no modifier keys are pressed, the cell array is empty.

Key

Key pressed, identified by the lowercase label on the key, or a descriptive word such as 'space'.

SourceObject that has focus when the key is pressed.
EventName'KeyPress'

For more information about specifying callback property values and using callback arguments, see Write Callbacks in App Designer.

The CurrentCharacter property also returns character information.

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

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.

PropertyDescription
Character

Character that corresponds to the key or keys that are released.

Certain keys or key combinations might return unprintable characters in this property.

Pressing and releasing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.

Modifier

Cell array containing the names of the modifier keys released, such as control, alt, or shift. If no modifier keys are released, the cell array is empty.

Key

Key released, identified by the (lowercase) label on the key, or a descriptive word such as 'space'.

SourceObject that has focus when the key is released.
EventName'KeyRelease'

For more information about specifying callback property values and using callback arguments, see Write Callbacks in App Designer.

Window Callbacks

expand all

Close request callback, specified as a function handle, cell array containing a function handle and additional arguments, or a character vector. 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.

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), where f is the Figure object.

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

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

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.

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

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 Write Callbacks in App Designer.

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 Write Callbacks in App Designer.

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

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 Write Callbacks in App Designer.

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.

PropertyDescription
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 return unprintable characters in this property.

Pressing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.

Modifier

Cell array containing the names of the modifier keys pressed, such as control, alt, or shift. If no modifier keys are pressed, the cell array is empty.

Key

Key pressed, identified by the lowercase label on the key, or a descriptive word such as 'space'.

SourceObject that has focus when the key is pressed.
EventName'KeyPress'

For more information about specifying callback property values and using callback arguments, see Write Callbacks in App Designer.

The CurrentCharacter property also returns character information.

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.

PropertyDescription
Character

Character that corresponds to the key or keys that are released.

Certain keys or key combinations might return unprintable characters in this property.

Pressing and releasing certain keys alone (such as Ctrl, Alt, Shift) does not generate Character data.

Modifier

Cell array containing the names of the modifier keys released, such as control, alt, or shift. If no modifier keys are released, the cell array is empty.

Key

Key released, identified by the (lowercase) label on the key, or a descriptive word such as 'space'.

SourceObject that has focus when the key is released.
EventName'KeyRelease'

For more information about specifying callback property values and using callback arguments, see Write Callbacks in App Designer.

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

A constant value of 3.

Source

Object that executes the callback.

EventName'WindowScrollWheel'.

For more information about specifying callback property values and using callback arguments, see Write Callbacks in App Designer

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

Callback Execution Control

expand all

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.

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, uifigure, getframe, waitfor, or pause command.

    • If the running callback contains one of those commands, then MATLAB stops the execution of the callback at that 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 those 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.

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

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.

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is permitted. If interruption is not permitted, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue. 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.

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

expand all

This property is read-only.

Parent object, returned as a root object.

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

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

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

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

This table describes the effect of setting each value:

HandleVisibility ValueDescription
'off'

The Figure object handle is not visible from callback functions or functions that execute in the Command Window. In addition, the object handle is:

  • Not visible in the lists returned by the graphics root Children or CurrentFigure properties.

  • Not returned by functions that access objects by searching the object hierarchy or querying object properties. These functions include gcf, gco, get, findobj, clf, and close.

This option prevents callback functions and functions invoked from the command line from targeting the object and making unintended changes to the UI.

'callback'

The Figure object handle is visible only from within callbacks or functions invoked by callbacks, but not from within functions invoked from the Command Window. In addition, the object handle is not visible in the lists returned by the graphics root Children or CurrentFigure properties.

This option blocks access to the object at the command line, but allows callback functions to access it.

'on'

The Figure object handle is always visible.

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

Identifiers

expand all

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 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 Image Types. Animated GIF files display only the first frame.

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

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

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

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

This property is read-only.

Number of the figure, returned as an integer or empty array. 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.

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

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

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

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

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

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

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

This property is read-only.

Type of graphics object, returned as 'figure'.

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.

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.

See Also

| |

Topics

Introduced in R2016a

MATLAB Documentation

Support

Introducing Deep Learning with MATLAB

Introducing Deep Learning with MATLAB

Download ebook