Figure Properties

Control figure window appearance and behavior

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

Starting in R2014b, you can use dot notation to refer to a particular object and property:

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

If you are using an earlier release, use the get and set functions to query and set properties.

Figure Appearance

expand all

ColorFigure window background colorRGB triplet | short name | long name | 'none'

The figure window background color, specified as an RGB triplet, a predefined color name string, or 'none'. If you specify 'none', the figure background color appears black on screen, but if you print it, the background prints as though the figure window is transparent.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Data Types: double | char

DockControlsInteractive figure docking'on' (default) | 'off'

Interactive figure docking, specified as one of the following:

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

  • 'off' — MATLAB disables the Desktop > Doc Figure menu item and does not display the figure dock button.

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

MenuBarFigure menu bar display'figure' (default) | 'none'

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

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

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

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

NameFigure window title'' (default) | string

Figure window title, specified as a string. The Name property specifies the title that the figure window displays. By default, the figure title displays as Figure 1, Figure 2, and so on. When you set this property to a string, the figure title becomes Figure:n string. If you want only the Name value to display, set IntegerHandle or NumberTitle to 'off'.

Example: 'Results'

NumberTitleFigure window title number'on' (default) | 'off'

Figure window title number, specified as 'on' or 'off'. The NumberTitle property determines whether MATLAB includes the string Figure n in the title bar, where n is the figure Number property value.

If you set IntegerHandle to 'off', then a number does not display in the figure window title, regardless of the NumberTitle property setting.

ToolBarFigure toolbar display'auto' (default) | 'figure' | 'none'

Figure toolbar display, specified as one of the following:

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

  • 'figure' — Toolbar displays.

  • 'none' — Toolbar does not display.

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

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

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

VisibleFigure visibility'on' (default) | 'off'

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

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

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

ClippingClipping of child components to figure'on' (default) | 'off'

This property has no effect on figures.

Axes and Plot Appearance

expand all

GraphicsSmoothingAxes graphics smoothing'on' (default) | 'off'

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

  • The Renderer property is set to 'painters'.

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

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

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

RendererRendering method used for screen display and printing'opengl' (default) | 'painters'

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

  • 'opengl'This option is typically faster than the 'painters' option and enables MATLAB to access graphics hardware if it is available on your system.

  • 'painters' — This option is good when the figure contains only simple or small graphics objects.

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

The OpenGL renderer displays objects sorted in front to back order, as seen on the monitor. Lines always draw in front of faces when at the same location on the plane of the monitor. The Painters renderer sorts by child order (order specified).

OpenGL Hardware and Software Implementations

The OpenGL hardware implementation uses special graphics hardware to increase performance and is significantly faster than the software implementation.

OpenGL is available on all computers that run MATLAB. MATLAB automatically finds hardware-accelerated versions of OpenGL, if available. If the hardware-accelerated version is not available, then MATLAB uses the software implementation (except on Macintosh systems, which do not support software OpenGL). MATLAB auto-selects software OpenGL if you are using graphics hardware with known driver issues or if you are using a virtual machine.

The following software versions are available:

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

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

  • On Macintosh systems, software OpenGL is not available.

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

Software OpenGL Selection

To use software OpenGL, do the following:

  • On UNIX systems, start MATLAB with the command, matlab softwareopengl.

  • On Windows systems, execute the command, opengl software in MATLAB. This command provides the equivalent behavior to a software implementation of OpenGL.

On Macintosh platforms, software OpenGL is not supported.

Determine OpenGL Library Version

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

opengl info

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

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

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

XServer Connection Lost

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

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

 matlab softwareopengl

RendererModeRenderer selection'auto' (default) | 'manual'

Renderer selection, specified as:

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

  • 'manual' — MATLAB uses the renderer specified with the Renderer property.

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

Color and Transparency Mapping

expand all

AlphamapTransparency map for axes content of figurearray of 64 values from 0 to 1 (default) | array of finite alpha values from 0 to 1

Transparency map for axes content of figure, specified as an array of finite alpha values that progress linearly from 0 to 1. The size of the array can be m-by-1 or 1-by-m. MATLAB accesses alpha values by their row number. For example, an index of 1 specifies the first alpha value, an index of 2 specifies the second alpha value, and so on. Alphamaps can be any length.

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

ColormapColor map for axes content of figureparula (default) | m-by-3 array of RGB triplets

Color map for axes content of a figure, specified as an m-by-3 array of RGB (red, green, blue) triplets that define m individual colors. MATLAB accesses these colors by their row number. For example, an index of 1 specifies the first RGB triplet, an index of 2 specifies the second RGB triplet, and so on.

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

Colormaps can be any length, but must be three columns wide.

