MATLAB Function Reference    
figure

Create a figure graphics object

Syntax

Description

figure creates figure graphics objects. figure objects are the individual windows on the screen in which MATLAB displays graphical output.

figure creates a new figure object using default property values.

figure('PropertyName',PropertyValue,...) creates a new figure object using the values of the properties specified. MATLAB uses default values for any properties that you do not explicitly define as arguments.

figure(h) does one of two things, depending on whether or not a figure with handle h exists. If h is the handle to an existing figure, figure(h) makes the figure identified by h the current figure, makes it visible, and raises it above all other figures on the screen. The current figure is the target for graphics output. If h is not the handle to an existing figure, but is an integer, figure(h) creates a figure, and assigns it the handle h. figure(h) where h is not the handle to a figure, and is not an integer, is an error.

h = figure(...) returns the handle to the figure object.

Remarks

To create a figure object, MATLAB creates a new window whose characteristics are controlled by default figure properties (both factory installed and user defined) and properties specified as arguments. See the properties section for a description of these properties.

You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types).

Use set to modify the properties of an existing figure or get to query the current values of figure properties.

The gcf command returns the handle to the current figure and is useful as an argument to the set and get commands.

Example

To create a figure window that is one quarter the size of your screen and is positioned in the upper-left corner, use the root object's ScreenSize property to determine the size. ScreenSize is a four-element vector: [left, bottom, width, height]:

See Also

axes, uicontrol, uimenu, close, clf, gcf, rootobject

Object Hierarchy

Setting Default Properties

You can set default figure properties only on the root level.

Where Property is the name of the figure property and PropertyValue is the value you are specifying. Use set and get to access figure properties.

Property List

The following table lists all figure properties and provides a brief description of each. The property name links bring you an expanded description of the properties.

Property Name
Property Description
Property Value
Positioning the Figure
Position
Location and size of figure
Value: a 4-element vector [left, bottom, width, height]
Default: depends on display
Units
Units used to interpret the Position property
Values: inches, centimeters, normalized, points, pixels, characters
Default: pixels
Specifying Style and Appearance
Color
Color of the figure background
Values: ColorSpec
Default: depends on color scheme (see colordef)
MenuBar
Toggle the figure menu bar on and off
Values: none, figure
Default: figure
Name
Figure window title
Values: string
Default: '' (empty string)
NumberTitle
Display "Figure No. n", where n is the figure number
Values: on, off
Default: on
Resize
Specify whether the figure window can be resized using the mouse
Values: on, off
Default: on
SelectionHighlight
Highlight figure when selected (Selected property set to on)
Values: on, off
Default: on
Visible
Make the figure visible or invisible
Values: on, off
Default: on
WindowStyle
Select normal or modal window
Values: normal, modal Default: normal
Controlling the Colormap
Colormap
The figure colormap
Values: m-by-3 matrix of RGB values
Default: the jet colormap
Dithermap
Colormap used for truecolor data on pseudocolor displays
Values: m-by-3 matrix of RGB values
Default: colormap with full range of colors
DithermapMode
Enable MATLAB-generated dithermap
Values: auto, manual
Default: manual
FixedColors
Colors not obtained from colormap
Values: m-by-3 matrix of RGB values (read only)
MinColormap
Minimum number of system color table entries to use
Values: scalar
Default: 64
ShareColors
Allow MATLAB to share system color table slots
Values on, off
Default: on
Specifying Transparency


