# 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.