Example: [1 0 1; 0 0 1; 1 1 0]

Location and Size

expand all

PositionLocation and size of figure's drawable area[left bottom width height]

Location and size of figure's drawable area, specified as the vector, [left bottom width height]. The drawable area is the inner area of the window, excluding the title bar, menu bar, and tool bars. This table describes each element in the Position vector.

ElementDescription
leftDistance from the left edge of the primary display to the inner left edge of the 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 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 figure.
heightDistance between the top and bottom inner edges of the figure.

All measurements are in units specified by the Units property.

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

To place the full window, including the title bar, menu bar, tool bars, and outer edges, use the OuterPosition property.

    Note:   On Windows systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the Position property.

Example: [230 250 570 510]

Data Types: double

OuterPositionLocation and size of figure's outer bounds[left bottom width height]

Location and size of outer bounds, specified as the vector, [left bottom width height]. This table describes each element in the vector.

ElementDescription
leftDistance from the left edge of the primary display to the outer left edge of the figure window. This value can be negative on systems that have more than one monitor.
bottomDistance from the bottom edge of the primary display to the outer bottom edge of the figure window. This value can be negative on systems that have more than one monitor.
widthDistance between the right and left outer edges of the figure.
heightDistance between the top and bottom outer edges of the figure.

All measurements are in units specified by the Units property.

If you attempt to set the OuterPosition property when the figure is docked, this warning displays:

Warning: Cannot set OuterPosition while
WindowStyle is 'docked' 

    Note:   On Microsoft® Windows systems, figure windows are always at least 104 pixels wide, regardless of the value of the OuterPosition property.

Example: [230 250 570 510]

Data Types: double

UnitsUnits of measurement'pixels' (default) | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

Units of measurement, specified as 'pixels', 'normalized', 'inches', 'centimeters', 'points', or 'characters'.

MATLAB uses these units to interpret the location and size values of the Position property:

  • The size of a figure specified in pixel units depends on the system display settings and resolution.

  • Normalized units map the lower left corner of the parent container to (0,0) and the upper right corner to (1.0,1.0).

  • Inches, centimeters, and points are absolute units. 1 point = 1/72 inch.

  • Character units are determined by the default system font. Each character unit is the width of the letter x. The height of each character unit is the distance between the baselines of two lines of text.

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

If you change the value of the Units property, it is good practice to return it to its default value after completing your computation to avoid affecting other functions that assume the Units property is set to the default value.

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

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

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

ResizeWindow resize mode'on' (default) | 'off'

Window resize mode, specified as:

  • 'on' — Users can resize the figure window.

  • 'off' — Users cannot resize the figure window. The figure window does not display any resizing controls.

SizeChangedFcnWindow resize callback function'' (default) | function handle | cell array | string

Callback function that executes when the figure size changes, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

Define this callback function when you want to customize the layout of a GUI beyond what the Position and Units properties provide.

The SizeChangedFcn callback executes under these circumstances:

  • The figure becomes visible for the first time.

  • The figure is visible while its drawable area changes. The drawable area is the area inside the outer bounds of the figure.

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

These are some of the important characteristics of the SizeChangedFcn callback and some recommended best practices:

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

  • Use the gcbo function in your SizeChangedFcn code to get the figure object that the user is resizing.

Example: Uicontrol That has Constant Height

This example code shows how to create a GUI layout containing a uicontrol having a constant height at the top of the figure. To see how it works, copy and paste this code into an editor and save it as sbar.m.

function sbar(src,callbackdata)
   u = findobj(gcbo,'Tag','StatusBar');
   fig = gcbo;
   old_units = fig.Units;
   fig.Units = 'pixels';
   sbar_units = u.Units;
   u.Units = 'pixels';
   figpos = fig.Position;
   upos = [1 figpos(4) - 20 figpos(3) 20];
   u.Position = upos;
   u.Units = sbar_units;
   fig.Units = old_units;
   u.Visible = 'on';
end

Then, run the following code:

f = figure('Visible','off'); 
u = uicontrol('Style','edit', 'Tag','StatusBar');
f.SizeChangedFcn = @sbar;
f.Visible = 'on';

The sbar function maintains a 20-pixel uicontrol height and sets the uicontrol width equal to the width of the figure. Notice the use of the findobj function to retrieve the uicontrol object. This function also calls the gcbo function to access the figure object.

Data Types: function_handle | cell | char

ResizeFcnFigure resize callback function'' (default) | function handle | cell array | string

Callback function that executes when the figure size changes, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

    Note:   Use of the ResizeFcn property is not recommended. It might be removed in a future release. Use SizeChangedFcn instead.

Data Types: function_handle | cell | char

Multiple Plots

expand all

