Figure Properties

Creating Figure Objects

Use figure to create figure objects.

Modifying Properties

You can set and query graphics object properties in two ways:

• Customize Objects in Graph is an interactive tool that enables you to see and change object property values.

• The set and get commands enable you to set and query the values of Handle Graphics^® properties.

To change the default values of properties, see Setting Default Property Values in the Handle Graphics Objects documentation.

Figure Property Descriptions

This section provides a description of properties. Curly braces { } enclose default values.

Alphamap

m-by-1 matrix of alpha values

Figure alphamap. An array of non-NaN alpha values. 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. The default alphamap contains 64 values that progress linearly from 0 to 1.

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

BeingDeleted

on | {off} (read-only)

This object is being deleted. Mechanism to determine if objects are in the process of being deleted. MATLAB sets theBeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property). It remains set to on while the delete function executes, after which the object no longer exists.

For example, an object's delete function calls other functions that act on a number of different objects. If a function does not need to perform an action on an about-be-deleted object, it can check the object's BeingDeleted property before acting.

See the close and delete function reference pages for related information.

BusyAction

cancel | {queue}

Callback function interruption. The BusyAction property enables you to control how MATLAB handles events that potentially interrupt executing callback functions. If there is a callback function executing, callback functions invoked subsequently always attempt to interrupt it. If the Interruptible property of the object whose callback is executing is on (the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible property is off, theBusyAction property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are

• cancel — Discard the event that attempted to execute a second callback function.

• queue — Queue the event that attempted to execute a second callback function until the current callback finishes.

ButtonDownFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Button press callback function. Executes whenever you press a mouse button while the pointer is in the figure window, but not over a child object (i.e., uicontrol, uipanel, axes, or axes child). Define the ButtonDownFcn as a function handle. The function must define at least two input arguments (handle of figure associated with the mouse button press and an empty event structure).

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

For information on the syntax of callback functions, see Function Handle Callbacks.

Using the ButtonDownFcn

This example creates a figure and defines a function handle callback for the ButtonDownFcn property. When the user Ctrl-clicks the figure, the callback creates a new figure having the same callback.

Click to view in editor — This link opens the MATLAB Editor with the following example.

Click to run example — Ctrl-click the figure to create a new figure.

fh_cb = @newfig; % Create function handle for newfig function
figure('ButtonDownFcn',fh_cb);

function newfig(src,evnt)
   if strcmp(get(src,'SelectionType'),'alt')
      figure('ButtonDownFcn',fh_cb)
   else
      disp('Use control-click to create a new figure')
   end
end

Children

vector of handles

Children of the figure. A vector containing the handles of all axes, user-interface objects displayed within the figure. You can change the order of the handles and thereby change the stacking of the objects on the display.

When an object's HandleVisibility property is off, it is not listed in its parent's Children property. See HandleVisibilityfor more information.

Clipping

{on} | off

Clipping mode. This property has no effect on figures.

CloseRequestFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Function executed on figure close. Executes whenever you issue the close command (either a close(figure_handle) or aclose all), when you close a figure window from the computer's window manager menu, or when you quit MATLAB.

The CloseRequestFcn provides a mechanism to intervene in the closing of a figure. It allows you to, 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 GUI.

The basic mechanism is:

1. A user issues the close command from the command line, by closing the window from the computer's window manager menu, or by quitting MATLAB.

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

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

Note that closereq honors the ShowHiddenHandles setting during figure deletion and will not delete hidden figures.

Redefining the CloseRequestFcn

Define the CloseRequestFcn as a function handle. For example:

set(gcf,'CloseRequestFcn',@my_closefcn)

Where @my_closefcn is a function handle referencing function my_closefcn.

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

A useful application of the close request function is to display a question dialog box asking the user to confirm the close operation. The following function illustrates how to do this.

Click to view in editor — This link opens the MATLAB editor with the following example.

Click to run example — Ctrl- click the figure to create a new figure.

function my_closereq(src,evnt)
% User-defined 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 using the CloseRequestFcn:

figure('CloseRequestFcn',@my_closereq)

To make this function your default close request function, set a default value on the root level.

set(0,'DefaultFigureCloseRequestFcn',@my_closereq)

MATLAB then uses this setting for the CloseRequestFcn of all subsequently created figures.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Color

ColorSpec

Background color. Controls the figure window background color. You can specify a color using a three-element vector of RGB values or one of the MATLAB predefined names. See ColorSpec for more information.

Colormap

m-by-3 matrix of RGB values

Figure colormap. An array of red, green, and blue (RGB) intensity values that define m individual colors. MATLAB accesses 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.

Number of Colors Allowed

Colormaps can be any length, but must be three columns wide. The default figure colormap contains 64 predefined colors.

Objects That Use Colormaps

Colormaps affect the rendering of surface, image, and patch objects, but generally do not affect other graphics objects. Seecolormap and ColorSpec for more information.

CreateFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Callback function executed during figure creation. Executes when MATLAB creates a figure object. You must define this property as a default value on the root level. For example, the statement:

set(0,'DefaultFigureCreateFcn',@fig_create)

defines a default value on the root level that causes all figures created to execute the setup function fig_create, which is defined below:

function fig_create(src,evnt)
set(src,'Color',[.2 .1 .5],...
   'IntegerHandle','off',...
   'MenuBar','none',...
   'ToolBar','none')
end

MATLAB executes the create function after setting all properties for the figure. Setting this property on an existing figure object has no effect.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

The handle of the object whose CreateFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo or the handle of the object generating the callback (the source of the event). For example, this,

f = figure('CreateFcn',@(o,e) keyboard)
K>> gcbo 

and this each return 1:

f = figure('CreateFcn',@(o,e) keyboard)
K>> o 

CurrentAxes

handle of current axes

Target axes in this figure. MATLAB sets this property to the handle of the figure's current axes (the handle returned by the gcacommand when this figure is the current figure). 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 CurrentAxes does not restack it above all other axes.

You can make an axes current using the axes and set commands. For example, axes(axes_handle) andset(gcf,'CurrentAxes',axes_handle) both make the axes identified by the handle axes_handle the current axes. In addition, axes(axes_handle) restacks the axes above all other axes in the figure.

If a figure contains no axes, get(gcf,'CurrentAxes') returns the empty matrix. Note that the gca function actually creates an axes if one does not exist.

CurrentCharacter

single character

Last key pressed. MATLAB sets this property to the last key pressed in the figure window. Use CurrentCharacter to obtain user input.

CurrentObject

object handle

Handle of current object. MATLAB sets this property to the handle of the last object clicked on by the mouse. This object is the frontmost object in the view. You can use this property to determine which object a user has selected. The function gcoprovides a convenient way to retrieve the CurrentObject of the CurrentFigure.

Note that the HitTest property controls whether an object can become the CurrentObject.

Hidden Handle Objects

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 hidden objects, set the hidden object's HitTestproperty to off.

Mouse Over

Note that cursor motion over objects does not update the CurrentObject; you must click objects to update this property. See the CurrentPoint property for related information.

CurrentPoint

two-element vector: [x-coordinate, y-coordinate]

Location of last button click in this figure. MATLAB sets this property to the location of the pointer at the time of the most recent mouse button press. MATLAB updates this property whenever you press the mouse button while the pointer is in the figure window.

Note that if you select a point in the figure and then 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

In addition to the behavior described above, MATLAB updates CurrentPoint before executing callback routines defined for the figure WindowButtonMotionFcn and WindowButtonUpFcn properties. This enables you to query CurrentPoint from these callback routines. It behaves like this:

• If there is no callback routine defined for the WindowButtonMotionFcn or the WindowButtonUpFcn, then MATLAB updates the CurrentPoint only when the mouse button is pressed down within the figure window.

• If there is a callback routine defined for the WindowButtonMotionFcn, then MATLAB updates the CurrentPoint just before executing the callback. Note that the WindowButtonMotionFcn executes only within the figure window unless the mouse button is pressed down within the window and then held down while the pointer is moved around the screen. In this case, the routine executes (and the CurrentPoint is updated) anywhere on the screen until the mouse button is released.

• If there is a callback routine defined for the WindowButtonUpFcn, MATLAB updates the CurrentPoint just before executing the callback. Note that the WindowButtonUpFcn executes only while the pointer is within the figure window unless the mouse button is pressed down initially within the window. In this case, releasing the button anywhere on the screen triggers callback execution, which is preceded by an update of the CurrentPoint.

The figure CurrentPoint is updated only when certain events occur, as previously described. In some situations (such as when the WindowButtonMotionFcn takes a long time to execute and the pointer is moved very rapidly), the CurrentPoint might not reflect the actual location of the pointer, but rather the location at the time when the WindowButtonMotionFcn began execution.

The CurrentPoint is measured from the lower-left corner of the figure window, in units determined by the Units property.

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.

See uicontrol for information on how this property is set when you click a uicontrol object.

DeleteFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Delete figure callback function. Executes when the figure object is deleted (for example, when you issue a delete or a closecommand). MATLAB executes the function before destroying the object's properties so these values are available to the callback routine.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

The handle of the object whose DeleteFcn is being executed is accessible through the root CallbackObject property, which you can query using gcbo.

See also the figure CloseRequestFcn property

See Function Handle Callbacks for information on how to use function handles to define the callback function.

DockControls

{on} | off

Displays controls used to dock figure. Determines whether the figure enables the Desktop menu item and the dock figure button in the title bar that allow you to dock the figure into the MATLAB desktop.

• on — Figure docking controls are visible.

• off — The Desktop menu item that enables you to dock the figure is disabled and the figure dock button is not displayed.

See the WindowStyle property for more information on docking figure.

DoubleBuffer

{on} | off

• Note:   This property is now obsolete and has no effect. It was provided for older computer systems to produce flash-free animations.

Flash-free rendering for simple animations. Double buffering is the process of drawing to an off-screen pixel buffer and then printing the buffer contents to the screen once the drawing is complete. Double buffering generally produces flash-free rendering for simple animations (such as those involving lines, as opposed to objects containing large numbers of polygons). Use double buffering with the animated objects' EraseMode property set to normal. Use the set command to disable double buffering.

set(figure_handle,'DoubleBuffer','off')

Double buffering works only when the figure Renderer property is painters.

FileName

String

GUI FIG-file name. GUIDE stores the name of the FIG-file used to save the GUI layout in this property. In non-GUIDE GUIs, by default FileName is empty. You can set the FileName property in non-GUIDE GUIs as well, and get it to verify what GUI is running or whether it has been previously saved.

FixedColors

m-by-3 matrix of RGB values (read-only)

Noncolormap colors. Fixed colors define all colors appearing in a figure window that are not from the figure colormap. These colors include axis lines and labels, the colors of line, text, uicontrol, and uimenu, and text objects, and any colors explicitly defined, for example, with a statement like:

set(gcf,'Color',[0.3,0.7,0.9])

Fixed color definitions reside in the system color table and do not appear in the figure colormap. For this reason, fixed colors can limit the number of simultaneously displayed colors if the number of fixed colors plus the number of entries in the figure colormap exceed your system's maximum number of colors.

(See the root ScreenDepth property for information on determining the total number of colors supported on your system. See the MinColorMap property for information on how MATLAB shares colors between applications.)

• Note:   The FixedColors property is being deprecated and will be removed in a future release

HandleVisibility

{on} | callback | off

Control access to object's handle. Determines when an object's handle is visible in its parent'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 devices (such as a dialog box).

Handles are always visible when HandleVisibility is on.

• on — Handles are always visible.

• callback — Handles are visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have access to object handles.

• off — Handles are invisible at all times. Use this option when a callback invokes a function that could damage the GUI (such as evaluating a user-typed string). This option temporarily hides its own handles during the execution of that function.

Visibility and Handles Returned by Other Functions

When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

When a handle's visibility is restricted using callback or off, the object's handle does not appear in its parent's Childrenproperty, figures do not appear in the root's CurrentFigureproperty, objects do not appear in the root's CallbackObjectproperty or in the figure's CurrentObject property, and axes do not appear in their parent's CurrentAxes property.

Making All Handles Visible

You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibilitysettings (this does not affect the values of the HandleVisibility properties).

Validity of Hidden Handles

Handles that are hidden are still valid. If you know an object's handle, you can pass it to any function that operates on handles, and set and get its properties.

HitTest

{on} | off

Selectable by mouse click. Determines if the figure can become the current object (as returned by the gco command and the figure CurrentObject property) as a result of a mouse click on the figure. If HitTest is off, clicking the figure sets theCurrentObject to the empty matrix.

IntegerHandle

{on} | off

Figure handle mode. Figure object handles are integers by default. When creating a new figure, MATLAB uses the lowest integer that is not used by an existing figure. If you delete a figure, its integer handle can be reused.

If you set this property to off, MATLAB assigns nonreusable real-number handles (for example, 67.0001221) instead of integers. This feature is designed for dialog boxes where removing the handle from integer values reduces the likelihood of inadvertently drawing into the dialog box.

Interruptible

{on} | off

Callback routine interruption mode. Controls whether a figure callback function can be interrupted by subsequently invoked callbacks.

How Callbacks Are Interrupted

MATLAB checks for queued events that can interrupt a callback function only when it encounters a call to drawnow, figure,getframe, or pause in the executing callback function. When executing one of these functions, MATLAB processes all pending events, including executing all waiting callback functions. The interrupted callback then resumes execution.

What Property Callbacks Are Interruptible

The Interruptible property only affects callback functions defined for the ButtonDownFcn, KeyPressFcn, KeyReleaseFcn,WindowButtonDownFcn, WindowButtonMotionFcn, WindowButtonUpFcn, WindowKeyPressFcn, WindowKeyReleaseFcn, andWindowScrollWheelFcn.

See the BusyAction property for related information.

InvertHardcopy

{on} | off

Change hardcopy to black objects on white background. Affects only exported and printed output. Printing a figure having 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.

When InvertHardCopy is on, MATLAB eliminates this effect by changing the color of the figure and axes to white and the axis lines, tick marks, axis labels, etc., to black. lines, text, and the edges of patches and surfaces might be changed, depending on the print command options specified.

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

See print for more information on printing MATLAB figures.

KeyPressFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Key press callback function. Callback function invoked by a key press that occurs while the figure window has focus. Define theKeyPressFcn as a function handle. The function must define at least two input arguments (handle of figure associated with key press and an event structure).

For information on the syntax of callback functions, see Function Handle Callbacks.

When no callback is specified for this property (which is the default state), MATLAB passes any key presses to the Command Window. However, when you define a callback for this property, the figure retains focus with each key press and executes the specified callback with each key press.

KeyPressFcn Event Structure

When you specify the callback as a function handle, MATLAB passes to it a structure to containing the following fields.

Field	Contents
Character	The character displayed as a result of the pressing the key(s), which can be empty or unprintable
Key	The key being pressed, identified by the lowercase label on key or a descriptive string
Modifier	A cell array containing the names of one or more modifier keys being pressed (i.e., control,alt, shift). On Macintosh computers, it contains 'command' when pressing the commandmodifier key

Explore KeyPressFcn Behavior

To view the values of the event data fields for any key or key combination, run the following code:

figure('NumberTitle','off','Menubar','none',...
       'Name',...
				'Press keys to put event data in Command Window',...
       'Position',[560 728 560 200],...
       'KeyPressFcn',@(obj,evt)disp(evt));

Each time you press a key, the KeyPressFcn uses disp to display the event data in the Command Window.

You can also view and run an example GUI, ex_KeyPressFcn.m, which displays keystroke event data in the figure window, and provides an option to write the event data structure to your workspace.

• Click here to view the example in the MATLAB editor

• Click here to add the example to the MATLAB path

• Click to run the example — Press and release various key combinations while the figure has focus. The callback displays event data in text fields in the figure window. The Char Code data is the Character field displayed as a number, not a separate event data field.

Event data passed to a KeyPressFcn and KeyReleaseFcn callbacks have the following characteristics:

• The Key field is always in lower case (contains the non-shifted symbol).

• Modifier keys (Alt, Ctrl, Shift,) return data when pressed alone as well as when pressed in combination with other keys.

• Modifier fields contain a cell array with zero or more strings.

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

• Certain keys, plus keys modified with Ctrl, put unprintable characters in the Character field.

• Ctrl, Alt, Shift, function and several other keys generate no Character field data.

Using the KeyPressFcn

This example creates a figure and defines a function handle callback for the KeyPressFcn property. When you press the p key, the callback exports the figure as a PNG image file. When you press Ctrl+p, the callback exports the figure as a PDF file.

function figure_keypress
    figure('KeyPressFcn',@printfig);
    surf(peaks)
    
    function printfig(src,event)
    % Callback to parse keypress event data to print a figure
        if event.Character == 'p'
            % On some systems you must send the file to a printer manually
            if length(event.Modifier) == 1 && ...
                strcmp(event.Modifier{:},'control')
                % Create PDF file of figure when Ctrl key is down
                print ('-dpdf',['-f' num2str(src)])
            elseif isempty(event.Modifier)
                % Print PNG image of figure when Ctrl is not pressed
                print ('-dpng','-r200',['-f' num2str(src)])
            end
        end
    end
end

KeyReleaseFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Key release callback function. Callback function invoked by a key release that occurs while the figure window has focus. Define the KeyReleaseFcn as a function handle. The function must define at least two input arguments (handle of figure associated with key release and an event structure).

For information on the syntax of callback functions, see Function Handle Callbacks.

KeyReleaseFcn Event Structure

When the callback is a function handle, MATLAB passes a structure as the second argument to the callback function that contains the following fields.

Field	Contents
Character	The character displayed as a result of the releasing the key(s), which can be empty or unprintable
Key	The key being released, identified by the lowercase label on key or a descriptive string
Modifier	A cell array containing the names of one or more modifier keys being released (i.e., control,alt, shift). On Macintosh computers, it contains 'command' when releasing the commandmodifier key

Properties Affected by the KeyReleaseFcn

When a callback is defined for the KeyReleaseFcn property, MATLAB updates the CurrentCharacter figure property just before executing the callback.

Multiple-Key Press Events and a Single-Key Release Event

Consider a figure having callbacks defined for both the KeyPressFcn and KeyReleaseFcn. In the case where you press multiple keys at close to the same time, MATLAB generates repeated KeyPressFcn events only for the last key pressed.

For example, suppose you press and hold down the a key, then press and hold down the s key. MATLAB generates repeatedKeyPressFcn events for the a key until you press the s key, at which point MATLAB generates repeated KeyPressFcn events for the s key. If you then release the s key, MATLAB generates a KeyReleaseFcn event for the s key, but no new KeyPressFcnevents for the a key. When you then release the a key, the KeyReleaseFcn again executes. The KeyReleaseFcn executes its callback every time you release a key while the figure is in focus, regardless of what any KeyPressFcn does.

Event structures passed to a KeyPressFcn and KeyReleaseFcn callbacks have the following characteristics:

• The Key field is always in lower case (contains the non-shifted symbol).

• Modifier keys (Alt, Ctrl, Shift,) return data when pressed alone as well as when pressed in combination with other keys.

• Modifier fields contain a cell array with zero or more strings.

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

• Certain keys, plus keys modified with Ctrl, put unprintable characters in the Character field.

• Ctrl, Alt, Shift, function and several other keys generate no Character field data.

Modifier Keys

When you press and release a key and a modifier key, the modifier key is returned in the event structure Modifier field. If you press and release a modifier key only, its name is not returned in the event structure of the KeyReleaseFcn, but is returned in the event structure of the KeyPressFcn.

Explore KeyReleaseFcn Behavior

The following code example creates a figure and defines a function handle callback for the KeyReleaseFcn property which reports the event data that the callback receives.

• Click here to view the example in the MATLAB editor

• Click here to add the example to the MATLAB path

• Click to run the example — Press and release various key combinations while the figure has focus. The callback displays event data in the Command Window.

function key_releaseFcn
   figure('KeyReleaseFcn',@cb)
      function cb(src,evnt)
      if ~isempty(evnt.Modifier)
         for ii = 1:length(evnt.Modifier)
            out = sprintf('Character: %c\nModifier: %s\nKey: %s\n',...
					evnt.Character,evnt.Modifier{ii},evnt.Key);
            disp(out)
         end
      else
         out = sprintf('Character: %c\nModifier: %s\nKey: %s\n',...
				evnt.Character,'No modifier key',evnt.Key);
         disp(out)
      end
   end   
end

MenuBar

none | {figure}

Enable-disable figure menu bar. Enables you to display or hide the menu bar that MATLAB places at the top of a figure window. The default (figure) is to display the menu bar.

This property affects only built-in menus. This property does not affect menus defined with the uimenu command.

Changing the WindowStyle of a window to 'modal' hides both its toolbar and menu bar, if they exist. Changing WindowStylefrom 'modal' to 'normal' or 'docked' displays any toolbar or menu bar a figure has.

MinColormap

scalar (default = 64)

Minimum number of color table entries used. Specifies the minimum number of system color table entries used by MATLAB to store the colormap defined for the figure (see the Colormap property). In certain situations, you might need to increase this value to ensure proper use of colors.

For example, suppose you run color-intensive applications in addition to MATLAB and have defined a large figure colormap (for example, 150 to 200 colors). MATLAB might select colors that are close but not exact from the existing colors in the system color table because there are not enough slots available to define all the colors you specified.

To ensure that MATLAB uses exactly the colors you define in the figure colormap, set MinColormap equal to the length of the colormap.

set(gcf,'MinColormap',length(get(gcf,'ColorMap')))

Note that the larger the value of MinColormap, the greater the likelihood that other windows (including other MATLAB figure windows) will be displayed in false colors.

• Note:   The MinColormap property is being deprecated and will be removed in a future release

Name

string

Figure window title. Specifies the title displayed in the figure window. By default, Name is empty and the figure title is displayed as Figure 1, Figure 2, and so on. When you set this parameter to a string, the figure title becomes Figure 1: <string>. See the NumberTitle property.

NextPlot

new | {add} | replace | replacechildren

How to add next plot. Determines which figure MATLAB uses to display graphics output. If the value of the current figure is:

• new — Create a new figure to display graphics (unless an existing parent is specified in the graphing function as a property/value pair).

• add — Use the current figure to display graphics (the default).

• replace — Reset all figure properties except Position to their defaults and delete all figure children before displaying graphics (equivalent to clf reset).

• replacechildren — Remove all child objects, but do not reset figure properties (equivalent to clf).

The newplot function provides an easy way to handle the NextPlot property. For more information, see the axes NextPlotproperty and Controlling Graphics Output.

NumberTitle

{on} | off (GUIDE default off)

Figure window title number string. Determines whether the string Figure No. N (where N is the figure number) is prefixed to the figure window title. See the Name property.

OuterPosition

four-element vector

Figure position including title bar, menu bar, tool bars, and outer edges. Specifies the size and location on the screen of the full figure window including the title bar, menu bar, tool bars, and outer edges. Specify the position rectangle with a four-element vector of the form:

rect = [left, bottom, width, height]

where left and bottom define the distance from the lower-left corner of the screen to the lower-left corner of the full figure window. width and height define the dimensions of the window. See the Units property for information on the units used in this specification. The left and bottom elements can be negative on systems that have more than one monitor.

Position of Docked Figures

If the figure is docked in the MATLAB desktop, then the OuterPosition property is specified with respect to the figure group container instead of the screen.

Moving and Resizing Figures

Use the get function to obtain this property and determine the position of the figure. Use the set function to resize and move the figure to a new location. You cannot set the figure OuterPosition when it is docked.

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

PaperOrientation

{portrait} | landscape

Horizontal or vertical paper orientation. Determines how to orient printed figures on the page.

• portrait — Orients the longest page dimension vertically.

• landscape — Orients the longest page dimension horizontally.

See the orient command for more information.

PaperPosition

four-element rect vector

Location on printed page. A rectangle that determines the location of the figure on the printed page. Specify this rectangle with a vector of the form:

 rect = [left, bottom, width, height]

where left specifies the distance from the left side of the paper to the left side of the rectangle and bottom specifies the distance from the bottom of the page to the bottom of the rectangle. Together these distances define the lower-left corner of the rectangle. width and height define the dimensions of the rectangle. The PaperUnits property specifies the units used to define this rectangle.

PaperPositionMode

auto | {manual}

WYSIWYG printing of figure.

• 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, centered on the page.

PaperSize

[width height]

Paper size. Size of the current PaperType, measured in PaperUnits. See PaperType to select standard paper sizes.

PaperType

Select a value from the following table.

Selection of standard paper size. Sets the PaperSize to one of the following standard sizes.

 Paper Sizes Table

Note that you might need to change the PaperPosition property in order to position the printed figure on the new paper size. One solution is to use normalized PaperUnits, which enables MATLAB to automatically size the figure to occupy the same relative amount of the printed page, regardless of the paper size.

PaperUnits

normalized | {inches} | centimeters | points

Hardcopy measurement units. Specifies the units used to define the PaperPosition and PaperSize properties. MATLAB measures all units from the lower-left corner of the page. normalized units map the lower-left corner of the page to (0, 0) and the upper-right corner to (1.0, 1.0). inches, centimeters, and points are absolute units (one point equals 1/72 of an inch).

If you change the value of PaperUnits, 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 PaperUnits is set to the default value.

Parent

handle

Handle of figure's parent. The parent of a figure object is the rootobject object. The handle to the root is always 0.

Pointer

crosshair | {arrow} | watch | topl | 
topr | botl | botr | circle | cross | 
fleur | left | right | top | bottom | 
fullcrosshair | ibeam | custom | hand

Pointer symbol, specified as a string 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.

Commonly Indicates	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 or right	'left' or 'right'
Resizing an object from the top or bottom	'top' or 'bottom'
Aligning a point with other objects on the display	'fullcross'
Clickable icon	'hand'

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

PointerShapeCData

16-by-16 matrix

User-defined pointer. Defines the pointer used when you set the Pointer property to custom. It is a 16-by-16 element matrix defining the 16-by-16 pixel pointer using the following values:

• 1 — Color pixel black.

• 2 — Color pixel white.

• NaN — Make pixel transparent (underlying screen shows through).

Element (1,1) of the PointerShapeCData matrix corresponds to the upper-left corner of the pointer. Setting the Pointerproperty 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.

PointerShapeHotSpot

two-element vector

Pointer active area. Specifies the row and column indices in the PointerShapeCData matrix defining the pixel indicating the pointer location. The location is contained in the CurrentPoint property and the root object's PointerLocation property. The default value is element (1,1), which is the upper-left corner.

Position

four-element vector

Figure position. Specifies the size and location on the screen of the figure window, not including title bar, menu bar, tool bars, and outer edges. Specify the position rectangle with a four-element vector of the form:

rect = [left, bottom, width, height]

where left and bottom define the distance from the lower-left corner of the screen to the lower-left corner of the figure window. width and height define the dimensions of the window. See the Units property for information on the units used in this specification. The left and bottom elements can be negative on systems that have more than one monitor.

Position of Docked Figures

If the figure is docked in the MATLAB desktop or in a figure window container, then the Position property is specified with respect to the figure group container instead of the screen.

Moving and Resizing Figures

You can use the get function to obtain this property and determine the position of the figure and you can use the set function to resize and move the figure to a new location. You cannot set the figure Position when it is docked.

• Note:   On Windows systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the Positionproperty. Also, the figure window includes the area to which MATLAB can draw; it does not include the title bar, menu bar, tool bars, and outer edges. To place the full window, use the OuterPosition property.

Renderer

painters | zbuffer | OpenGL

Rendering method used for screen and printing. Selects the method used to render MATLAB graphics. is the default. The choices are:

• painters — The original rendering method used by MATLAB is faster when the figure contains only simple or small graphics objects.

  If you set Renderer to painters on a Windows system, set Colormap no longer than 256 rows.

• zbuffer — MATLAB draws graphics objects faster and more accurately because it colors objects on a per-pixel basis and MATLAB renders only those pixels that are visible in the scene (thus eliminating front-to-back sorting errors). Note that this method can consume a lot of system memory if MATLAB is displaying a complex scene.

• OpenGL — OpenGL^® is a renderer that is available on many computer systems. This renderer is generally faster thanpainters or zbuffer and in some cases enables MATLAB to access graphics hardware that is available on some systems.

Hardware vs. Software OpenGL Implementations

There are two kinds of OpenGL implementations — hardware and software.

The hardware implementation uses special graphics hardware to increase performance and is therefore significantly faster than the software version. Many computers have this special hardware available as an option or might come with this hardware right out of the box.

Software implementations of OpenGL are much like the ZBuffer renderer that is available on MATLAB Version 5.0 and later; however, OpenGL generally provides superior performance to ZBuffer.

OpenGL Availability

OpenGL is available on all computers that run MATLAB. MATLAB automatically finds hardware-accelerated versions of OpenGL if such versions are available. If the hardware-accelerated version is not available, then MATLAB uses the software version (except on Macintosh systems, which do not support software OpenGL).

The following software versions are available:

• On UNIX^® systems, MATLAB uses the software version 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.

Selecting Hardware-Accelerated or Software OpenGL

MATLAB enables you to switch between hardware-accelerated and software OpenGL. However, Windows and UNIX systems behave differently:

• On Windows systems, you can toggle between software and hardware versions any time during the MATLAB session.

• On UNIX systems, you must set the OpenGL version before MATLAB initializes OpenGL. Therefore, you cannot issue theopengl info command or create graphs before you call opengl software. To reenable hardware accelerated OpenGL, you must restart MATLAB.

• On Macintosh systems, software OpenGL is not available.

If you do not want to use hardware OpenGL, but do want to use object transparency, you can issue the following command.

opengl software 

This command forces MATLAB to use software OpenGL. Software OpenGL is useful if your hardware-accelerated version of OpenGL does not function correctly and you want to use image, patch, or surface transparency, which requires the OpenGL renderer. To reenable hardware OpenGL, use the command:

opengl hardware 

on Windows systems or restart MATLAB on UNIX systems.

By default, MATLAB uses hardware-accelerated OpenGL.

See the opengl reference page for additional information

Determining the 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 (Software = true) or hardware-accelerated (Software = false) OpenGL.

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.

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

OpenGL vs. Other MATLAB Renderers

There are some differences between drawings created with OpenGL and those created with other renderers. The OpenGL specific differences include:

• OpenGL does not do colormap interpolation. If you create a surface or patch using indexed color and interpolated face or edge coloring, OpenGL interpolates the colors through the RGB color cube instead of through the colormap.

• OpenGL does not support the phong value for the FaceLighting and EdgeLighting properties of surfaces and patches.

• OpenGL does not support logarithmic-scale axes.

• OpenGL and Zbuffer renderers display objects sorted in front to back order, as seen on the monitor, and lines always draw in front of faces when at the same location on the plane of the monitor. Painters sorts by child order (order specified).

XServer Connection Lost

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

You can also try using software OpenGL and upgrade the OpenGL driver on a Linux system.

Try these workarounds:

1. Upgrade you XServer to the latest version

2. Upgrade your OpenGL driver to the latest version

3. Switch to software OpenGL by entering this command:

   opengl software

RendererMode

{auto} | manual

Automatic or user selection of renderer. Specifies whether MATLAB should choose the Renderer based on the contents of the figure window, or whether the Renderer should remain unchanged.

When the RendererMode property is auto, MATLAB selects the rendering method for printing as well as for screen display based on the size and complexity of the graphics objects in the figure.

For printing, MATLAB switches to zbuffer at a greater scene complexity than for screen rendering because printing from a z-buffered figure can be considerably slower than one using the painters rendering method, and can result in large PostScript^® files. However, the output does always match what is on the screen. The same holds true for OpenGL: the output is the same as that produced by the zbuffer renderer — a bitmap with a resolution determined by the print command's -roption.

Criteria for Autoselection of the OpenGL Renderer

When the RendererMode property is auto, MATLAB uses the following criteria to determine whether to select the OpenGL renderer:

If the opengl autoselection mode is autoselect, MATLAB selects OpenGL if

• The host computer has OpenGL installed and is in True Color mode (OpenGL does not fully support 8-bit color mode).

• The figure contains no logarithmic axes (OpenGL does not support logarithmic axes).

• MATLAB would select zbuffer based on figure contents.

• Patch objects' faces have no more than three vertices (some OpenGL implementations of patch tessellation are unstable).

• The figure contains less than 10 uicontrols (OpenGL clipping around uicontrols is slow).

• No line objects use markers (drawing markers is slow).

• You do not specify Phong lighting (OpenGL does not support Phong lighting; if you specify Phong lighting, MATLAB uses the ZBuffer renderer).

  Or

• Figure objects use transparency (OpenGL is the only MATLAB renderer that supports transparency).

When the RendererMode property is manual, MATLAB does not change the Renderer, regardless of changes to the figure contents.

Resize

{on} | off

Window resize mode. Determines if you can resize the figure window with the mouse. on means you can resize the window,off means you cannot. When Resize is off, the figure window does not display any resizing controls (such as boxes at the corners), to indicate that it cannot be resized.

ResizeFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Window resize callback function. Executes whenever you resize the figure window and when the figure is created. You can query the figure's Position property to determine the new size and position of the figure. During execution of the callback routine, the handle to the figure being resized is accessible only through the root CallbackObject property, which you can query using gcbo.

You can use ResizeFcn to maintain a GUI layout that is not directly supported by the MATLAB Position/Units paradigm.

For example, consider a GUI layout that maintains an object at a constant height in pixels and attached to the top of the figure, but always matches the width of the figure. The following ResizeFcn accomplishes this; it keeps the uicontrol whose Tag is'StatusBar' 20 pixels high, as wide as the figure, and attached to the top of the figure. Note the use of the Tag property to retrieve the uicontrol handle, and the gcbo function to retrieve the figure handle. Also note the defensive programming regarding figure Units, which the callback requires to be in pixels in order to work correctly, but which the callback also restores to their previous value afterwards.

u = findobj('Tag','StatusBar');
fig = gcbo;
old_units = get(fig,'Units');
set(fig,'Units','pixels');
figpos = get(fig,'Position');
upos = [0, figpos(4) - 20, figpos(3), 20];
set(u,'Position',upos);
set(fig,'Units',old_units);

You can change the figure Position from within the ResizeFcn callback; however, the ResizeFcn is not called again as a result.

Note that the print command can cause the ResizeFcn to be called if the PaperPositionMode property is manual and you have defined a ResizeFcn function. If you do not want ResizeFcn called by print, set the PaperPositionMode to auto.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Selected

on | off

Is object selected? This property indicates whether the figure is selected. You can, for example, define the ButtonDownFcn to set this property, allowing users to select the object with the mouse.

SelectionHighlight

{on} | off

Figures do not indicate selection.

SelectionType

{normal} | extend | alt | open

Mouse selection type. 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, etc.).

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