Alphamap
The figure alphamap
m-by-1 matrix of alpha values
Specifying the Renderer
BackingStore
Enable off screen pixel buffering
Values: on, off
Default: on
DoubleBuffer
Flash-free rendering for simple animations
Values: on, off
Default: off
Renderer
Rendering method used for screen and printing
Values: painters, zbuffer, OpenGL
Default: automatic selection by MATLAB
General Information About the Figure
Children
Handle of any uicontrol, uimenu, and uicontextmenu objects displayed in the figure
Values: vector of handles
FileName
Used by guide
String
Parent
The root object is the parent of all figures
Value: always 0
Selected
Indicate whether figure is in a "selected" state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read only)
Value: the string 'figure'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
RendererMode
Automatic or user-selected renderer
Values: auto, manual
Default: auto
Information About Current State
CurrentAxes
Handle of the current axes in this figure
Values: axes handle
CurrentCharacter
The last key pressed in this figure
Values: single character
CurrentObject
Handle of the current object in this figure
Values: graphics object handle
CurrentPoint
Location of the last button click in this figure
Values: 2-element vector [x-coord, y-coord]
SelectionType
Mouse selection type
Values: normal, extended, alt, open
Callback Routine Execution
BusyAction
Specify how to handle callback routine interruption
Values: cancel, queue Default: queue
ButtonDownFcn
Define a callback routine that executes when a mouse button is pressed on an unoccupied spot in the figure
Values: string
Default: empty string
CloseRequestFcn
Define a callback routine that executes when you call the close command
Values: string
Default: closereq
CreateFcn
Define a callback routine that executes when a figure is created
Values: string
Default: empty string
DeleteFcn
Define a callback routine that executes when the figure is deleted (via close or delete)
Values: string
Default: empty string
Interruptible
Determine if callback routine can be interrupted
Values: on, off
Default: on (can be interrupted)
KeyPressFcn
Define a callback routine that executes when a key is pressed in the figure window
Values: string
Default: empty string
ResizeFcn
Define a callback routine that executes when the figure is resized
Values: string
Default: empty string
UIContextMenu
Associate a context menu with the figure
Values: handle of a Uicontrextmenu
WindowButtonDownFcn
Define a callback routine that executes when you press the mouse button down in the figure
Values: string
Default: empty string
WindowButtonMotionFcn
Define a callback routine that executes when you move the pointer in the figure
Values: string
Default: empty string
WindowButtonUpFcn
Define a callback routine that executes when you release the mouse button
Values: string
Default: empty string
Controlling Access to Objects
IntegerHandle
Specify integer or noninteger figure handle
Values: on, off
Default: on (integer handle)
HandleVisibility
Determine if figure handle is visible to users or not
Values: on, callback, off Default: on
HitTest
Determine if the figure can become the current object (see the figure CurrentObject property)
Values: on, off
Default: on
NextPlot
Determine how to display additional graphics to this figure
Values: add, replace, replacechildren
Default: add
Defining the Pointer
Pointer
Select the pointer symbol
Values: crosshair, arrow, watch, topl, topr, botl, botr, circle, cross, fleur, left, right, top, bottom, fullcrosshair, ibeam, custom
Default: arrow
PointerShapeCData
Data that defines the pointer
Values: 16-by-16 matrix Default: set Pointer to custom and see
PointerShapeHotSpot
Specify the pointer active spot
Values: 2-element vector [row, column]
Default: [1,1]
Properties That Affect Printing
InvertHardcopy
Change figure colors for printing
Values: on, off
Default: on
PaperOrientation
Horizontal or vertical paper orientation
Values: portrait, landscape Default: portrait
PaperPosition
Control positioning figure on printed page
Values: 4-element vector [left, bottom, width, height]
PaperPositionMode
Enable WYSIWYG printing of figure
Values: auto, manual
Default: manual
PaperSize
Size of the current PaperType specified in PaperUnits
Values: [width, height]
PaperType
Select from standard paper sizes
Values: see property description
Default: usletter
PaperUnits
Units used to specify the PaperSize and PaperPosition
Values: normalized, inches, centimeters, points Default: inches
Controlling the XWindows Display (UNIX only)

XDisplay
Specify display for MATLAB (UNIX only)
Values: display identifier
Default: :0.0
XVisual
Select visual used by MATLAB (UNIX only)
Values: visual ID
XVisualMode
Auto or manual selection of visual (UNIX only)
Values: auto, manual
Default: auto


 figflag Figure Properties