figure

Purpose

Open new graphics window by creating figure object.

Synopsis

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

Description

Figure objects are children of the root object and parents of axes, uimenus, and uicontrols. They are the individual windows on the screen in which MATLAB displays graphical output. When you create a figure, you create a new window whose characteristics are controlled by a number of factors including the windowing system and the figure properties.

figure, by itself, opens a new figure (graph window).

h = figure opens a new figure and returns the next available figure number, also known as the figure handle. Figure handles are integers numbered sequentially starting at 1 and are displayed in the border at the top of the window.

figure(h) makes the figure with handle h the current figure for subsequent plotting commands.

h = figure('PropertyName',PropertyValue,...) accepts property name/property value pairs as input arguments. These properties are described under "Object Properties." You can also set and query property values after creating the object using the set and get functions.

Use gcf (get current figure) to obtain the handle of the current figure. The current figure is the window in which any drawing command is directed.

Specify default figure properties at the figure's parent level, that is, at the root object. To do so, call the set function, supplying as arguments the handle 0 (for the root), a default name string, and the desired default value. Construct the default name string by prepending the string 'DefaultFigure' to the desired figure property name. For example

set(0,'DefaultFigureColor','blue')
sets the default figure background color to blue.

Object Properties

This section lists property names along with the type of values each accepts.