Selection Type	Microsoft Windows	X-Windows
Normal	Click left mouse button.	Click left mouse button.
Extend	Shift - click left mouse button or click both left and right mouse buttons.	Shift-click left mouse button or click middle mouse button.
Alternate	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.

• Note:   For uicontrols whose Enable property is on, a single left-click, Ctrl-left click, or Shift-left click sets the figureSelectionType property to normal. For a list box uicontrol whose Enable property is on, the second click of a double-click sets the figure SelectionType property to open. All clicks on uicontrols whose Enable property is inactive or offand all right-clicks on uicontrols whose Enable property is on set the figure SelectionType property as specified in the preceding table.

Tag

string

User-specified object label. Provides a means to identify graphics objects with a user-specified label. The default is an empty string.

Use the Tag property and the findobj function to manipulate specific objects within a plotting hierarchy.

For example, suppose you want to direct all graphics output from a file to a particular figure, regardless of user actions that might have changed the current figure. To do this, identify the figure with a Tag.

figure('Tag','Plotting Figure')

Then make that figure the current figure before drawing by searching for the Tag with findobj.

figure(findobj('Tag','Plotting Figure'))

Toolbar

none | {auto} | figure

Control display of figure toolbar. Control whether MATLAB displays the default figure toolbar on figures. The possible values are:

• none — Do not display the figure toolbar.

• auto — Display the figure toolbar, but remove it if a uicontrol is added to the figure.

• figure — Display the figure toolbar.

Note that this property affects only the figure toolbar; it does not affect other toolbars (for example, the Camera Toolbar or Plot Edit Toolbar). Selecting Figure Toolbar from the figure View menu sets this property to figure.

Changing the WindowStyle of a window to 'modal' hides both its toolbar and menu bar, if they exist. Changing WindowStylefrom 'modal' to 'normal' or 'docked' displays any toolbar or menu bar a figure has.

Type

string (read-only)

Object class. String that identifies the class of the graphics object. Use this property to find all objects of a given type within a plotting hierarchy. For figures, Type is always 'figure'.

UIContextMenu

handle of uicontextmenu object

Associate a context menu with the figure. Assign the handle of a uicontextmenu object created in the figure to this property.Use the uicontextmenu function to create the context menu. MATLAB displays the context menu whenever you right-click over the figure.

Units

inches | centimeters | normalized | points | {pixels} | characters

Units of measurement. Specifies the units MATLAB uses to interpret size and location data. All units are measured from the lower-left corner of the window.

• normalized — Units map the lower-left corner of the figure window to (0,0) and the upper-right corner to (1.0,1.0).