NextPlotDirective 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 table describes the effects of each value.

Property ValueEffect
'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 who are not hidden before adding new objects. Does not reset figure properties.

Equivalent to using the clf command.

'replace'

Removes all axes objects and resets figure properties to their defaults before adding new graphics objects.

Equivalent to using the clf reset command.

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

Interactive Control

expand all

SelectedSelection status of figure'off' (default) | 'on'

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

SelectionHighlightAbility of figure to highlight when user selects it'on' (default) | 'off'

    Note:   Use of the figure SelectionHighlight property is not recommended. This property might be removed in a future release.

This property has no effect on figures.

Callback Execution Control

expand all

BusyActionCallback queuing'queue' (default) | 'cancel'

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

  • The running callback is the currently executing callback.

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

The BusyAction property of the source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these values:

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

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

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

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

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

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

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

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a figure callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

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

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

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

    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.

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

HitTestAbility to become current object'on' (default) | 'off'

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

  • Setting the value to 'on' allows the figure to become the current object when the user clicks on it. A value of 'on' also allows the figure CurrentObject property and the gco function to report the figure as the current object.

  • Setting the value to 'off' sets the figure CurrentObject property to an empty GraphicsPlaceholder array when the user clicks on the figure.

Keyboard Control

expand all

CurrentCharacterLast key pressed in figure'' (default) | 1-character string

The last key pressed in the figure, returned as a 1-character string. Use the CurrentCharacter property to obtain user input.

Example: 't'

KeyPressFcnKey-press callback function'' (default) | function handle | cell array | string

The callback function that executes when a user presses a key, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes when the figure window has focus and the user presses a key. If you do not define a function for this property, MATLAB passes key presses to the Command Window. Repeated key presses retain the focus of the figure, and the function executes with each key press. If the user presses multiple keys at approximately the same time, MATLAB detects the key press for the last key pressed.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.

Property

Contents

Character

The character that displays as a result of pressing the key or keys. The character can be empty or unprintable.

Modifier

A cell array containing the names of one or more modifier keys that are being pressed (such as , control, alt, shift). On Macintosh computers, the cell array contains 'command' when the command modifier key is pressed.

Key

The key being pressed, identified by the (lowercase) label on the key, or a descriptive string.

SourceThe object that has focus when the user presses the key.
EventnameThe action that caused the callback function to execute.

Pressing modifier keys affects the callback data in the following ways:

  • Modifier keys can affect the Character property, but do not change the Key property.

  • Certain keys, and keys modified with Ctrl, put unprintable characters in the Character property.

  • Ctrl, Alt, Shift, and several other keys, do not generate Character property data.

You also can query the CurrentCharacter property of the figure to determine which character the user pressed.

Example: @myfun

Example: {@myfun,x}

KeyReleaseFcnKey-release callback function'' (default) | function handle | cell array | string

Key press callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes when the figure object has focus and the user releases a key.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.

Property

Description

Examples:

a

=

Shift

Shift-a

Character

Character interpretation of the key that was released.

'a'

'='

''

'A'

Modifier

Current modifier, such as 'control', or an empty cell array if there is no modifier

{1x0 cell}

{1x0 cell}

{'shift'}

{'shift'}

Key

The key being released, identified by the (lowercase) label on the key, or a descriptive string.

'a'

'equal'

'shift'

'a'

SourceThe object that has focus when the user presses the key.figurefigurefigurefigure
EventnameThe action that caused the callback function to execute.'KeyRelease''KeyRelease''KeyRelease''KeyRelease'

Pressing modifier keys affects the callback data in the following ways:

  • Modifier keys can affect the Character property, but do not change the Key property.

  • Certain keys, and keys modified with Ctrl, put unprintable characters in the Character property.

  • Ctrl, Alt, Shift, and several other keys, do not generate Character property data.

You also can query the CurrentCharacter property of the figure to determine which character the user pressed.

Example: @myfun

Example: {@myfun,x}

WindowKeyPressFcnKey-press callback function for the figure window'' (default) | function handle | cell array | string

Key-press callback function for the figure window, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback executes whenever a key press occurs while either the figure window or any of its children has focus.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.

Property

Contents

Character

The character displayed as a result of pressing the key. The character which can be empty or unprintable

Modifier

A cell array containing the names of one or more modifier keys being pressed (such as control, alt, shift). On Macintosh computers, it contains 'command' when pressing the command modifier key.

Key

The key being pressed, identified by the (lowercase) label on the key, or a descriptive string.

SourceThe object that has focus when the user presses the key.
EventnameThe action that caused the callback function to execute.

Example: @myfun

Example: {@myfun,x}

WindowKeyReleaseFcnKey-release callback function for the figure window'' (default) | function handle | cell array | string

