figure (MATLAB Function Reference)

Create a Figure graphics object

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 "Figure 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 the Renderer
`BackingStore`	Enable off screen pixel buffering	Values: `on`, `off` Default: `on`
`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
`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 (read only)
`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 (read only)	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: empty string
`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` (read only)	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`

[ Previous | Help Desk | Next ]