• inches, centimeters, and points — Absolute units. 1 point = ¹/72 inch.

• pixels — Size depends on screen resolution.

• characters — Based on the size of characters in the default system font. The width of one characters unit is the width of the letter x, and the height of one characters unit is the distance between the baselines of two lines of text.

This property affects the CurrentPoint and Position properties. If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is the default value.

When specifying the units as property/value pairs during object creation, you must set the Units property before specifying the properties that you want to use these units.

UserData

matrix

User-specified data. Data you want to associate with the figure object. The default value is an empty array. MATLAB does not use this data, but you can access it using the set and get commands.

Visible

{on} | off

Object visibility. The Visible property determines whether an object is displayed on the screen. If the Visible property of a figure is off, the entire figure window is invisible.

A Note About Using the Window Button Properties

Your window button callback functions might need to update the display by calling drawnow or pause, which causes MATLAB to process all events in the queue. Processing the event queue can cause your window button callback functions to be reentered. For example, a drawnow in the WindowButtonDownFcn might result in the WindowButtonDownFcn being called again before the first call has finished. You should design your code to handle reentrancy and you should not depend on global variables that might change state during reentrance.

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

WindowButtonDownFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Button press callback function. Executes whenever you press a mouse button while the pointer is in the figure window. See theWindowButtonMotionFcn property for an example.