Key-release callback function for the figure window, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback executes whenever a key release occurs while the figure window or any of its children has focus.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.

Property

Contents

Character

The character displayed as a result of the releasing the key or keys. The character which can be empty or unprintable.

Modifier

A cell array containing the names of one or more modifier keys being released (such as control, alt, shift). On Macintosh computers, it contains 'command' when releasing the command modifier key.

Key

The key being released, identified by the (lowercase) label on the key, or a descriptive string.

SourceThe object that has focus when the user releases the key.
EventnameThe action that caused the callback function to execute.

Example: @myfun

Example: {@myfun,x}

Mouse Control

expand all

ButtonDownFcnButton-press callback function'' (default) | function handle | cell array | string

Button-press callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback executes whenever the user clicks a mouse button while the pointer is in the figure window, but not over a child object such as a uicontrol, uipanel, axes, or axes child.

See the figure's SelectionType property to determine whether modifier keys are also pressed.

CurrentPointLocation of last button click in figuretwo-element vector: [x-coordinate, y-coordinate]

Location of the last button click in this figure, returned as a two-element vector. The CurrentPoint property value is measured from the lower left corner of the figure window, in units determined by the Units property. MATLAB updates this property whenever a user presses the mouse button while the pointer is in the figure window.

If a user selects a point in the figure, and you use the values returned by the CurrentPoint property to plot that point, there can be differences in the position due to round-off errors.

CurrentPoint and Cursor Motion

MATLAB updates CurrentPoint before executing callback functions defined for the figure WindowButtonMotionFcn and WindowButtonUpFcn properties. This enables you to query CurrentPoint from these callback functions. It behaves like this:

  • If you define a callback function for the WindowButtonMotionFcn property or the WindowButtonUpFcn property, then MATLAB updates the CurrentPoint property only when the user presses the mouse button within the figure window.

  • If you define a callback function for the WindowButtonMotionFcn property, then MATLAB updates the CurrentPoint property just before executing the callback. The WindowButtonMotionFcn property executes only within the figure window, unless the user presses the mouse button within the figure and keeps the mouse button down while moving the pointer around the screen. In this case, the function executes (and MATLAB updates the CurrentPoint property) anywhere on the screen until the user releases the mouse button.

  • If you define a callback function for the WindowButtonUpFcn property, then MATLAB updates the CurrentPoint property just before executing the callback. The WindowButtonUpFcn callback executes only while the pointer is within the figure window, unless the user presses the mouse button within the window and releases the mouse button anywhere on the screen. In this case, the function executes, preceded by an update of the CurrentPoint property value.

  • If you add a uicontrol or uitable component to the figure, then MATLAB updates the CurrentPoint property when the user right-clicks the component, or when they left-click the component while the Enable property of that component is 'off' or 'inactive'.

In some situations (such as when the WindowButtonMotionFcn callback takes a long time to execute and the user moves the pointer very rapidly), the CurrentPoint property might not reflect the actual location of the pointer, but rather the location at the time when the WindowButtonMotionFcn callback began execution.

The root PointerLocation property contains the location of the pointer updated synchronously with pointer movement. However, the location is measured with respect to the screen, not a figure window.

SelectionTypeMouse selection type'normal' (default) | 'extend' | 'alt' | 'open'

Mouse selection type, returned as 'normal', 'extend' , 'alt' , or 'open'. MATLAB maintains this property to provide information about the last mouse-button press that occurred within the figure window. This information indicates the type of selection made. Selection types are actions that MATLAB generally associates with particular responses from the user interface software (for example, single-clicking a graphics object places it in move or resize mode; double-clicking a file name opens it, and so on).

The physical action required to make these selections varies by platform. However, all selection types exist on all platforms.

Selection Type

Microsoft Windows

Linux

Mac

'normal'

Click left mouse button.

Click left mouse button.

Click left mouse button.

'extend'

Either of the following:

  • Shift-click left mouse button.

  • Click both left and right mouse buttons.

Either of the following:

  • Shift-click left mouse button.

  • Click middle mouse button.

Any one of the following:

  • Shift-click left mouse button.

  • Click middle mouse button.

  • Click both left and right mouse buttons.

'alternate'

Control-click left mouse button or click right mouse button.

Control-click left mouse button or click right mouse button.

Control-click left mouse button or click right mouse button.

'open'

Double-click any mouse button.

Double-click any mouse button.

Double-click any mouse button.

    Note:   For a list box (uicontrol), the second click of a double-click sets the figure's SelectionType property to 'open'.

WindowButtonDownFcnButton press callback function'' (default) | function handle | cell array | string

