figure (MATLAB Function Reference)

Create a figure graphics object

Syntax

figure
figure('PropertyName',PropertyValue,...)
figure(h)
h = figure(...)

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

scrsz = get(0,'ScreenSize');
figure('Position',[1 scrsz(4)/2 scrsz(3)/2 scrsz(4)/2])

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.

set(0,'DefaultFigureProperty',PropertyValue...)

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

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