• Note:   When using a two- 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 mouse is clicked without first moving it. In this circumstance, for the WindowButtonDownFcn to work, the user needs to do one of the following: Move the mouse after the figure is created, 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.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

WindowButtonMotionFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Mouse motion callback function. Executes whenever you move the pointer within the figure window. Define theWindowButtonMotionFcn as a function handle. The function must define at least two input arguments (handle of figure associated with key release and an event structure).

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Example Using All Window Button Properties

Click to view in editor — This example enables you to use mouse motion to draw lines. It uses all three window button functions.

Click to run example — 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.

• Note:   On some computer systems, the WindowButtonMotionFcn is executed when a figure is created even though there has been no mouse motion within the figure.

WindowButtonUpFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Button release callback function. Executes whenever you release a mouse button. Define the WindowButtonUpFcn as a function handle. The function must define at least two input arguments (handle of figure associated with key release and an event structure).

The button up event is associated with the figure window in which the preceding button down event occurred. Therefore, the pointer need not be in the figure window when you release the button to generate the button up event.

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

See Function Handle Callbacks for information on how to use function handles to define the callback function.

WindowKeyPressFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Key press callback function for the figure window. Executes whenever a key press occurs. This is a callback function invoked by a key press that occurs while either the figure window or any of its children has focus. Define the WindowKeyPressFcn as a function handle. The function must define at least two input arguments (handle of figure associated with key release and an event structure).