BackingStore
Store copy of figure window for fast refresh.
on (Default.) Store copy of figure. When obscured parts of the figure are uncovered, the system restores them without rerendering. This causes faster screen redraws, but uses more memory.
off Redraw previously obscured portions of the figure.
ButtonDownFcn
Callback string, object selection.
Any legal MATLAB expression, including the name of an M-file or function. When you click the mouse button with the cursor over the figure, the string is passed to the eval function to execute the specified function. Initially the empty matrix.
Children
Children of figure.
A read-only vector containing the handles of all objects displayed within the figure. The children objects of figures can be axes, uicontrols, and uimenus.
Clipping
Data clipping.
on (Default.) No effect for figure objects.
off No effect for figure objects.
Color
Figure background color.
A three-element RGB vector or one of MATLAB's predefined names, specifying the background color for the figure. The default Color is black. See the ColorSpec reference page for more information on specifying color.
ColorMap
Figure colormap.
An m-by-3 matrix of RGB values. Graphics commands index the colors in the colormap 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. The maximum colormap length is determined by your system (usually slightly less than 256 colors), but the colormap must be three columns wide. The default figure colormap contains 64 predefined colors.
You can replace the default colormap, hsv, with your own or with one of MATLAB's predefined colormaps. To define a colormap, specify the intensity of the red component in the first column, the green component in the second column and the blue component in the third column. Color intensities are floating-point numbers in the range [0 1]. A value of 0 indicates no intensity and a value of 1 indicates full intensity. An RGB triplet of [0 0 0] specifies black and [1 1 1] specifies white.
Colormaps affect the rendering of surface, image, and patch objects, but generally do not affect other objects. See the colormap and ColorSpec reference pages for more information.
CurrentAxes
Figure's current axes.
The handle of the figure's current axes. This is the handle returned by gca when this figure is the current figure. If axes children exist, there is always a current axes for the figure. If there are no axes in a figure,
get(gcf,'CurrentAxes')
creates one and returns its handle.
CurrentCharacter
Last key pressed.
The last key pressed in the current figure window.
CurrentMenu
Figure's current menu.
The handle of the figure's current (most recently selected) menu. If you use a single menu handler for multiple menu items, query this property to determine which menu called the handler.
CurrentObject
Figure's current object.
The handle of the figure's current object, the object located at the CurrentPoint (see below). This object is the front-most object in the stacking order. Use this property to determine which object you have selected.
CurrentPoint
Location of last mouse press or release in the figure.
A two-element vector [x y] containing the x- and y-coordinates of the location in the figure window where you last pressed or released the mouse button. This is measured from the lower-left corner of the figure window in units specified by the Units property. Initially [0 0].
FixedColors
Fixed colors allotted for figure.
An n-by-3 matrix of RGB values that define the fixed colors for the figure. Fixed colors take up slots in the system color table, reducing the number of slots available for colormaps. Initial fixed colors are white and black.
Interruptible
Callback interruptibility.
yes Any of the figure's callbacks are interruptible by other callbacks.
no (Default.) The callbacks are not interruptible.
See the MATLAB Release Notes for more details on the Interruptible property.
InvertHardCopy
Change hardcopy from white on black to black on white.
on (Default.) For printed output, change black figure background to white, and lines, text, and so on to black. Surface and patch colors are not affected. If the output device does not support color, lines and text in colors other than black or white are changed to either black or white (whichever provides the most contrast with the paper background).
off Color of printed output exactly matches screen display.
KeyPressFcn
Callback string, key press.
Any legal MATLAB expression, including the name of an M-file or function. When you press a keyboard key while the pointer is within the figure, the string is passed to the eval function to execute the specified function. Use the CurrentCharacter property to determine which key was pressed. Use the PointerWindow property of the root object to determine in which figure the key was pressed. (Note that pressing a keyboard key over a figure does not make that figure active.) Initially the empty matrix.
MenuBar
Display menu bar.
figure (Default.) Display default MATLAB menus for figure. On some systems, these menus appear at the top of the figure window; on others, they appear at the top of the screen.
none Do not display default MATLAB menus. Some systems still display system-specific menus.
MinColorMap
Minimum number of color table entries to use.
The minimum number of color table slots that MATLAB will make available at any time.
MATLAB keeps track of the indices in use by other applications, and avoids using them. With no color-intensive applications running, more than 200 slots can be available. This allows several 64-color MATLAB colormaps (the default size) and many other fixed colors to coexist with the rest of the applications on the screen. Figure windows display correctly even when not active.
If there are not enough free slots to install a desired figure colormap without causing false colors in other applications, the figure changes as many slots as needed to reach MinColorMap number of slots. If the resulting number of slots is smaller than the length of the colormap, individual colormap entries are grouped together piecewise with their neighbors to create as many groups as there are available slots in the color table. In this case, all members of a given group display in the color of the group's center member.
This scheme does not interpolate lost colors, but merely subsamples the desired colormap to fit in the available number of color table slots. This works well for smoothly varying colormaps and poorly for colormaps with irregularly located colors. For images, whose colormaps often consist of irregularly located colors, it is best to set MinColormap to the number of distinct colors in the image to avoid displaying it in false colors, even when the figure is active.
If there are several figure windows open with similar or with small colormaps, they display simultaneously in their correct colors. If the colormaps are very large, and/or very different, it is likely that the inactive windows display in false color. Clicking on an inactive window to make it active restores the correct colors.
Name
Figure window title.
A string specifying a name for the window that contains the figure. By default, this property is the empty string and figure titles are Figure No. 1, Figure No. 2, and so on. If you set Name to string, the title becomes Figure No. n: string.
NextPlot
Figure handling for subsequent plots.
new Create a new figure before drawing.
add (Default.) Add new objects to the current figure.
replace Reset all figure properties except Position and delete all figure children before drawing.
This property is used by the built-in high-level graphing functions plot, plot3, fill, fill3, and the M-file graphing functions mesh, surf, bar, and so on. The M-file newplot is a preamble for handling the NextPlot property. M-file graphing functions like mesh, surf, and bar call newplot to control this property before drawing their respective graphs. When creating M-files that implement graphing commands, use newplot at the beginning of the file. See the M-file pcolor for an example. Also see the NextPlot property of axes objects.
NumberTitle
Prepend figure window number to title.
on (Default.) Prepend the string Figure No. N to the figure window title.
off Do not add figure number to the figure window title.
PaperOrientation
Paper orientation.
portrait (Default.) Portrait orientation - longest dimension of page is vertical
land Landscape orientation - longest dimension of page is horizontal.
PaperPosition
Location of figure on printed page.
A four-element vector, [left,bottom,width,height], where left and bottom are the distance from the lower-left corner of the page to the lower-left corner of the printed figure window. width and height are the dimensions of the printed figure window. All measurements are in units specified by the PaperUnits property. Initial setting depends on PaperSize and PaperOrientation.
PaperSize
Paper size.
A two-element vector, [width,height], containing the current PaperSize measured in PaperUnits. The default PaperSize is [8.5 11].
PaperType
Type of printed page.
usletter (Default.) Standard US letter.
uslegal Standard US legal.
a4letter European A4.
When the PaperUnits property is set to normal, MATLAB uses PaperType to scale printed figures so they fit on the page correctly.
PaperUnits
Unit of measurement for hardcopy.
normal Normalized coordinates, where the lower-left corner of the page maps to (0,0) and the upper-right corner to (1.0,1.0).
inches (Default.) Inches.
cent Centimeters.
points Points. Each point is equivalent to 1/72 of an inch.
This property specifies the unit for PaperPosition and PaperSize measurements. If you change the value of PaperUnits, it is good practice to return it 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 of the figure's parent object.
A read-only property that contains the handle of the figure's parent object. The parent of a figure object is always the root, so this property is always 0.
Pointer
Symbol to indicate cursor position in the figure window.
arrow (Default.) Arrow.
crossh Crosshair.
watch Watch.
cross Double-line cross.
topl Arrow pointing to upper-left corner of figure.
topr Arrow pointing to upper-right corner of figure.
botl Arrow pointing to lower-left corner of figure.
botr Arrow pointing to lower-right corner of figure.
circle Circle.
fleur Four-headed arrow (compass).
Position
Size and position of figure.
A four-element vector, [left,bottom,width,height], where left and bottom are the distance from the lower-left corner of the screen to the lower-left corner of the figure window. width and height are the dimensions of the figure window. All measurements are in units specified by the Units property.
Resize
Window resize mode.
on (Default.) Users can resize the figure window using the mouse.
off Users cannot resize the figure window.
SelectionType
Mouse selection type.
A read-only string providing information about the last mouse button press, indicating a type of selection. All selection types exist on all platforms, although the action required to implement the selections may differ. This list describes the X-Windows based selection system.
normal (Default.) Click the mouse button (press and release) while the pointer is over the object to select.
For a two-button mouse, click and release the left mouse button.
extended Hold down the Shift key and make a normal selection. Add selections by keeping the shift key depressed.
For a two-button mouse, make extended selections by clicking both buttons simultaneously. For a three-button mouse, use mouse button 2.
alt Hold down the Control key and make a normal selection. For a two- or three-button mouse, press the right-most button.
open Double-click the mouse while the pointer is over the object to select. For a two- or three-button mouse, use the same button for both clicks.
ShareColors
Share color table slots.
yes (Default.) MATLAB minimizes color table use by reusing existing color table slots whenever possible. This allows the maximum number of windows to render their contents accurately.
no Do not share color table slots with other windows.
Type
Type of graphics object.
A read-only string; always 'figure' for a figure object.
Units
Unit of measurement for screen display.
pixels (Default.) Screen pixels.
normalized Normalized coordinates, where the lower-left corner of the figure window maps to (0,0) and the upper-right corner to (1.0,1.0).
inches Inches.
cent Centimeters.
points Points. Each point is equivalent to 1/72 of an inch.
All units are measured from the lower-left corner of the window. 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 set to the default value.
UserData
User-specified data.
Any matrix you want to associate with the figure object. The object does not use this data, but you can retrieve it using the get command.
Visible
Figure visibility.
on (Default.) Figure window is visible on the screen.
off Figure window is not visible on the screen.
WindowButtonDownFcn
Callback string, mouse button press.
Any legal MATLAB expression, including the name of an M-file or function. When you press a mouse button while the pointer is within the figure (but not over a uicontrol), the string is passed to the eval function to execute the specified function. Initially the empty matrix.
See the MATLAB Release Notes for more details on the WindowButtonDownFcn property.
WindowButtonMotionFcn
Callback string, pointer motion.
Any legal MATLAB expression, including the name of an M-file or function. When you move the pointer within the figure, the string is passed to the eval function to execute the specified function. Initially the empty matrix.
See the MATLAB Release Notes for more details on the WindowButtonMotionFcn property.
WindowButtonUpFcn
Callback string, mouse button release.
Any legal MATLAB expression, including the name of an M-file or function. When you release a mouse button while the pointer is within the figure, the string is passed to the eval function to execute the specified function. If you move the pointer between figures, the callback executed is that associated with the figure where the button was pressed. Initially the empty matrix.
See the MATLAB Release Notes for more details on the WindowButtonUpFcn property.

See Also

axes, clf, close, gcf, subplot

(c) Copyright 1994 by The MathWorks, Inc.