figure

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

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 or function handle Default: empty string
CloseRequestFcn	Define a callback routine that executes when you call the close command	Values: string or function handle Default: closereq
CreateFcn	Define a callback routine that executes when a figure is created	Values: string or function handle Default: empty string
DeleteFcn	Define a callback routine that executes when the figure is deleted (via close or delete)	Values: string or function handle 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 or function handle Default: empty string
ResizeFcn	Define a callback routine that executes when the figure is resized	Values: string or function handle 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 or function handle Default: empty string
WindowButtonMotionFcn	Define a callback routine that executes when you move the pointer in the figure	Values: string or function handle Default: empty string
WindowButtonUpFcn	Define a callback routine that executes when you release the mouse button	Values: string or function handle 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