For information on the syntax of callback functions, see Function Handle Callbacks.

When no callback is specified for this property (which is the default state), MATLAB passes any key presses to the Command Window. However, when you define a callback for this property, the figure retains focus with each key press and executes the specified callback with each key press.

WindowKeyPressFcn Event Structure

When you specify the callback as a function handle, MATLAB passes to it a structure to containing the following fields.

Field	Contents
Character	The character displayed as a result of the releasing the key(s), which can be empty or unprintable
Key	The key being released, identified by the lowercase label on key or a descriptive string
Modifier	A cell array containing the names of one or more modifier keys being released (i.e., control,alt, shift). On Macintosh computers, it contains 'command' when releasing the commandmodifier key

For more information and examples of use, see the KeyPressFcn property description.

WindowKeyReleaseFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Key release callback function for the figure window. Executes whenever a key release occurs. This is a callback function invoked by a key release that occurs while the figure window or any of its children has focus. Define the WindowKeyReleaseFcnas a function handle. The function must define at least two input arguments (handle of the figure associated with key release and an event structure).

See Function Handle Callbacks for information on how to use function handles to define the callback function.

WindowKeyReleaseFcn Event Structure

When you specify the callback as a function handle, MATLAB passes to it a structure to containing the following fields.

Field	Contents
Character	The character displayed as a result of the releasing the key(s), which can be empty or unprintable
Key	The key being released, identified by the lowercase label on key or a descriptive string
Modifier	A cell array containing the names of one or more modifier keys being released (i.e., control,alt, shift). On Macintosh computers, it contains 'command' when releasing the commandmodifier key

