Control appearance and behavior of figure window (2024)

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 menu children still exist in the Children property of the figure. However, the menus do not display while WindowStyle is set to 'Modal'.

Figure toolbar display, specified as one of the following:

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

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

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

Window state, specified as one of these values:

Clicking the minimize, maximize, or restore button provided by the operating system sets the WindowState property accordingly. Pressing Ctrl+F11 (Windows^® and Linux^®) or Ctrl+Command+f (macOS) toggles the 'fullscreen' state.

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

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

This property value is identical to the Position property value.

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

This table describes each element in the vector.

All measurements are in units specified by the Units property.

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

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

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

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

Example: figure('Colormap',[1 0 1; 0 0 1; 1 1 0]) sets the color map to three colors: magenta, blue, and yellow.

MATLAB accesses these colors by their row number.

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

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

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

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

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

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

This table describes the effects of each value.

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.

Renderer for screen display and printing, specified as one of these values:

Setting the Renderer property is not supported in MATLAB Online.

OpenGL Hardware and Software Implementations

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

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

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

Software OpenGL Selection

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

The following software versions are available:

Determine OpenGL Library Version

To determine the version and vendor of the OpenGL library that MATLAB is using on your system, call the rendererinfo function. For example, this command gets the information for the current axes and stores it in a structure called info.

info = rendererinfo(gca)

This structure also provides the name of the graphics renderer in the GraphicsRenderer field. For example, if MATLAB is using hardware-accelerated OpenGL, the field returns 'OpenGL Hardware'. If MATLAB is using software OpenGL, the field returns 'OpenGL Software'.

XServer Connection Lost

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

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

 matlab -softwareopengl

Renderer selection, specified as:

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

Axes graphics smoothing, 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.

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:

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.

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

Setting the GraphicsSmoothing property is not supported in MATLAB Online.

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

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

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

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

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

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

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

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

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

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

See the orient function for more information.

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

Figure background color when saving or printing, 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.

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

Custom Pointer Symbol

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

Limitations

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

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

Each element in the matrix defines the brightness level for 1 pixel in the pointer, where the element can have one of these values:

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

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

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.

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 figure, specified as an Axes object, a PolarAxes object, or a graphics object such as a HeatmapChart.

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

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

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

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

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

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

Current point, returned as a two-element vector. The vector contains the (x, y) coordinates of the mouse pointer, measured from the lower-left corner of the figure. The values are in units specified by the Units property.

The coordinates update when you do any of the following:

If the figure has a callback that responds to mouse interactions, and you trigger that callback faster than the system can execute the code, the coordinates might not reflect the actual location of the pointer. Instead, they are the location when the callback began execution.

If you use the CurrentPoint property to plot points, the coordinate values might contain rounding error.

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

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

Button down callback, specified as one of these values:

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

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

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

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

This callback function executes when the user presses a key while the figure or a child object has focus. If the user presses a key on a UIControl or Table component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

If the user presses multiple keys at approximately the same time, MATLAB detects all the keys.

The KeyPressFcn callback can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of this object.

The KeyPressFcn callback is not supported in the Live Editor.

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

The CurrentCharacter property also returns character information.

Key-release callback, specified as one of these values

This callback function executes when the user presses a key while the figure or a child object has focus. If the user releases a key on a UIControl or Table component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

The KeyReleaseFcn callback can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of this object.

The KeyReleaseFcn callback is not supported in the Live Editor.

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

Close request callback, specified as one of these values:

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

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

The basic mechanism is:

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

Example: Code CloseRequestFcn to Display Dialog Box

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

function my_closereq(src,event)% 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 endend

Now, create a figure specifying my_closereq for the CloseRequestFcn. Notice that the function handle does not explicitly refer to any input arguments, but the function declaration includes two input arguments. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

figure('CloseRequestFcn',@my_closereq)

Close the figure window and the question dialog box displays.

Size changed callback, specified as one of these values:

Define this callback to customize the app layout when the size of this container changes (e.g., when the user resizes the window).

The SizeChangedFcn callback executes when:

Other important points to consider when defining a SizeChangedFcn callback:

Example: Edit Field With Constant Height

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

function myuif = figure('Visible','off','SizeChangedFcn',@sbar); u = uicontrol('Style','edit','Tag','StatusBar');f.Visible = 'on'; function sbar(src,event) old_units = src.Units; src.Units = 'pixels'; sbar_units = u.Units; u.Units = 'pixels'; fpos = src.Position; upos = [1 fpos(4) - 20 fpos(3) 20]; u.Position = upos; u.Units = sbar_units; src.Units = old_units; u.Visible = 'on'; endend

Notice that the function handle for sbar does not explicitly refer to any input arguments, but the function declaration includes two input arguments. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

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

This callback executes when the user clicks anywhere in the figure or one of its child objects. If the user clicks a UIControl or Table component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

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

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

Typically, this callback function executes whenever the user moves the pointer within the figure. However, if the user clicks and holds the mouse button and moves the pointer outside the figure, the WindowButtonMotionFcn callback executes while the pointer is outside the figure.

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

Example: Simple Drawing App

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

function drawing_appfigure('WindowButtonDownFcn',@wbdcb)ah = axes('SortMethod','childorder');axis ([1 10 1 10])title('Click and drag') function wbdcb(src,event) seltype = src.SelectionType; if strcmp(seltype,'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,event) cp = ah.CurrentPoint; xdat = [xinit,cp(1,1)]; ydat = [yinit,cp(1,2)]; hl.XData = xdat; hl.YData = ydat; drawnow end function wbucb(src,event) last_seltype = src.SelectionType; if strcmp(last_seltype,'alt') src.Pointer = 'arrow'; src.WindowButtonMotionFcn = ''; src.WindowButtonUpFcn = ''; else return end end endend

Notice that the callback function handles do not explicitly refer to any input arguments, but the function declarations include two input arguments. MATLAB passes these arguments automatically when the callbacks execute. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

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

This callback executes when the user releases the mouse button anywhere in the figure or one of its child objects. If the user releases the mouse button on a UIControl or Table component, the callback does not execute unless the Enable property is set to 'off' or 'inactive'.

The button-up actions are associated with button-down actions in the figure. The mouse pointer must be inside the figure when the button-down action occurs, but it can be outside the figure when the button-up action occurs.

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

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

This callback function executes when the user presses a key while the figure or a child object has focus.

This callback function can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of this object.

The WindowKeyPressFcn callback is not supported in the Live Editor.

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

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

This callback function executes when the user releases a key while the figure or a child object has focus.

This callback function can access specific information about the user’s interaction with the keyboard. MATLAB passes this information in a KeyData object as the second argument to your callback function. This table lists the properties of this object.

The WindowKeyReleaseFcn callback is not supported in the Live Editor.

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

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

This callback executes when the user moves the scroll wheel while the figure or any if its children have focus. However, other objects can capture scroll wheel movement and interfere with the execution of this callback.

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

The WindowScrollWheelFcn callback can access specific information when the user rotates the scroll wheel. MATLAB passes this information in a ScrollWheelData object as the second argument to your callback function. This table lists the properties of the ScrollWheelData object.

The WindowScrollWheelFcn callback is not supported in the Live Editor.

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

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 = 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,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; x = [0:.1:xd(end)-inc+.1]; % Don't let xd = 0; 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 endend

Notice that the function handle for figScroll does not explicitly refer to any input arguments, but the function declaration includes two input arguments. MATLAB passes these arguments automatically when the callback executes. The first argument is the UI component that triggered the callback, and the second argument provides event data to the callback function.

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

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

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

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

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

Visibility of figure object, 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).

Number title, 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 you set this property to 'on', the title of the figure includes the phrase 'Figure n', where n is the value of the Number property.

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

Use integer handle, 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.

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

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

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

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

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

This property is read-only.

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