Button press callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes whenever a user clicks a mouse button while the pointer is in the figure window. See the WindowButtonMotionFcn property for an example.

    Note:   When using a two-button or three-button mouse on Macintosh systems, right-button and middle-button presses are not always reported. This happens only when a new figure window appears under the mouse cursor and the user clicks the mouse without first moving the mouse. In this circumstance, for the WindowButtonDownFcn callback to work, the user needs to do one of the following:

    • Move the mouse after the figure is created, and then click any mouse button.

    • Press Shift or Ctrl while clicking the left mouse button to perform the Extend and Alternate selection types.

    Pressing the left mouse button (or single mouse button) works without having to take either of the above actions.

For information on how callbacks interact, see the Interruptible and BusyAction properties.

Example: @myfun

Example: {@myfun,x}

WindowButtonMotionFcnMouse-motion callback function'' (default) | function handle | cell array | string

Mouse-motion callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes whenever the user moves the pointer within the figure window. The function must define at least two input arguments: the figure associated with key release and the callback data.

    Note:   On some systems, the WindowButtonMotionFcn callback executes when MATLAB creates a figure, even though there has been no mouse motion within the figure.

Your callback functions might need to update the display by calling the drawnow or pause function, which causes MATLAB to process all callbacks in the queue. Processing the callback queue can cause your callback function to be reentered. Design your code to handle reentrancy and do not depend on global variables that might change state during reentrance.

For information on how callbacks interact, see the Interruptible and BusyAction properties.

Example: Coding Window Button Callback Functions

This example shows how to code all three window button callback functions so that the user can draw lines using mouse motions.

Copy and save the following code to a file on a writable folder on your system. Then, run the code. Click the left mouse button in the axes and move the cursor. Left-click to define the line end point. Right-click to end drawing mode.

function window_motion_test
% 
figure('WindowButtonDownFcn',@wbdcb)
ah = axes('SortMethod','childorder');
axis ([1 10 1 10])
title('Click and drag')
   function wbdcb(src,callbackdata)
     if strcmp(src.SelectionType,'normal')
        src.Pointer = 'circle';
        cp = ah.CurrentPoint;
        xinit = cp(1,1);
        yinit = cp(1,2);
        hl = line('XData',xinit,'YData',yinit,...
        'Marker','p','color','b');
        src.WindowButtonMotionFcn = @wbmcb;
        src.WindowButtonUpFcn = @wbucb;
     end    
 
        function wbmcb(src,callbackdata)
           cp = ah.CurrentPoint;
           xdat = [xinit,cp(1,1)];
           ydat = [yinit,cp(1,2)];
           hl.XData = xdat;
           hl.YData = ydat;
           drawnow
        end
   
        function wbucb(src,callbackdata)
           if strcmp(src.SelectionType,'alt')
              src.Pointer = 'arrow';
              src.WindowButtonMotionFcn = '';
              src.WindowButtonUpFcn = '';
           else
              return
           end
        end
  end
end

WindowButtonUpFcnButton-release callback function'' (default) | function handle | cell array | string

Button-release callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes whenever a user releases a mouse button.

The button-up callback is associated with the figure window in which a previous button-down action occurred. Therefore, the pointer need not be in the figure window when the user releases the button to generate the button-up callback.

If the callback functions defined by the WindowButtonDownFcn or WindowButtonMotionFcn properties contain drawnow commands or call other functions that contain drawnow commands and the Interruptible property is set to 'off', then the WindowButtonUpFcn callback might not be called. You can prevent this situation by setting the Interruptible property to 'on'.

Your callback functions might need to update the display by calling the drawnow or pause function, which causes MATLAB to process all callbacks in the queue. Processing the queue can cause your callback function to be reentered. For example, a drawnow command in the WindowButtonUpFcn callback might result in the WindowButtonUpFcn callback being called again before the first call has finished. Design your code to handle reentrancy and do not depend on global variables that might change state during reentrance.

You can use the Interruptible and BusyAction figure properties to control how callbacks interact.

Example: @myfun

Example: {@myfun,x}

WindowScrollWheelFcnMouse-scroll-wheel callback'' (default) | function handle | cell array | string

Mouse-scroll-wheel callback, 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback executes when the user moves the mouse-scroll-wheel while the figure has focus. MATLAB executes the callback with each single mouse-scroll-wheel click.

Be aware that it is possible for another object to capture the mouse-scroll-wheel movement from MATLAB. For example, if the figure contains Java® or ActiveX® control objects that are listening for mouse-scroll-wheel movements, then these objects can capture the activity and prevent the WindowScrollWheelFcn callback from executing.

WindowScrollWheelFcn Callback Data

When the callback is a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in the following table. You can access these properties inside the callback function using dot notation.