For more information and examples of use, see the KeyReleaseFcn property description.

WindowScrollWheelFcn

function handle | cell array containing function handle and additional arguments | string (not recommended)

Respond to mouse scroll wheel. Executes when the mouse wheel is scrolled while the figure has focus. MATLAB executes the callback with each single mouse wheel click.

Note that it is possible for another object to capture the event from MATLAB. For example, if the figure contains Java^® or ActiveX^® control objects that are listening for mouse scroll wheel events, then these objects can consume the events and prevent the WindowScrollWheelFcn from executing.

There is no default callback defined for this property.

WindowScrollWheelFcn Event Structure

When the callback is a function handle, MATLAB passes a structure to the callback function that contains the following fields.

Field	Contents
VerticalScrollCount	A positive or negative integer that indicates the number of 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, VerticalScrollAmount returns a value of 1.

Effects on Other Properties

• CurrentObject property — Mouse scrolling does not update this figure property.

• CurrentPoint property — If there is no callback defined for the WindowScrollWheelFcn property, then MATLAB does not update the CurrentPoint property as the scroll wheel is turned. However, if there is a callback defined for theWindowScrollWheelFcn 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.

• HitTest property — The WindowScrollWheelFcn callback executes regardless of the setting of the figure HitTestproperty.

• SelectionType property — The WindowScrollWheelFcn callback has no effect on this 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 is reset. 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 and/or the user spins the scroll wheel very fast, then the returned value can have an absolute value greater than one.

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

Example

Click to view in editor — This example creates a graph of a function and enables you to use the mouse scroll wheel to change the range over which a mathematical function is evaluated and update the graph to reflect the new limits as you turn the scroll wheel.

Click to run example — Mouse over the figure and scroll your mouse wheel.

Related Information

See Function Handle Callbacks for information on how to use function handles to define the callback function.

WindowStyle

{normal} | modal | docked

Normal, modal, or dockable window behavior. When WindowStyle is modal:

• The figure window traps all keyboard and mouse events over all MATLAB windows as long as they are visible.

• Windows belonging to applications other than MATLAB are unaffected.

• Modal figures remain stacked above all normal figures and the MATLAB Command Window.

• 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 WindowStyle normal , or is deleted. At that time, focus reverts to the window that last had focus.

Use modal figures to create dialog boxes that force the user to respond without being able to interact with other windows. Typing Ctrl+C while the figure has focus causes all figures with WindowStyle modal to revert to WindowStyle normal, allowing you to type at the command line.

Invisible Modal Figures

Figures with WindowStyle modal and Visible off do not behave modally until they are made visible, so it is acceptable to hide a modal window for later reuse instead of destroying it.

Stacking Order of Modal Figures

Creating a figure with WindowStyle modal stacks it 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 is displayed (for example, plots created by a modal GUI) stack on top of it and are accessible; they can be modal as well.

Changing Modes

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

Window Decorations on Modal Figures

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 WindowStyle to modal on a figure with uimenu children. The uimenu objects exist and their handles are retained by the figure. If you reset the figure's WindowStyle to normal, the uimenus are displayed.

