MATLAB Function Reference |
You can set and query graphics object properties in two ways:
set
and get
commands enable you to set and query the values of properties.
To change the default values of properties, see Setting Default Property Values.
Figure Property Descriptions
This section lists property names along with the type of values each accepts. Curly braces { } enclose default values.
Alphamap
m-by-1 matrix of alpha values
Figure alphamap. This property is an m-by-1 array of non-NaN alpha values. MATLAB accesses alpha values by their row number. For example, an index of 1 specifies the first alpha value, an index of 2 specifies the second alpha value, and so on. Alphamaps can be any length. The default alphamap contains 64 values that progress linearly from 0 to 1.
Alphamaps affect the rendering of surface, image, and patch objects, but do not affect other graphics objects.
BackingStore
{on} | off
Offscreen pixel buffer. When BackingStore
is on
, MATLAB stores a copy of the figure window in an offscreen pixel buffer. When obscured parts of the figure window are exposed, MATLAB copies the window contents from this buffer rather than regenerating the objects on the screen. This increases the speed with which the screen is redrawn.
While refreshing the screen quickly is generally desirable, the buffers required do consume system memory. If memory limitations occur, you can set BackingStore
to off
to disable this feature and release the memory used by the buffers. If your computer does not support backing store, setting the BackingStore
property results in a warning message, but has no other effect.
Setting BackingStore
to off
can increase the speed of animations because it eliminates the need to draw into both an off-screen buffer and the figure window.
Note that when the Renderer
is set to opengl
, MATLAB sets BackingStore
to off
.
BeingDeleted
on | {off}
Read Only
This object is being deleted. The BeingDeleted
property provides a mechanism that you can use to determine if objects are in the process of being deleted. MATLAB sets the BeingDeleted
property to on
when the object's delete function callback is called (see the DeleteFcn
property). It remains set to on
while the delete function executes, after which the object no longer exists.
For example, an object's delete function might call other functions that act on a number of different objects. These functions may not need to perform actions on objects that are going to be deleted, and therefore, can check the object's BeingDeleted
property before acting.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction
property enables you to control how MATLAB handles events that potentially interrupt executing callback routines. If there is a callback routine executing, callback routines invoked subsequently always attempt to interrupt it. If the Interruptible
property of the object whose callback is executing is set to on
(the default), then interruption occurs at the next point where the event queue is processed. If the Interruptible
property is off
, the BusyAction
property (of the object owning the executing callback) determines how MATLAB handles the event. The choices are
cancel
-- Discard the event that attempted to execute a second callback routine.
queue
-- Queue the event that attempted to execute a second callback routine until the current callback finishes.
ButtonDownFcn
string or function handle
Button press callback function. A callback routine that executes whenever you press a mouse button while the pointer is in the figure window, but not over a child object (i.e., uicontrol, axes, or axes child). Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.
See the figure's SelectionType
property to determine whether modifier keys were also pressed.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
Children
vector of handles
Children of the figure. A vector containing the handles of all axes, user-interface objects displayed within the figure. You can change the order of the handles and thereby change the stacking of the objects on the display.
When an object's HandleVisibility
property is set to off
, it is not listed in its parent's Children
property. See HandleVisibility
for more information.
Clipping
{on} | off
This property has no effect on figures.
CloseRequestFcn
string or function handle
Function executed on figure close. This property defines a function that MATLAB executes whenever you issue the close
command (either a close(figure_handle)
or a close
all
), when you close a figure window from the computer's window manager menu, or when you quit MATLAB.
The CloseRequestFcn
provides a mechanism to intervene in the closing of a figure. It allows you to, for example, display a dialog box to ask a user to confirm or cancel the close operation or to prevent users from closing a figure that contains a GUI.
close
command from the command line, by closing the window from the computer's window manager menu, or by quitting MATLAB.
CloseRequestFcn
. The default function is named closereq
and is predefined as
These statements unconditionally delete the current figure, destroying the window. closereq
takes advantage of the fact that the close
command makes all figures specified as arguments the current figure before calling the respective close request function.
You can set CloseRequestFcn
to any string that is a valid MATLAB statement, including the name of an M-file. For example,
This close request function never closes the figure window; it simply echoes "This window is immortal" on the command line. Unless the close request function calls delete
, MATLAB never closes the figure. (Note that you can always call delete(
figure_handle
)
from the command line if you have created a window with a nondestructive close request function.)
A more useful application of the close request function is to display a question dialog box asking the user to confirm the close operation. The following M-file illustrates how to do this.
% my_closereq % User-defined close request function % to display a question dialog box selection = questdlg('Close Specified Figure?',... 'Close Request Function',... 'Yes','No','Yes'); switch selection, case 'Yes', delete(gcf) case 'No' return end
Now assign this M-file to the CloseRequestFcn
of a figure:
To make this M-file your default close request function, set a default value on the root level.
MATLAB then uses this setting for the CloseRequestFcn
of all subsequently created figures.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
Color
ColorSpec
Background color. This property controls the figure window background color. You can specify a color using a three-element vector of RGB values or one of the MATLAB predefined names. See ColorSpec
for more information.
Colormap
m-by-3 matrix of RGB values
Figure colormap. This property is an m-by-3 array of red, green, and blue (RGB) intensity values that define m individual colors. MATLAB accesses colors 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. Colormaps can be any length (up to 256 only on MS-Windows), but must be three columns wide. The default figure colormap contains 64 predefined colors.
Colormaps affect the rendering of surface, image, and patch objects, but generally do not affect other graphics objects. See colormap
and ColorSpec
for more information.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a callback routine that executes when MATLAB creates a figure object. You must define this property as a default value for figures. For example, the statement
defines a default value on the root level that causes the created figure to use noninteger handles whenever you (or MATLAB) create a figure. MATLAB executes this routine after setting all properties for the figure. Setting this property on an existing figure object has no effect.
The handle of the object whose
CreateFcn
is being executed is accessible only through the root CallbackObject
property, which you can query using gcbo
.
CurrentAxes
handle of current axes
Target axes in this figure. MATLAB sets this property to the handle of the figure's current axes (i.e., the handle returned by the gca
command when this figure is the current figure). In all figures for which axes children exist, there is always a current axes. The current axes does not have to be the topmost axes, and setting an axes to be the CurrentAxes
does not restack it above all other axes.
You can make an axes current using the axes
and set
commands. For example, axes(
axes_handle
)
and set(gcf,
'
CurrentAxes
'
,
axes_handle
)
both make the axes identified by the handle axes_handle
the current axes. In addition, axes(
axes_handle
)
restacks the axes above all other axes in the figure.
If a figure contains no axes, get(gcf,
'
CurrentAxes
'
)
returns the empty matrix. Note that the gca
function actually creates an axes if one does not exist.
CurrentCharacter
single character
Last key pressed. MATLAB sets this property to the last key pressed in the figure window. CurrentCharacter
is useful for obtaining user input.
CurrentMenu
(Obsolete)
This property produces a warning message when queried. It has been superseded by the root CallbackObject
property.
CurrentObject
object handle
Handle of current object. MATLAB sets this property to the handle of the last object clicked on by the mouse. This object is the front-most object in the view. You can use this property to determine which object a user has selected. The function gco
provides a convenient way to retrieve the CurrentObject
of the CurrentFigure
.
Note that cursor motion over objects does not update the CurrentObject
; you must click on objects to update this property. See the CurrentPoint
property for related information.
CurrentPoint
two-element vector: [x-coordinate, y-coordinate]
Location of last button click in this figure. MATLAB sets this property to the location of the pointer at the time of the most recent mouse button press. MATLAB updates this property whenever you press the mouse button while the pointer is in the figure window.
Note that if you select a point in the figure and then use the values returned by the CurrentPoint property to plot that point, there can be differences in the position due to round off errors.
CurrentPoint and Cursor Motion
In addition to the behavior described above, MATLAB updates CurrentPoint
before executing callback routines defined for the figure WindowButtonMotionFcn
and WindowButtonUpFcn
properties. This enables you to query CurrentPoint
from these callback routines. It behaves like this:
WindowButtonMotionFcn
or the WindowButtonUpFcn
, then MATLAB updates the CurrentPoint
only when the mouse button is pressed down within the figure window.
WindowButtonMotionFcn
, then MATLAB updates the CurrentPoint
just before executing the callback. Note that the WindowButtonMotionFcn
executes only within the figure window unless the mouse button is pressed down within the window and then held down while the pointer is moved around the screen. In this case, the routine executes (and the CurrentPoint
is updated) anywhere on the screen until the mouse button is released.
WindowButtonUpFcn
, MATLAB updates the CurrentPoint
just before executing the callback. Note that the WindowButtonUpFcn
executes only while the pointer is within the figure window unless the mouse button is pressed down initially within the window. In this case, releasing the button anywhere on the screen triggers callback execution, which is preceded by an update of the CurrentPoint
.
The figure CurrentPoint
is updated only when certain events occur, as previously described. In some situations, (such as when the WindowButtonMotionFcn
takes a long time to execute and the pointer is moved very rapidly) the CurrentPoint
may not reflect the actual location of the pointer, but rather the location at the time when the WindowButtonMotionFcn
began execution.
The CurrentPoint
is measured from the lower left corner of the figure window, in units determined by the Units
property.
The root PointerLocation
property contains the location of the pointer updated synchronously with pointer movement. However, the location is measured with respect to the screen, not a figure window.
See uicontrol
for information on how this property is set when you click a uicontrol object.
DeleteFcn
string or function handle
Delete figure callback routine. A callback routine that executes when the figure object is deleted (e.g., when you issue a delete
or a close
command). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine.
The handle of the object whose
DeleteFcn
is being executed is accessible only through the root CallbackObject
property, which you can query using gcbo
.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
Dithermap
Obsolete
This property is not useful with TrueColor displays and will be removed in a future release.
DithermapMode
Obsolete
This property is not useful with TrueColor displays and will be removed in a future release.
DockControls
{
on} | off
Displays controls used to dock figure. This property determines whether the figure enables the Desktop menu item and the dock figure button in the titlebar that allow you to dock the figure into the MATLAB desktop.
By default, the figure docking controls are visible. If you set this property to off
, the Desktop menu item that enables you to dock the figure is disabled and the figure dock button is not displayed.
See also the WindowStyle
property for more information on docking figure.
DoubleBuffer
{on} | off
Flash-free rendering for simple animations. Double buffering is the process of drawing to an off-screen pixel buffer and then blitting the buffer contents to the screen once the drawing is complete. Double buffering generally produces flash-free rendering for simple animations (such as those involving lines, as opposed to objects containing large numbers of polygons). Use double buffering with the animated objects' EraseMode
property set to normal
. Use the set
command to disable double buffering.
Double buffering works only when the figure Renderer
property is set to painters
.
FileName
String
GUI FIG-file name. GUIDE stores the name of the FIG-file used to save the GUI layout in this property.
FixedColors
m-by-3 matrix of RGB values (read only)
Noncolormap colors. Fixed colors define all colors appearing in a figure window that are not obtained from the figure colormap. These colors include axis lines and labels, the colors of line, text, uicontrol, and uimenu objects, and any colors that you explicitly define, for example, with a statement like
Fixed color definitions reside in the system color table and do not appear in the figure colormap. For this reason, fixed colors can limit the number of simultaneously displayed colors if the number of fixed colors plus the number of entries in the figure colormap exceed your system's maximum number of colors.
(See the root ScreenDepth
property for information on determining the total number of colors supported on your system. See the MinColorMap
and ShareColors
properties for information on how MATLAB shares colors between applications.)
HandleVisibility
{on} | callback | off
Control access to object's handle by command-line users and GUIs. This property determines when an object's handle is visible in its parent's list of children. HandleVisibility
is useful for preventing command-line users from accidentally drawing into or deleting a figure that contains only user interface devices (such as a dialog box).
Handles are always visible when HandleVisibility
is on
.
Setting HandleVisibility
to callback
causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.
Setting HandleVisibility
to off
makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent's list of children, it cannot be returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get
, findobj
, gca
, gcf
, gco
, newplot
, cla
, clf
, and close
.
When a handle's visibility is restricted using callback
or off
, the object's handle does not appear in its parent's Children
property, figures do not appear in the root's CurrentFigure
property, objects do not appear in the root's CallbackObject
property or in the figure's CurrentObject
property, and axes do not appear in their parent's CurrentAxes
property.
You can set the root ShowHiddenHandles
property to on to make all handles visible, regardless of their HandleVisibility
settings (this does not affect the values of the HandleVisibility
properties).
Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest
determines if the figure can become the current object (as returned by the gco
command and the figure CurrentObject
property) as a result of a mouse click on the figure. If HitTest
is off
, clicking the figure sets the CurrentObject
to the empty matrix.
IntegerHandle
{on} | off
Figure handle mode. Figure object handles are integers by default. When creating a new figure, MATLAB uses the lowest integer that is not used by an existing figure. If you delete a figure, its integer handle can be reused.
If you set this property to off
, MATLAB assigns nonreusable real-number handles (e.g., 67.0001221) instead of integers. This feature is designed for dialog boxes where removing the handle from integer values reduces the likelihood of inadvertently drawing into the dialog box.
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible
property controls whether a figure callback routine can be interrupted by callback routines invoked subsequently. Only callback routines defined for the ButtonDownFcn
, KeyPressFcn
, WindowButtonDownFcn
, WindowButtonMotionFcn
, and WindowButtonUpFcn
are affected by the Interruptible
property. MATLAB checks for events that can interrupt a callback routine only when it encounters a drawnow
, figure
, getframe
, or pause
command in the routine. See the BusyAction
property for related information.
InvertHardcopy
{on} | off
Change hardcopy to black objects on white background. This property affects only printed output. Printing a figure having a background color (Color
property) that is not white results in poor contrast between graphics objects and the figure background and also consumes a lot of printer toner.
When InvertHardCopy
is on
, MATLAB eliminates this effect by changing the color of the figure and axes to white and the axis lines, tick marks, axis labels, etc., to black. lines, text, and the edges of patches and surfaces may be changed, depending on the print
command options specified.
If you set InvertHardCopy
to off
, the printed output matches the colors displayed on the screen.
See print
for more information on printing MATLAB figures.
KeyPressFcn
string or function handle
Key press callback function. A callback routine invoked by a key press in the figure window. You can define KeyPressFcn
as any legal MATLAB expression, the name of an M-file, or a function handle.
The callback can query the figure's CurrentCharacter
property to determine what particular key was pressed and thereby limit the callback execution to specific keys.
The callback can query the figure's SelectionType
property to determine whether modifier keys were also pressed.
The callback can also query the root PointerWindow
property to determine in which figure the key was pressed. Note that pressing a key while the pointer is in a particular figure window does not make that figure the current figure (i.e., the one referred to by the gcf
command).
KeyPressFcn Event Structure
When the callback is a function handle, MATLAB passes a structure to the callback function that contains the following fields.
Some key combinations do not define a value for the Character
field.
Using the KeyPressFcn
This example, creates a figure and defines a function handle callback for the KeyPressFcn property. When the "e" key is pressed, the callback exports the figure as an EPS file. When Ctrl-t is pressed, the callback exports the figure as a TIFF file.
function figure_keypress figure('KeyPressFcn',@printfig); function printfig(src,evnt) if evnt.Character == 'e' print ('-deps',['-f' num2str(src)])
See Function Handle Callbacks for information on how to use function handles to define the callback function.
MenuBar
none | {figure}
Enable-disable figure menu bar. This property enables you to display or hide the menu bar that MATLAB places at the top of a figure window. The default (figure
) is to display the menu bar.
This property affects only built-in menus. Menus defined with the uimenu
command are not affected by this property.
MinColormap
scalar (default = 64)
Minimum number of color table entries used. This property specifies the minimum number of system color table entries used by MATLAB to store the colormap defined for the figure (see the ColorMap
property). In certain situations, you may need to increase this value to ensure proper use of colors.
For example, suppose you are running color-intensive applications in addition to MATLAB and have defined a large figure colormap (e.g., 150 to 200 colors). MATLAB may select colors that are close but not exact from the existing colors in the system color table because there are not enough slots available to define all the colors you specified.
To ensure that MATLAB uses exactly the colors you define in the figure colormap, set MinColorMap
equal to the length of the colormap.
Note that the larger the value of MinColorMap
, the greater the likelihood that other windows (including other MATLAB figure windows) will be displayed in false colors.
Name
string
Figure window title. This property specifies the title displayed in the figure window. By default, Name
is empty and the figure title is displayed as Figure 1
, Figure 2
, and so on. When you set this parameter to a string, the figure title becomes Figure 1: <
string
>
. See the NumberTitle
property.
NextPlot
new | {add} | replace | replacechildren
How to add next plot. NextPlot
determines which figure MATLAB uses to display graphics output. If the value of the current figure is
new
-- Create a new figure to display graphics (unless an existing parent is specified in the graphing function as a property/value pair).
add
-- Use the current figure to display graphics (the default).
replace
-- Reset all figure properties except Position
to their defaults and delete all figure children before displaying graphics (equivalent to clf
reset
).
replacechildren
-- Remove all child objects, but do not reset figure properties (equivalent to clf
).
The newplot
function provides an easy way to handle the NextPlot
property. Also see the NextPlot
axes property and Controlling creating_plotsGraphics Output for more information.
NumberTitle
{on} | off
(GUIDE default off
)
Figure window title number. This property determines whether the string Figure No. N
(where N
is the figure number) is prefixed to the figure window title. See the Name
property.
PaperOrientation
{portrait} | landscape
Horizontal or vertical paper orientation. This property determines how printed figures are oriented on the page. portrait
orients the longest page dimension vertically; landscape
orients the longest page dimension horizontally. See the orient
command for more detail.
PaperPosition
four-element rect vector
Location on printed page. A rectangle that determines the location of the figure on the printed page. Specify this rectangle with a vector of the form
where left
specifies the distance from the left side of the paper to the left side of the rectangle and bottom
specifies the distance from the bottom of the page to the bottom of the rectangle. Together these distances define the lower left corner of the rectangle. width
and height
define the dimensions of the rectangle. The PaperUnits
property specifies the units used to define this rectangle.
PaperPositionMode
auto | {manual}
WYSIWYG printing of figure. In manual
mode, MATLAB honors the value specified by the PaperPosition
property. In auto
mode, MATLAB prints the figure the same size as it appears on the computer screen, centered on the page.
See the Pixels per Inch Solution for information on specifying a pixels per inch resolution setting for MATLAB figures. Doing so might be necassary to obtain a printed figure that is the same size as it is on screen.
PaperSize
[width height]
Paper size. This property contains the size of the current PaperType
, measured in PaperUnits
. See PaperType
to select standard paper sizes.
PaperType
Select a value from the following table.
Selection of standard paper size. This property sets the PaperSize
to one of the following standard sizes.
Note that you may need to change the PaperPosition
property in order to position the printed figure on the new paper size. One solution is to use normalized
PaperUnits
, which enables MATLAB to automatically size the figure to occupy the same relative amount of the printed page, regardless of the paper size.
PaperUnits
normalized | {inches} | centimeters | points
Hardcopy measurement units. This property specifies the units used to define the PaperPosition
and PaperSize
properties. All units are measured from the lower left corner of the page. normalized
units map the lower left corner of the page to (0, 0) and the upper right corner to (1.0, 1.0). inches
, centimeters
, and points
are absolute units (one point equals 1/72 of an inch).
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
Handle of figure's parent. The parent of a figure object is the root object. The handle to the root is always 0.
Pointer
crosshair | {arrow} | watch | topl |
topr | botl | botr | circle | cross |
fleur | left | right | top | bottom |
fullcrosshair | ibeam | custom
Pointer symbol selection. This property determines the symbol used to indicate the pointer (cursor) position in the figure window. Setting Pointer
to custom
allows you to define your own pointer symbol. See the PointerShapeCData
property and Specifying the Figure Pointer for more information.
PointerShapeCData
16-by-16 matrix
User-defined pointer. This property defines the pointer that is used when you set the Pointer
property to custom
. It is a 16-by-16 element matrix defining the 16-by-16 pixel pointer using the following values:
1
-- Color pixel black.
2
-- Color pixel white.
NaN
-- Make pixel transparent (underlying screen shows through).
Element (1,1) of the PointerShapeCData
matrix corresponds to the upper left corner of the pointer. Setting the Pointer
property to one of the predefined pointer symbols does not change the value of the PointerShapeCData
. Computer systems supporting 32-by-32 pixel pointers fill only one quarter of the available pixmap.
PointerShapeHotSpot
two-element vector
Pointer active area. A two-element vector specifying the row and column indices in the PointerShapeCData
matrix defining the pixel indicating the pointer location. The location is contained in the CurrentPoint
property and the root object's PointerLocation
property. The default value is element (1,1), which is the upper left corner.
Position
four-element vector
Figure position. This property specifies the size and location on the screen of the figure window. Specify the position rectangle with a four-element vector of the form
where left
and bottom
define the distance from the lower left corner of the screen to the lower left corner of the figure window. width
and height
define the dimensions of the window. See the Units
property for information on the units used in this specification. The left
and bottom
elements can be negative on systems that have more than one monitor.
You can use the get
function to obtain this property and determine the position of the figure and you can use the set
function
to resize and move the figure to a new location.
Note that on MS-Windows systems, figure windows cannot be less than 104 pixels wide, regardless of the value of the Position
property.
Renderer
painters | zbuffer | OpenGL
Rendering method used for screen and printing. This property enables you to select the method used to render MATLAB graphics. The choices are
painters
-- The original rendering method used by MATLAB is faster when the figure contains only simple or small graphics objects.
zbuffer
-- MATLAB draws graphics objects faster and more accurately because objects are colored on a per-pixel basis and MATLAB renders only those pixels that are visible in the scene (thus eliminating front-to-back sorting errors). Note that this method can consume a lot of system memory if MATLAB is displaying a complex scene.
OpenGL
-- OpenGL is a renderer that is available on many computer systems. This renderer is generally faster than painters or zbuffer and in some cases enables MATLAB to access graphics hardware that is available on some systems. Note that when the Renderer
is set to opengl
, MATLAB sets BackingStore
to off
.
Hardware vs. Software OpenGL Implementations
There are two kinds of OpenGL implementations -- hardware and software.
The hardware implementation makes use of special graphics hardware to increase performance and is therefore significantly faster than the software version. Many computers have this special hardware available as an option or may come with this hardware right out of the box.
Software implementations of OpenGL are much like the ZBuffer renderer that is available on MATLAB Version 5.0 and later; however, OpenGL generally provides superior performance to ZBuffer.
OpenGL Availability
OpenGL is available on all computers that run MATLAB. MATLAB automatically finds hardware accelerated versions of OpenGl if such versions are available. If the hardware accelerated version is not available, then MATLAB uses the software version.
The following software versions are available:
MATLAB issues a warning if it cannot find a usable OpenGL library.
Selecting Hardware Accelerated or Software OpenGL
MATLAB enables you to switch between hardware accelerated and software OpenGL. However, MS-Windows and Unix systems behave differently:
opengl info
command or create graphs before you call opengl software
. To re-enable hardware accelerated OpenGL, you must restart MATLAB.
If you do not want to use hardware OpenGL, but do want to use object transparency, you can issue the following command.
This command forces MATLAB to use software OpenGL. Software OpenGL is useful if your hardware accelerated version of OpenGL does not function correctly and you want to use image, patch, or surface transparency, which requires the OpenGL renderer. To reenable hardware OpenGL, use the command
on MS-Windows systems or restart MATLAB on UNIX systems.
By default, MATLAB uses hardware accelerated OpenGL.
See the opengl
reference page for additional information
Determining What Version You Are Using
To determine the version and vendor of the OpenGL library that MATLAB is using on your system, type the following command at the MATLAB prompt:
The returned information contains a line that indicates if MATLAB is using software (Software = true
) or hardware accelerated (Software = false
) OpenGL.
This command also returns a string of extensions to the OpenGL specification that are available with the particular library MATLAB is using. This information is helpful to The MathWorks, so please include this information if you need to report bugs.
Note that issuing the opengl info
command causes MATLAB to initialize OpenGL.
OpenGL vs. Other MATLAB Renderers
There are some differences between drawings created with OpenGL and those created with the other renderers. The OpenGL specific differences include
phong
value for the FaceLighting
and EdgeLighting
properties of surfaces and patches.
If You Are Having Problems
Consult the OpenGL Technical Note if you are having problems using OpenGL. This technical note contains a wealth of information on MATLAB renderers.
RendererMode
{auto} | manual
Automatic or user selection of renderer. This property enables you to specify whether MATLAB should choose the Renderer
based on the contents of the figure window, or whether the Renderer
should remain unchanged.
When the RendererMode
property is set to auto
, MATLAB selects the rendering method for printing as well as for screen display based on the size and complexity of the graphics objects in the figure.
For printing, MATLAB switches to zbuffer
at a greater scene complexity than for screen rendering because printing from a Z-buffered figure can be considerably slower than one using the painters
rendering method, and can result in large PostScript files. However, the output does always match what is on the screen. The same holds true for OpenGL: the output is the same as that produced by the ZBuffer renderer -- a bitmap with a resolution determined by the print
command's -r
option.
Criteria for Autoselection of OpenGL Renderer
When the RendererMode
property is set to auto
, MATLAB uses the following criteria to determine whether to select the OpenGL renderer:
If the opengl
autoselection mode is autoselect
, MATLAB selects OpenGL if
zbuffer
based on figure contents.
When the RendererMode
property is set to manual
, MATLAB does not change the Renderer
, regardless of changes to the figure contents.
Resize
{on} | off
Window resize mode. This property determines if you can resize the figure window with the mouse. on
means you can resize the window, off
means you cannot. When Resize
is off
, the figure window does not display any resizing controls (such as boxes at the corners), to indicate that it cannot be resized.
ResizeFcn
string or function handle
Window resize callback routine. MATLAB executes the specified callback routine whenever you resize the figure window. You can query the figure's Position
property to determine the new size and position of the figure window. During execution of the callback routine, the handle to the figure being resized is accessible only through the root CallbackObject
property, which you can query using gcbo
.
You can use ResizeFcn
to maintain a GUI layout that is not directly supported by the MATLAB Position
/Units
paradigm.
For example, consider a GUI layout that maintains an object at a constant height in pixels and attached to the top of the figure, but always matches the width of the figure. The following ResizeFcn
accomplishes this; it keeps the uicontrol whose Tag
is 'StatusBar'
20 pixels high, as wide as the figure, and attached to the top of the figure. Note the use of the Tag
property to retrieve the uicontrol handle, and the gcbo
function to retrieve the figure handle. Also note the defensive programming regarding figure Units
, which the callback requires to be in pixels in order to work correctly, but which the callback also restores to their previous value afterwards.
u = findobj('Tag','StatusBar'); fig = gcbo; old_units = get(fig,'Units'); set(fig,'Units','pixels'); figpos = get(fig,'Position'); upos = [0, figpos(4) - 20, figpos(3), 20]; set(u,'Position',upos); set(fig,'Units',old_units);
You can change the figure Position
from within the ResizeFcn
callback; however, the ResizeFcn
is not called again as a result.
Note that the print
command can cause the ResizeFcn
to be called if the PaperPositionMode
property is set to manual
and you have defined a resize function. If you do not want your resize function called by print
, set the PaperPositionMode
to auto
.
See Figure Resize Functions for an example of how to implement a resize function for a GUI.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
See Resize Behavior for information on creating resize functions using GUIDE.
Selected
on | off
Is object selected? This property indicates whether the figure is selected. You can, for example, define the ButtonDownFcn
to set this property, allowing users to select the object with the mouse.
SelectionHighlight
{on} | off
figures do not indicate selection.
SelectionType
{normal} | extend | alt | open
Mouse selection type. MATLAB maintains this property to provide information about the last mouse button press that occurred within the figure window. This information indicates the type of selection made. Selection types are actions that are generally associated with particular responses from the user interface software (e.g., single-clicking a graphics object places it in move or resize mode; double-clicking a filename opens it, etc.).
The physical action required to make these selections varies on different platforms. However, all selection types exist on all platforms.
Note that the ListBox
style of uicontrols sets the figure SelectionType
property to normal
to indicate a single mouse click or to open
to indicate a double mouse click. See uicontrol
for information on how this property is set when you click a uicontrol object.
ShareColors
{on} | off
Obsolete
Share slots in system color table with like colors. This property is obsolete because MATLAB now requires true color systems.
Tag
string
User-specified object label. The Tag
property provides a means to identify graphics objects with a user-specified label. This is particularly useful when you are constructing interactive graphics programs that would otherwise need to define object handles as global variables or pass them as arguments between callback routines.
For example, suppose you want to direct all graphics output from an M-file to a particular figure, regardless of user actions that may have changed the current figure. To do this, identify the figure with a Tag
.
Then make that figure the current figure before drawing by searching for the Tag
with findobj
.
Toolbar
none | {auto} | figure
Control display of figure toolbar. The Toolbar
property enables you to control whether MATLAB displays the default figure toolbar on figures. There are three possible values:
none
-- do not display the figure toolbar
auto
-- display the figure toolbar, but remove it if a uicontrol is added to the figure
figure
-- display the figure toolbar
Note that this property affects only the figure toolbar; other toolbars (e.g., the Camera Toolbar or Plot Edit Toolbar) are not affected. Selecting Figure Toolbar from the figure View menu sets this property to figure
.
Type
string (read only)
Object class. This property identifies the kind of graphics object. For figures, Type
is always the string 'figure'
.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the figure. Assign this property the handle of a uicontextmenu object created in the figure. Use the uicontextmenu
function to create the context menu. MATLAB displays the context menu whenever you right-click over the figure.
Units
{pixels} | normalized | inches |
centimeters | points | characters
Units of measurement. This property specifies the units MATLAB uses to interpret size and location data. All units are measured from the lower left corner of the window.
normalized
units map the lower left corner of the figure window to (0,0) and the upper right corner to (1.0,1.0).
inches
, centimeters
, and points
are absolute units (one point equals 1/72 of an inch).
pixel
depends on screen resolution.
characters
units are defined by characters from the default system font; the width of one character is the width of the letter x, the height of one character is the distance between the baselines of two lines of text.
This property affects the CurrentPoint
and Position
properties. 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.
When specifying the units as property/value pairs during object creation, you must set the Units
property before specifying the properties that you want to use these units.
UserData
matrix
User-specified data. You can specify UserData
as any matrix you want to associate with the figure object. The object does not use this data, but you can access it using the set
and get
commands.
Visible
{on} | off
Object visibility. The Visible
property determines whether an object is displayed on the screen. If the Visible
property of a figure is off
, the entire figure window is invisible.
WindowButtonDownFcn
string or functional handle
Button press callback function. Use this property to define a callback routine that MATLAB executes whenever you press a mouse button while the pointer is in the figure window. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
WindowButtonMotionFcn
string or functional handle
Mouse motion callback function. Use this property to define a callback routine that MATLAB executes whenever you move the pointer within the figure window. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
WindowButtonUpFcn
string or function handle
Button release callback function. Use this property to define a callback routine that MATLAB executes whenever you release a mouse button. Define this routine as a string that is a valid MATLAB expression or the name of an M-file. The expression executes in the MATLAB workspace.
The button up event is associated with the figure window in which the preceding button down event occurred. Therefore, the pointer need not be in the figure window when you release the button to generate the button up event.
If the callback routines defined by WindowButtonDownFcn
or WindowButtonMotionFcn
contain drawnow
commands or call other functions that contain drawnow
commands and the Interruptible
property is set to off
, the WindowButtonUpFcn
may not be called. You can prevent this problem by setting Interruptible
to on
.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
WindowStyle
{normal} | modal | docked
Normal, modal, or dockable window behavior. When WindowStyle
is set to modal
, the figure window traps all keyboard and mouse events over all MATLAB windows as long as they are visible. Windows belonging to applications other than MATLAB are unaffected. Modal figures remain stacked above all normal figures and the MATLAB command window. When multiple modal windows exist, the most recently created window keeps focus and stays above all other windows until it becomes invisible, or is returned to WindowStyle
normal
, or is deleted. At that time, focus reverts to the window that last had focus.
Figures with WindowStyle
modal
and Visible
off
do not behave modally until they are made visible, so it is acceptable to hide a modal
window instead of destroying it when you want to reuse it.
You can change the WindowStyle
of a figure at any time, including when the figure is visible and contains children. However, on some systems this may cause the figure to flash or disappear and reappear, depending on the windowing system's implementation of normal and modal windows. For best visual results, you should set WindowStyle
at creation time or when the figure is invisible.
Modal figures do not display uimenu children, built-in menus, or toolbars but it is not an error to create uimenus in a modal figure or to change WindowStyle
to modal
on a figure with uimenu children. The uimenu objects exist and their handles are retained by the figure. If you reset the figure's WindowStyle
to normal
, the uimenus are displayed.
Use modal figures to create dialog boxes that force the user to respond without being able to interact with other windows. Typing Control C at the MATLAB prompt causes all figures with WindowStyle
modal
to revert to WindowStyle
normal
, allowing you to type at the command line.
Docked WindowStyle
When WindowStyle
is set to docked
, the figure is docked in the desktop or a document window. When you issue the following command,
MATLAB docks the figure identified by figure_handle
and sets the DockControls
property to on
, if it was off
.
Note that if WindowStyle
is docked
, you cannot set the DockControls
property to off
.
The value of the WindowStyle
property is not changed by calling reset
on a figure.
WVisual
identifier string (MS Windows only)
Specify pixel format for figure. MATLAB automatically selects a pixel format for figures based on your current display settings, the graphics hardware available on your system, and the graphical content of the figure.
Usually, MATLAB chooses the best pixel format to use in any given situation. However, in cases where graphics objects are not rendered correctly, you might be able select a different pixel format and improve results. See Understanding the WVisual String for more information.
Querying Available Pixel Formats on Window Systems
You can determine what pixel formats are available on your system for use with MATLAB using the following statement:
MATLAB returns a list of the currently available pixel formats for the current figure. For example, the following are the first three entries from a typical list.
01 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, Opengl, GDI, Window) 02 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, Opengl, Double Buffered, Window) 03 (RGB 16 bits(05 06 05 00) zdepth 24, Hardware Accelerated, Opengl, Double Buffered, Window)
Use the number at the beginning of the string to specify which pixel format to use. For example,
specifies the second pixel format in the list above. Note that pixel formats may differ on your system.
Understanding the WVisual String
The string returned by querying the WVisual
property provide information on the pixel format. For example,
RGB 16 bits(05 06 05 00)
- indicates true color with 16-bit resolution (5 bits for red, 6 bits for green, 5 bits for blue, and 0 for alpha (transparency). MATLAB requires true color.
zdepth 24
- indicates 24-bit resolution for sorting object's front to back position on the screen. Selecting pixel formats with higher (24 or 32) zdepth might solve sorting problems.
Hardware Accelerated
- some graphics functions may be performed by hardware for increased speed. If there are incompatibilities between your particular graphic hardware and MATLAB, select a pixel format in which the term Generic
appears instead of Hardware Accelerated
.
Opengl
- supports OpenGL. See Pixel Formats and OpenGL for more information.
GDI
- supports for Windows 2-D graphics interface.
Double Buffered
- support for double buffering with the OpenGL renderer. Note that the figure DoubleBuffer
property applies only to the painters renderer.
Bitmap
- support for rendering into a bitmap (as opposed to drawing in the window)
Window
- support for rendering into a window
Pixel Formats and OpenGL
If you are experiencing problems using hardware OpenGL on your system, you can try using generic OpenGL, which is implemented in software. To do this, first instruct MATLAB to use the software version of OpenGL with the following statement.
Then allow MATLAB to select best pixel format to use.
See the Renderer
property for more information on how MATLAB uses OpenGL.
WVisualMode
auto
| manual
(MS Windows only)
Auto or manual selection of pixel format. VisualMode
can take on two values -- auto
(the default) and manual
. In auto
mode, MATLAB selects the best pixel format to use based on your computer system and the graphical content of the figure. In manual
mode, MATLAB does not change the visual from the one currently in use. Setting the WVisual
property sets this property to manual
.
XDisplay
display identifier (UNIX only)
Contains the display used for MATLAB. You can query this property to determine the name of the display that MATLAB is using. For example, if MATLAB is running on a system called mycomputer, querying XDisplay
returns a string of the following form:
Setting XDisplay on Motif
If your computer uses Motif-based figures, you can specify the display MATLAB uses for a figure by setting the value of the figure's XDisplay
property. For example, to display the current figure on a system called fred
, use the command
XVisual
visual identifier (UNIX only)
Select visual used by MATLAB. You can select the visual used by MATLAB by setting the XVisual
property to the desired visual ID. This can be useful if you want to test your application on an 8-bit or grayscale visual. To see what visuals are available on your system, use the UNIX xdpyinfo
command. From MATLAB, type
The information returned contains a line specifying the visual ID. For example,
To use this visual with the current figure, set the XVisual
property to the ID.
To see which of the available visuals MATLAB can use, call set
on the XVisual
property:
The following typical output shows the visual being used (in curly brackets) and other possible visuals. Note that MATLAB requires a TrueColor visual.
{ 0x23 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) } 0x24 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x25 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x26 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x27 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x28 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x29 (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff) 0x2a (TrueColor, depth 24, RGB mask 0xff0000 0xff00 0x00ff)
You can also use the glxinfo
unix command to see what visuals are available for use with the OpenGL renderer. From MATLAB, type
After providing information about the implemenation of OpenGL on your system, glxinfo
returns a table of visuals. The partial listing below shows typcial output.
visual x bf lv rg d st colorbuffer ax dp st accumbuffer ms cav id dep cl sp sz l ci b ro r g b a bf th cl r g b a ns b eat ---------------------------------------------------------------- 0x23 24 tc 0 24 0 r y . 8 8 8 8 0 0 0 0 0 0 0 0 0 None 0x24 24 tc 0 24 0 r . . 8 8 8 8 0 0 0 0 0 0 0 0 0 None 0x25 24 tc 0 24 0 r y . 8 8 8 8 0 24 8 0 0 0 0 0 0 None 0x26 24 tc 0 24 0 r . . 8 8 8 8 0 24 8 0 0 0 0 0 0 None 0x27 24 tc 0 24 0 r y . 8 8 8 8 0 0 0 16 16 16 0 0 0 Slow
The third column is the class of visual. tc
means a true color visual. Note that some visuals may be labeled Slow
under the caveat column. Such visuals should be avoided.
To determine which visual MATLAB will use by default with the OpenGL renderer, use the MATLAB opengl
info
command. The returned entry for the visual might look like the following.
Experimenting with a different TrueColor visual may improve certain rendering problems.
XVisualMode
auto
| manual
Auto or manual selection of visual. VisualMode
can take on two values -- auto
(the default) and manual
. In auto
mode, MATLAB selects the best visual to use based on the number of colors, availability of the OpenGL extension, etc. In manual
mode, MATLAB does not change the visual from the one currently in use. Setting the XVisual
property sets this property to manual
.
figure | figurepalette |
© 1994-2005 The MathWorks, Inc.