Property

Contents

VerticalScrollCount

A positive or negative integer that indicates the number of mouse-scroll-wheel clicks. Positive values indicate clicks of the wheel scrolled in the down direction. Negative values indicate clicks of the wheel scrolled in the up direction.

VerticalScrollAmount

The current system setting for the number of lines that are scrolled for each click of the scroll wheel. If the mouse property setting for scrolling is set to One screen at a time, the VerticalScrollAmount property is 1.

Effects on Other Properties

The WindowScrollWheelFcn property value has the following effects on these properties:

  • CurrentObject property — The WindowScrollWheelFcn property has no effect on the CurrentObject property.

  • CurrentPoint property — If there is no callback defined for the WindowScrollWheelFcn property, then MATLAB does not update the CurrentPoint property as the user turns the scroll wheel. However, if there is a callback defined for the WindowScrollWheelFcn property, then MATLAB updates the CurrentPoint property just before executing the callback. This enables you to determine the point at which the mouse scrolling occurred.

  • SelectionType property — The WindowScrollWheelFcn property has no effect on the SelectionType property.

Values Returned by VerticalScrollCount

When a user moves the mouse scroll wheel by one click, MATLAB increments the count by +/- 1, depending on the direction of the scroll (scroll down being positive). When MATLAB calls the WindowScrollWheelFcn callback, the counter resets. In most cases, this means that the absolute value of the returned value is 1. However, if the WindowScrollWheelFcn callback takes a long enough time to return or the user spins the scroll wheel very fast, or both, then the returned value can have an absolute value greater than one.

The actual value returned by VerticalScrollCount property is the algebraic sum of all mouse-scroll-wheel clicks that occurred since last processed. This enables your callback to respond correctly to the user action.

Example: Code WindowScrollWheelFcn Callback

This example creates a graph and enables users to use the mouse scroll wheel to change the range over which MATLAB evaluates a mathematical function. In addition, it updates the graph to reflect the new limits as the user turns the scroll wheel.

Copy and save the function to a writable folder on your system. Then, run the code. Mouse over the figure and scroll your mouse wheel.

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

   function re_eval(x)
      y = 4.*cos(x)./(x+2);
      h.YData = y;
      h.XData = x;
      a.XLim = [0 x(end)];
      drawnow
   end % re_eval
end % scroll_wheel

UIContextMenuFigure context menuempty GraphicsPlaceholder array (default) | uicontextmenu object

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

Window Control

expand all

CloseRequestFcnFigure close request callback function'' (default) | function handle | cell array | string

Figure close request callback 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.

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

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

The basic mechanism is:

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

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

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

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

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

Example: Code CloseRequestFcn to Display Dialog Box

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

function my_closereq(src,callbackdata)
% Close request function 
% to display a question dialog box 
   selection = questdlg('Close This Figure?',...
      'Close Request Function',...
      'Yes','No','Yes'); 
   switch selection, 
      case 'Yes',
         delete(gcf)
      case 'No'
      return 
   end
end

Now, create a figure specifying my_closereq for the CloseRequestFcn:

figure('CloseRequestFcn',@my_closereq)

Close the figure window and the question dialog box displays.

WindowStyleFigure window behavior'normal' (default) | 'modal' | 'docked'

Figure window behavior, specified as one of the following:

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

  • 'modal' — The figure displays on top of all existing figure windows, making them inaccessible as long as the top figure exists and remains modal. However, any new figures created after a modal figure will display. For example, plots created by a modal GUI stack on top of the modal window and are accessible. The figures containing these plots can be modal as well.

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

  • 'docked' — The figure displays in the desktop or a document window. This code docks the figure and sets the DockControls property to 'on', if it was set to 'off'.

    f = figure;
    f.WindowStyle = docked;

    If the WindowStyle property is set to 'docked', you cannot set the DockControls property to 'off'.

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

    • When you create UI windows, always specify the WindowStyle property. If you also want to set the Resize, Position, or OuterPosition properties of the figure, then set the WindowStyle property first.

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

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

Modal Window Style Behavior

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

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

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

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

Creation and Deletion Control

expand all

BeingDeletedDeletion status of figure'off' (default) | 'on'

This property is read only.

Deletion status of figure, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the figure begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the figure no longer exists.

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

CreateFcnFigure creation functionfunction handle | cell array | string

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

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

Use the gcbo function in your CreateFcn code to get the handle to the figure that is being created.

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

    Note:   Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. Copying the figure object causes the CreateFcn callback to execute repeatedly.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnFigure deletion functionfunction handle | cell array | string

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

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

Use the gcbo function in your DeleteFcn code to get the handle to the figure that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

CurrentAxesTarget axes in current figureaxes object

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