Docked WindowStyle

When WindowStyle is docked, the figure is docked in the desktop or a document window. When you issue the following command:

set(figure_handle,'WindowStyle','docked')

MATLAB docks the figure identified by figure_handle and sets the DockControls property to on, if it was off.

Note that if WindowStyle is docked, you cannot set the DockControls property to off.

The value of the WindowStyle property is not changed by calling reset on a figure.

WVisual

identifier string (Windows only)

Specify pixel format for figure. MATLAB automatically selects a pixel format for figures based on your current display settings, the graphics hardware available on your system, and the graphical content of the figure.

Usually, MATLAB chooses the best pixel format to use in any given situation. However, in cases where graphics objects are not rendered correctly, you might be able to select a different pixel format and improve results. See "Understanding the WVisual String" for more information.

Querying Available Pixel Formats on Window Systems

You can determine what pixel formats are available on your system for use with MATLAB using the following statement:

set(gcf,'WVisual')

MATLAB returns a list of the currently available pixel formats for the current figure. For example, the following are the first three entries from a typical list:

01 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, OpenGL, GDI, Window)

02 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, OpenGL, Double Buffered, Window)

03 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, OpenGL, Double Buffered, Window)

Use the number at the beginning of the string to specify which pixel format to use. For example:

set(gcf,'WVisual','02')

specifies the second pixel format in the list above. Note that pixel formats might differ on your system.

Understanding the WVisual String

The string returned by querying the WVisual property provides information on the pixel format. For example:

• RGB 16 bits(05 06 05 00) — Indicates true color with 16-bit resolution (5 bits for red, 6 bits for green, 5 bits for blue, and 0 for alpha (transparency). MATLAB requires true color.

• zdepth 24 — Indicates 24-bit resolution for sorting object's front to back position on the screen. Selecting pixel formats with higher (24 or 32) zdepth might solve sorting problems.

• Hardware Accelerated — Some graphics functions might be performed by hardware for increased speed. If there are incompatibilities between your particular graphic hardware and MATLAB, select a pixel format in which the term Genericappears instead of Hardware Accelerated.

• Opengl — Supports OpenGL. See the preceding "Pixel Formats and OpenGL" for more information.

• GDI — Supports for Windows 2-D graphics interface.

• Double Buffered — Support for double buffering with the OpenGL renderer. Note that the figure DoubleBuffer property applies only to the painters renderer.

• Bitmap — Support for rendering into a bitmap (as opposed to drawing in the window).

• Window — Support for rendering into a window.

Pixel Formats and OpenGL

If you are experiencing problems using hardware OpenGL on your system, you can try using generic OpenGL, which is implemented in software. To do this, first instruct MATLAB to use the software version of OpenGL with the following statement:

opengl software

Then allow MATLAB to select best pixel format to use.

See the Renderer property for more information on how MATLAB uses OpenGL.

WVisualMode

{auto} | manual (Windows only)

Auto or manual selection of pixel format. WVisualMode can take on two values — auto (the default) and manual. In automode, MATLAB selects the best pixel format to use based on your computer system and the graphical content of the figure. Inmanual mode, MATLAB does not change the visual from the one currently in use. Setting the WVisual property sets this property to manual.

XDisplay

display identifier (UNIX only)

Contains the display used for MATLAB. You can query this property to determine the name of the display that MATLAB is using. For example, if MATLAB is running on a system called mycomputer, querying XDisplay returns a string of the following form:

get(gcf,'XDisplay')
ans
mycomputer:0.0

Setting XDisplay on Motif

If your computer uses Motif-based figures, you can specify the display MATLAB uses for a figure by setting the value of the figure's XDisplay property. For example, to display the current figure on a system called fred, use the command:

set(gcf,'XDisplay','fred:0.0')

XVisual

visual identifier (UNIX only)

Select visual used by MATLAB. You can select the visual used by MATLAB by setting the XVisual property to the desired visual ID. This can be useful if you want to test your application on an 8-bit or grayscale visual. To see what visuals are available on your system, use the UNIX xdpyinfo command. From MATLAB, type:

!xdpyinfo

The information returned contains a line specifying the visual ID. For example:

visual id:    0x23

To use this visual with the current figure, set the XVisual property to the ID.

set(gcf,'XVisual','0x23')

To see which of the available visuals MATLAB can use, call set on the XVisual property:

set(gcf,'XVisual')

The following typical output shows the visual being used (in curly braces) and other possible visuals. Note that MATLAB requires a TrueColor visual.

{ 0x23 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) }
  0x24 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x25 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x26 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x27 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x28 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x29 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
  0x2a (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)

You can also use the glxinfo UNIX command to see what visuals are available for use with the OpenGL renderer. From MATLAB, type:

!glxinfo

After providing information about the implementation of OpenGL on your system, glxinfo returns a table of visuals. The partial listing below shows typical output:

visual  x  bf lv rg d st colorbuffer ax dp st accumbuffer  ms  cav
 id dep cl sp sz l  ci b ro  r  g  b  a bf th cl  r  g  b  a ns b eat
---------------------------------------------------------------
-
0x23 24 tc  0 24  0 r  y  .  8  8  8  8  0  0  0  0  0  0  0  0 0 None
0x24 24 tc  0 24  0 r  .  .  8  8  8  8  0  0  0  0  0  0  0  0 0 None
0x25 24 tc  0 24  0 r  y  .  8  8  8  8  0 24  8  0  0  0  0  0 0 None
0x26 24 tc  0 24  0 r  .  .  8  8  8  8  0 24  8  0  0  0  0  0 0 None
0x27 24 tc  0 24  0 r  y  .  8  8  8  8  0  0  0 16 16 16  0  0 0 Slow

The third column is the class of visual. tc means a true color visual. Note that some visuals might be labeled Slow under the caveat column. Such visuals should be avoided.

To determine which visual MATLAB will use by default with the OpenGL renderer, use the MATLAB opengl info command. The returned entry for the visual might look like the following:

Visual = 0x23 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)

Experimenting with a different TrueColor visual might improve certain rendering problems.

XVisualMode

{auto} | manual (UNIX only)

Auto or manual selection of visual. XVisualMode can take on two values — auto (the default) and manual. In auto mode, MATLAB selects the best visual to use based on the number of colors, availability of the OpenGL extension, etc. In manualmode, MATLAB does not change the visual from the one currently in use. Setting the XVisual property sets this property tomanual.