To get the current axes pbject without forcing the creation of an axes if one does not exist, query the figure CurrentAxes property.

fh = gcf;
ah = fh.CurrentAxes

MATLAB returns h as an empty array if there is no current axes. Be aware that gcf creates a figure if one does not exist.

CurrentObjectMost recently selected component in figureobject

Most recently selected component in the Figure, specified as an object. MATLAB sets the CurrentObject property to the last object the user clicked. This object is the front-most object in the view. You can use this property to determine which object a user has selected.

An object's HitTest property controls whether that object can become the CurrentObject.

Clicking an object whose HandleVisibility property is off (such as axis labels and title) causes the CurrentObject property to be set to empty. To avoid returning an empty value when users click a hidden object, set HitTest property of the hidden object to 'off'.

Moving the cursor over objects does not update the CurrentObject. Users must click objects to update this property. See the CurrentPoint property for related information.

If you are looking for a quick way to access the current object, consider using the gco command.

FileNameGUI FIG-file namestring

GUI FIG-file name, specified as a string. GUIDE stores the name of the FIG-file in which it saves the GUI layout in this property. In non-GUIDE GUIs, by default, the FileName property is empty. You can specify the FileName property in non-GUIDE GUIs and access it to verify which GUI is running or whether you have saved the GUI.

Example: 'myguifile.fig'

IntegerHandleAbility to assign figure number'on' (default) | 'off'

Ability to assign figure number, specified as 'on' or 'off'.

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

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

NumberFigure numberinteger | []

This property is read only.

Figure number, 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', Number is an empty array.

If IntegerHandle is 'on', the Number property value is an integer value. If a figure is deleted, MATLAB reuses that figure's number for the next figure window created.

Example: 3

TagFigure identifier' ' (default) | string

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

Example: 'Plotting Figure'

TypeType of Figure object 'figure'

This property is read only.

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

UserDataData to associate with the figure objectempty array (default) | array

Data to associate with the figure object, specified as any array. Specifying UserData can be useful for sharing data values within and across GUIs you create. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

Parent/Child

expand all

ParentFigure parentroot object

Figure parent, returned as a root object.

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

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

You cannot add or remove children using the Children property of the figure. 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 handle.

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

HandleVisibilityVisibility of figure handle'on' (default) | 'callback' | 'off'

Visibility of figure handle, specified as 'on', 'callback', or 'off'.

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

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

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

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

Pointers

expand all

PointerPointer symbol'arrow' (default) | string

Pointer symbol, specified as a string. Valid strings are listed in the following table. By convention, each symbol commonly indicates a particular usage. However, MATLAB does not enforce rules for the use of any symbols. The appearance of the symbol that displays for a given string is operating-system dependent.

Typical Usage Indicated

Symbol String

Editing location in text

'ibeam'

Point on a graphics object

'crosshair'

Point anywhere in the figure

'arrow'

Busy system

'watch'

Resizing an object from a top-left or bottom-right corner

'topl' or 'botr'

Resizing an object from a top-right or bottom-left corner

'topr' or 'botl'

A hot spot

'circle'

A point

'cross'

Moving an object

'fleur'

Resizing an object from the left side

'left'

Resizing an object from the right side

'right'

Resizing an object from the top or bottom

'top' or 'bottom'

Clickable icon

'hand'

    Note:   The 'fullcrosshair' option was removed in R2014b.

Setting Pointer property to 'custom' enables you to define your own pointer symbol. See the PointerShapeCData property for more information.

PointerShapeCDataPointer shape16-by-16 matrix

Pointer shape MATLAB uses when the Pointer property is set to 'custom', specified as a 16-by-16 matrix. The matrix defines a 16-by-16 pixel pointer using the following values:

  • 1 — Color pixel black.

  • 2 — Color pixel white.

  • NaN — Make pixel transparent, such that underlying screen shows through

Element (1,1) of the PointerShapeCData matrix corresponds to the upper-left corner of the pointer. Setting the Pointer property to one of the predefined pointer symbols does not change the value of the PointerShapeCData. Computer systems supporting 32-by-32 pixel pointers fill only one quarter of the available pixmap.

PointerShapeHotSpotActive area of pointer[1 1] — upper-left corner (default) | two-element vector

Active area of pointer, specified as a two-element vector. The vector specifies the row and column indices in the PointerShapeCData matrix defining the pixel indicating the pointer location. The CurrentPoint property and the root object's PointerLocation property specify the location.

Printing

expand all

PaperSizeSize of the current PaperType[width height]

Size of the current PaperType, specified as [width height]. The default value is locale-dependent, as follows:

  • United States — [8.5000 11]

  • Europe and Asia — [21 29.7]

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

See the PaperType property to select a standard paper size.

    Tip   Use the PaperType property instead of the PaperSize property if you do not want to be concerned with setting the PaperUnits property.

PaperUnitsOutput measurement units'inches' | 'centimeters' | 'normalized' | 'points'

Output measurement units measured from the bottom of the page, specified as one of the following values:

  • 'inches'— absolute unit

    This is the default when the locale is the United States.

  • 'normalized' — maps the lower left corner of the page to (0, 0) and the upper right corner to (1.0, 1.0)

  • 'centimeters'— absolute unit

    This is the default when the locale is Europe or Asia.

  • 'points' — absolute unit. One point equals 1/72 of an inch

This property affects all printed and exported output, not just output printed to paper.

MATLAB uses these units with the PaperPosition and PaperSize properties.

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

PaperOrientationFigure orientation on printed page'portrait' (default) | 'landscape'

Figure orientation on printed page, specified as 'portrait' or 'landscape'.

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

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

See the orient function for more information.

PaperPositionFigure location and size on page [left bottom width height]

Figure location and size on the page, specified as [left bottom width height]. Page refers to printed pages and files exported to PDF or PostScript® formats. The left value specifies the distance from the left side of the page to the left side of the figure. The bottom value specifies the distance from the bottom of the page to the bottom of the figure. Together these distances specify the lower left corner of the figure position.

The width and height values define the dimensions of the figure. The PaperUnits property specifies the units of measurement.

    Note:   When exporting to a nonpage format, such as to image file formats or encapsulated PostScript (EPS), MATLAB uses the width and height values only.

Example: [.25 .25 8 6]

PaperPositionModeDirective for honoring PaperPosition property'manual' (default) | 'auto'

Directive for honoring the PaperPosition property, specified as one of the following:

  • 'manual' — MATLAB honors the value specified by the PaperPosition property.

  • 'auto' — MATLAB prints the figure the same size as it appears on the computer screen. For page formats, the output is centered on the page.

    To determine the output size when PaperPosition is 'auto', the figure's size (width and height) is converted to inches based on the screen resolution. MATLAB generates output to match that size, based on the output resolution. For example, a figure that is 500 x 400 pixels on a screen that has a resolution of 100 dpi measures 5x4 inches; when output at 150 dpi, the image will be 750 x 600 pixels (5 inches * 150 dpi x 4 inches * 150 dpi)

      Tip   To generate output that matches the on-screen size in pixels, call print with the -r0 option.

PaperTypeStandard paper size selectionstring

Standard paper size selection, specified as a string.

The default setting is locale-dependent, as follows:

  • United States — 'usletter'

  • Europe and Asia — 'a4'

Valid strings are described in the table that follows. You can enter strings using uppercase or lowercase letters, but MATLAB always stores the strings using lowercase.

To position the printed figure on a new paper size, you might need to change the setting of the PaperPosition property. Consider setting the PaperUnits property to 'normalized'l This setting enables MATLAB to automatically size the figure to occupy the same relative amount of the printed page, regardless of the paper size.

Property Value

Size (Width x Height)

'usletter'

8.5-by-11 inches

'uslegal'

8.5-by-14 inches

'tabloid'

11-by-17 inches

'a0'

841-by-1189 mm

'a1'

594-by-841 mm

'a2'

420-by-594 mm

'a3'

297-by-420 mm

'a4'

210-by-297 mm

'a5'

148-by-210 mm

'b0'

1029-by-1456 mm

'b1

728-by-1028 mm

'b2'

514-by-728 mm

'b3'

364-by-514 mm

'b4'

257-by-364 mm

'b5'

182-by-257 mm

'arch-a'

9-by-12 inches

'arch-b'

12-by-18 inches

'arch-c'

18-by-24 inches

'arch-d'

24-by-36 inches

'arch-e'

36-by-48 inches

'a'

8.5-by-11 inches

'b'

11-by-17 inches

'c'

17-by-22 inches

'd'

22-by-34 inches

'e'

34-by-43 inches

InvertHardcopyDirective to use black on white background when printing or exporting'on' (default) | 'off'

Directive to use black on white background when printing or exporting, specified as the string 'on' or 'off'. Printing a figure that has a background color (Color property) that is not white results in poor contrast between graphics objects and the figure background; and also consumes a lot of printer toner.

If you set the InvertHardCopy property to 'on', MATLAB changes the color of the figure and axes to white and the axis lines, tick marks, axis labels, etc., that are currently white to black. The lines, text, and edges of patches and surfaces might be changed, depending on the print command options you specify.

If you set InvertHardCopy to 'off', the printed or exported output matches the colors displayed on the screen.

Was this topic helpful?