Axes Properties

Control axes appearance and behavior

Axes properties control the appearance and behavior of an axes object. By changing property values, you can modify certain aspects of the axes.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

ax = gca;
c = ax.Color;
ax.Color = 'blue';

If you are using an earlier release, use the get and set functions to query and set properties.

Appearance

expand all

ColorColor of axes back planes[1 1 1] (default) | RGB triplet | color string | 'none'

Color of axes back planes, specified as an RGB triplet, a color string, or 'none'. If you set the color to 'none', then the axes is invisible and the figure color shows through.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

BoxAxes box outline'off' (default) | 'on'

Axes box outline, specified as one of these values:

  • 'off' — Do not display the box outline around the axes.

  • 'on' — Display the box outline around the axes. In a 3-D view, the outline appears around the axes back planes. Use the BoxStyle property to change the extent of the outline.

The XColor, YColor, and ZColor properties control the color of the outline.

BoxStyleStyle of axes box outline'back' (default) | 'full'

Style of axes box outline, specified as one of these values:

  • 'back' — Outline the back planes of the 3-D box.

  • 'full' — Outline the entire 3-D box.

The BoxStyle property affects only 3-D views.

XColor, YColor, ZColorColor of axes outline and tick marks[0.15 0.15 0.15] (default) | RGB triplet | color string | 'none'

Color of the axes outline in the x, y, or z direction and the associated tick marks, specified as an RGB triplet, a color string, or 'none'. If you set the color to 'none', then the axes outline is invisible.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Setting this property sets the associated mode property to manual.

Example: [1 1 0]

Example: 'y'

Example: 'yellow'

XColorMode, YColorMode, ZColorModeSelection mode for axes outline color'auto' (default) | 'manual'

Selection mode for the axes outline color, specified as one of these values:

  • 'auto' — Use the default color. For related information about grid-line selection, see the GridColorMode property.

  • 'manual' — Use the manually specified color. To specify the color, set the XColor, YColor, or ZColor property.

LineWidthWidth of axes outline, tick marks, and grid lines0.5 (default) | scalar value

Width of axes outline, tick marks, and grid lines, specified as a scalar value in point units. One point equals 1/72 inch.

Example: 1.5

Individual Axis Lines

expand all

XAxisLocationLocation of x-axis'bottom' (default) | 'top'

Location of the x-axis, specified as one of these values:

  • 'bottom' — Display x-axis at bottom of axes.

  • 'top' — Display x-axis at top of axes.

This property applies only to 2-D views.

YAxisLocationLocation of y-axis'left' (default) | 'right'

Location of y-axis, specified as one of these values:

  • 'left' — Display y-axis on right side of axes.

  • 'right' — Display y-axis on left side of axes.

This property applies only to 2-D views.

XDir, YDir, ZDirDirection of increasing values along axis'normal' (default) | 'reverse'

Direction of increasing values along axis, specified as one of these values:

  • 'normal' — Normal direction of increasing values:

    • x-axis values increase from left to right.

    • y-axis values increase from bottom to top (2-D view) or front to back (3-D view).

    • z-axis values increase pointing out of the screen (2-D view) or from bottom to top (3-D view).

  • 'reverse' — Reverse direction of increasing values:

    • x-axis values decrease from left to right.

    • y-axis values decrease from bottom to top (2-D view) or front to back (3-D view).

    • z-axis values decrease pointing out of the screen (2-D view) or from bottom to top (3-D view).

XScale, YScale, ZScaleScale of values along axis'linear' (default) | 'log'

Scale of values along axis, specified as 'linear' or 'log'.

XLim, YLim, ZLimMinimum and maximum axis limits[0 1] (default) | two-element vector of the form [min max]

Minimum and maximum x-axis, y-axis, or z-axis limits, specified as a two-element vector of the form [min max].

If the associated mode property is set to 'auto', then MATLAB® chooses the axis limits. If you assign a value to this property, then MATLAB sets the mode to 'manual' and does not automatically compute the limits.

XLimMode, YLimMode, ZLimModeSelection mode for axis limits'auto' (default) | 'manual'

Selection mode for the axis limits, specified as one of these values:

  • 'auto' — Select axis limits based on the data plotted, that is, the total span of the XData, YData, or ZData of all the objects displayed in the axes.

  • 'manual' — Use manually specified axis limits. To specify the axis limits, set the XLim, YLim, or ZLim property.

Tick Values and Labels

expand all

XTick, YTick, ZTickTick mark locations[] (default) | vector of increasing values

Tick mark locations, specified as a vector of increasing values.

If the associated mode property is set to 'auto', then MATLAB chooses the tick values. If you assign a value to this property, then MATLAB sets the mode to 'manual' and does not automatically recompute the tick values.

Example: [2 4 6 8 10]

Example: 0:10:100

Data Types: single | double

XTickMode, YTickMode, ZTickModeSelection mode for tick mark locations'auto' (default) | 'manual'

Selection mode for the tick mark locations, specified as one of these values:

  • 'auto' — Select the tick mark locations based on the range of data for the axis.

  • 'manual' — Use manually specified tick mark locations. To specify the values, set the XTick, YTick, or ZTick property.

XTickLabel, YTickLabel, ZTickLabelTick mark labels'' (default) | cell array of strings

Tick mark labels, specified as a cell array of strings. If you do not specify enough strings for all the ticks marks, then the axes cycles through the specified strings. Tick mark labels support TeX and LaTeX markup. See the TickLabelInterpreter property for more information.

If the associated mode property is set to 'auto', then MATLAB chooses the labels. If you assign a value to this property, then MATLAB sets the mode to 'manual' and does not automatically choose the labels.

XTickLabelMode, YTickLabelMode, ZTickLabelModeSelection mode for tick mark labels'auto' (default) | 'manual'

Selection mode for the tick mark labels, specified as one of these values:

  • 'auto' — Label tick marks with numeric values that span the range of the plotted data.

  • 'manual' — Use manually specified tick mark labels. To specify the labels, set the XTickLabel, YTickLabel, or ZTickLabel property.

TickLabelInterpreterInterpretation of characters in tick labels'tex' (default) | 'latex' | 'none'

Interpretation of tick label characters, specified as one of these values:

  • 'tex' — Interpret strings using a subset of TeX markup.

  • 'latex' — Interpret strings using LaTeX markup.

  • 'none' — Display literal characters

TeX Markup

By default, MATLAB supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the text type and color, and include special characters in the text string.

This table lists the supported modifiers when the TickLabelInterpreter property is set to 'tex', which is the default value. Modifiers remain in effect until the end of the string, except for superscripts and subscripts which only modify the next character or the text within the curly braces {}.

ModifierDescriptionExample of String
^{ }Superscript'text^{superscript}'
_{ }Subscript'text_{subscript}'
\bfBold font'\bf text'
\itItalic font'\it text'
\slOblique font (rarely available)'\sl text'
\rmNormal font'\rm text'
\fontname{specifier}Set specifier as the name of a font family to change the font style. You can use this in combination with other modifiers.'\fontname{Courier} text'
\fontsize{specifier}Set specifier as a scalar numeric value to change the font size.'\fontsize{15} text'
\color{specifier}Set specifer as one of these colors: red, green, yellow, magenta, blue, black, white, gray, darkGreen, orange, or lightBlue.'\color{magenta} text'
\color[rgb]{specifier}Set specifier as a three-element RGB triplet to change the font color.'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters when the interpreter is set to 'tex'.

Character SequenceSymbolCharacter SequenceSymbolCharacter SequenceSymbol

\alpha

α

\upsilon

υ

\sim

~

\angle

\phi

Φ

\leq

\ast

*

\chi

χ

\infty

\beta

β

\psi

ψ

\clubsuit

\gamma

γ

\omega

ω

\diamondsuit

\delta

δ

\Gamma

Γ

\heartsuit

\epsilon

ɛ

\Delta

Δ

\spadesuit

\zeta

ζ

\Theta

Θ

\leftrightarrow

\eta

η

\Lambda

Λ

\leftarrow

\theta

Θ

\Xi

Ξ

\Leftarrow

\vartheta

ϑ

\Pi

Π

\uparrow

\iota

ι

\Sigma

Σ

\rightarrow

\kappa

κ

\Upsilon

ϒ

\Rightarrow

\lambda

λ

\Phi

Φ

\downarrow

\mu

µ

\Psi

Ψ

\circ

º

\nu

ν

\Omega

Ω

\pm

±

\xi

ξ

\forall

\geq

\pi

π

\exists

\propto

\rho

ρ

\ni

\partial

\sigma

σ

\cong

\bullet

\varsigma

ς

\approx

\div

÷

\tau

τ

\Re

\neq

\equiv

\oplus

\aleph

\Im

\cup

\wp

\otimes

\subseteq

\oslash

\cap

\in

\supseteq

\supset

\lceil

\subset

\int

\cdot

·

\o

ο

\rfloor

\neg

¬

\nabla

\lfloor

\times

x

\ldots

...

\perp

\surd

\prime

´

\wedge

\varpi

ϖ

\0

\rceil

\rangle

\mid

|

\vee

\langle

\copyright

©

LaTeX Markup

To use LaTeX markup, set the TickLabelInterpreter property to 'latex'. The displayed text uses the default LaTeX font style. The FontName, FontWeight, and FontAngle properties do not have an effect. To change the font style, use LaTeX markup within the text string.

The maximum size of the string that you can use with the LaTeX interpreter is 1200 characters. For multiline strings, this reduces by about 10 characters per line.

For more information about the LaTeX system, see The LaTeX Project website at http://www.latex-project.org/.

XTickLabelRotation, YTickLabelRotation, ZTickLabelRotationRotation of tick labels0 (default) | scalar value in degrees

Rotation of tick labels, specified as a scalar value in degrees. Negative values give clockwise rotation.

Example: 90

XMinorTick, YMinorTick, ZMinorTickDisplay of minor tick marks'off' (default) | 'on'

Display of minor tick marks, specified as one of these values:

  • 'off' — Do not display minor tick marks.

  • 'on' — Display minor tick marks between the major tick marks on the axis. The space between the major tick marks determines the number of minor tick marks.

TickLengthTick mark length[0.01 0.025] (default) | two-element vector

Tick mark length, specified as a two-element vector of the form [2Dlength 3Dlength]. The first element is the tick mark length in 2-D views and the second element is the tick mark length in 3-D views. Specify the values in units normalized relative to the longest of the visible x-axis, y-axis, or z-axis lines.

Example: [0.02 0.035]

TickDirTick mark direction'in' (default) | 'out'

Tick mark direction, specified as one of these values:

  • 'in' — Direct tick marks inward from the axis lines. This is the default for 2-D views.

  • 'out' — Direct tick marks outward from the axis lines. This is the default for 3-D views.

If the associated mode property is set to 'auto', then MATLAB chooses the tick label direction. If you set this property, then MATLAB sets the mode to 'manual' and does not automatically choose the tick label direction.

TickDirModeSelection mode for TickDir'auto' (default) | 'manual'

Selection mode for the TickDir property, specified as one of these values:

  • 'auto' — Use default tick direction.

  • 'manual' — Use manually specified tick mark direction. To specify the tick mark direction, set the TickDir property.

Grid Lines

expand all

XGrid, YGrid, ZGridDisplay of grid lines'off' (default) | 'on'

Display of grid lines, specified as one of these values:

  • 'off' — Do not display the grid lines.

  • 'on' — Display grid lines perpendicular to the axis, for example, along lines of constant x, y, or z values. Use the grid command to set all three properties 'on' or 'off' .

XMinorGrid, YMinorGrid, ZMinorGridDisplay of minor grid lines'off' (default) | 'on'

Display of minor grid lines, specified as one of these values:

  • 'off' — Do not display grid lines.

  • 'on' — Display grid lines aligned with the minor tick marks of the axis. You do not need to enable minor ticks to display minor grid lines.

GridLineStyleLine style for grid lines'-' (default) | '--' | ':' | '-.' | 'none'

Line style used for grid lines, specified as one of the strings shown in this table.

StringLine Style
'-'Solid line
'--'Dashed line
':'Dotted line
'-.'Dash-dotted line
'none'No line

To display the grid lines, use the grid on command or set the XGrid, YGrid, or ZGrid property to 'on'.

MinorGridLineStyleLine style for minor grid lines':' (default) | '-' | '--' | '-.' | 'none'

Line style used for minor grid lines, specified as one of the strings shown in this table.

StringLine Style
'-'Solid line
'--'Dashed line
':'Dotted line
'-.'Dash-dotted line
'none'No line

To display minor grid lines, use the grid minor command or set the XGridMinor, YGridMinor, or ZGridMinor property to 'on'.

GridColorColor of grid lines[0.15 0.15 0.15] (default) | RGB triplet | color string | 'none'

Color of grid lines, specified as an RGB triplet, a color string, or 'none'.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

To set the colors for the axes box outline, use the XColor, YColor, and ZColor properties.

Setting this property sets the associated mode property to manual.

Example: [0 0 1]

Example: 'b'

Example: 'blue'

GridColorModeSelection mode for GridColor'auto' (default) | 'manual'

Selection mode for the GridColor property, specified as 'auto' or 'manual'. The color is based on the values of the GridColorMode, XColorMode, YColorMode, and ZColorMode properties.

These tables list the grid line colors for different combinations of color modes.

GridColorMode PropertyXColorMode Propertyx-Axis Grid-Line Color

'auto'

'auto'

Use GridColor property.

'auto'

'manual'

Use XGridColorproperty.

'manual'

'auto'

Use GridColor property.

'manual'

'manual'

Use GridColor property.

GridColorMode PropertyYColorMode Propertyy-Axis Grid-Line Color

'auto'

'auto'

Use GridColor property.

'auto'

'manual'

Use YGridColorproperty.

'manual'

'auto'

Use GridColor property.

'manual'

'manual'

Use GridColor property.

GridColorMode PropertyZColorMode Propertyz-Axis Grid-Line Color

'auto'

'auto'

Use GridColor property.

'auto'

'manual'

Use ZGridColorproperty.

'manual'

'auto'

Use GridColor property.

'manual'

'manual'

Use GridColor property.

MinorGridColorColor of minor grid lines[0.1 0.1 0.1] (default) | RGB triplet | color string

Color of minor grid lines, specified as an RGB triplet, a color string, or 'none'.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

GridAlphaGrid-line transparency0.15 (default) | value in the range [0,1]

Grid-line transparency, specified as a value in the range [0,1]. A value of 1 means opaque and a value of 0 means completely transparent.

Setting this property sets the associated mode property to manual.

Example: 0.5

GridAlphaModeSelection mode for GridAlpha'auto' (default) | 'manual'

Selection mode for the GridAlpha property, specified as one of these values:

  • 'auto' — Use default transparency value of 0.15.

  • 'manual' — Use the manually specified transparency value. To specify the value, set the GridAlpha property.

MinorGridAlphaMinor grid-line transparency0.25 (default) | value in the range [0,1]

Minor grid-line transparency, specified as a value in the range [0,1]. A value of 1 means opaque and a value of 0 means completely transparent.

Setting this property sets the associated mode property to manual.

Example: 0.5

MinorGridAlphaModeSelection mode for MinorGridAlpha'auto' (default) | 'manual'

Selection mode for the MinorGridAlpha property, specified as one of these values:

  • 'auto' — Use the default transparency value of 0.15.

  • 'manual' — Use the manually specified transparency value. To specify the value, set the MinorGridAlpha property.

LayerPlacement of grid lines and tick marks in relation to graphic objects'bottom' (default) | 'top'

Placement of grid lines and tick marks in relation to graphic objects, specified as one of these values:

  • 'bottom' — Display tick marks and grid lines under graphics objects.

  • 'top' — Display tick marks and grid lines over graphics objects.

This property affects only 2-D views.

Font Style

expand all

FontNameFont name'Helvetica' (default) | 'FixedWidth' | system supported font name

Font name, specified as the name of the font to use or the string 'FixedWidth'. To display and print properly, the font name must be a font that your system supports.

To use a fixed-width font that looks good in any locale, use the case-sensitive string 'FixedWidth'. This eliminates the need to hard-code the name of a fixed-width font, which might not display text properly on systems that do not use ASCII character encoding. The 'FixedWidth' value relies on the root FixedWidthFontName property. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

Example: 'Cambria'

FontSizeFont size10 (default) | scalar numeric value

Font size, specified as a scalar numeric value. The FontSize, LabelFontSizeMultiplier, and TitleFontSizeMultiplier properties determine the size of the text used for the axis labels and the title. The FontUnits property determines the units used to interpret the font size.

Example: 12

TitleFontSizeMultiplierScale factor for title font size1.1 (default) | numeric value greater than 0

Scale factor for title font size, specified as a numeric value greater than 0. The axes applies this scale factor to the value of the FontSize property to determine the font size for the title.

Example: 1.75

LabelFontSizeMultiplierScale factor for label font size1.1 (default) | numeric value greater than 0

Scale factor for label font size, specified as a numeric value greater than 0. The axes applies this scale factor to the value of the FontSize property to determine the font size for the x-axis, y-axis, and z-axis labels.

Example: 1.5

FontUnitsFont size units'points' (default) | 'inches' | 'centimeters' | 'characters' | 'normalized' | 'pixels'

Font size units, specified as one of the values in this table.

UnitsDescription
'points'Points. One point equals 1/72 inch.
'inches'Inches.
'centimeters'Centimeters.
'characters'Based on the size of characters in the default system font. The width of one character unit is the width of the letter x. The height of one character unit is the distance between the baselines of two lines of text.
'normalized'Interpreted as a fraction of the axes height. If you resize the axes, MATLAB modifies the font size accordingly. For example, if the FontSize is 0.1 in normalized units, then the text is 1/10 of the axes height.
'pixels'Pixels. Pixel size depends on the screen resolution.

If you set both the font size and the font units in one function call, you must set the FontUnits property first so that the axes correctly interprets the specified font size.

FontAngleCharacter slant'normal' (default) | 'italic'

Character slant, specified as 'normal' or 'italic'. Not all fonts have both font styles. Therefore, the italic font might look the same as the normal font.

    Note:   The 'oblique' value has been removed. Use 'italic' instead.

FontWeightThickness of text characters'normal' (default) | 'bold'

Thickness of the text characters, specified as one of these values:

  • 'normal' — Default weight as defined by the particular font

  • 'bold' — Thicker characters outlines than normal

MATLAB uses the FontWeight property to select a font from those available on your system. Not all fonts have a bold font weight. Therefore, specifying a bold font weight could still result in the normal font weight.

    Note:   The 'light' and 'demi' font weight values have been removed. Use 'normal' instead.

TitleFontWeightThickness of title text'bold' (default) | 'normal'

Thickness of the title text, specified as one of these values:

  • 'bold' — Thicker characters outlines than normal.

  • 'normal' — Default weight as defined by the particular font.

FontSmoothingText smoothing'on' (default) | 'off'

Text smoothing, specified as one of these values:

  • 'on' — Use antialiasing to make text appear smoother on the screen.

  • 'off' — Do not use antialiasing. Use this setting if the text seems blurry. In certain cases, smoothed text blends against the background color and results in a blurring effect.

Title and Axis Labels

expand all

TitleText object for axes titletext object (default)

Text object for axes title. Refer to this text object to change properties of the title.

ax = gca;
ax.Title.String = 'My Graph Title';
ax.Title.FontWeight = 'normal';

    Note:   To access the axes title text object, use the Title property or the title function. This text object is not contained in the axes Children property, it cannot be returned by findobj, and it does not use default values defined for text objects.

XLabel, YLabel, ZLabelText object for axis labeltext object (default)

Text object for x-axis, y-axis, or z-axis label. Refer to this text object to change properties of the axis label.

ax = gca;
ax.YLabel.String = 'Y Axis';
ax.YLabel.FontSize = 12;

    Note:   To access the axis label text objects, use the XLabel, YLabel, and ZLabel properties or the xlabel, ylabel, and zlabel functions. These text objects are not contained in the axes Children property, they cannot be returned by findobj, and they do not use default values defined for text objects.

Line Colors and Line Styles

expand all

ColorOrderColors for multiline plotsseven predefined colors (default) | three-column matrix of RGB triplets

Colors for multiline plots, specified as a three-column matrix of RGB triplets. Each row of the matrix defines one color in the color order. The default color order has seven colors.

Default Color OrderAssociated RGB Triplets

    [    0    0.4470    0.7410
    0.8500    0.3250    0.0980
    0.9290    0.6940    0.1250
    0.4940    0.1840    0.5560
    0.4660    0.6740    0.1880
    0.3010    0.7450    0.9330
    0.6350    0.0780    0.1840]

The functions that create line plots cycle through the colors to color each line. The hold state for the axes affects the colors used.

  • If the hold state is off (when the NextPlot property is set to 'replace'), then high-level plotting functions such as plot reset the color order to the default colors before plotting. If you want to specify new colors for the color order and do not want high-level plotting functions to reset them, then set the NextPlot property to 'replacechildren'. Alternatively, you can specify a new default value for the ColorOrder property on the root using the set function. For example, use set(groot,'defaultAxesColorOrder',[0 1 0; 0 0 1]).

  • If the hold state for the axes is on (when the NextPlot property is set to 'add'), then plotting functions cycle through the colors starting from the place in the color order where the last plot ended.

Data Types: single | double

LineStyleOrderLine styles and markers for multiline plots'-' solid line (default) | cell array of specifiers

Line styles and markers for multiline plots, specified as a cell array of one or more specifiers in this table, for example, {'-*',':','o'}.

SpecifierLine Style
'-'(default) Solid line
'--'Dashed line
':'Dotted line
'-.'Dash-dotted line
'+'Plus sign markers
'o'Circle markers
'*'Star markers
'.'Point markers
'x'Cross markers
's'Square markers
'd'Diamond markers
'^'Upward-pointing triangle markers
'v'Downward-pointing triangle markers
'>'Right-pointing triangle markers
'<'Left-pointing triangle markers
'p'Five-pointed star (pentagram) markers
'h'Six-pointed star (hexagram) markers

Combine strings to specify lines with markers, such as '-*'. The plot cycles through the line styles only after using all the colors contained in the ColorOrder property. If the hold state for the axes is off (when the NextPlot property of the axes is set to 'replace'), then high-level plotting functions such as plot reset the line style order to the default line styles before plotting. If you want to specify a set of line styles that is different from the default and do not want high-level plotting functions to reset the LineStyleOrder property, then set NextPlot to 'replacechildren'. Alternatively, you can specify a new default value for the LineStyleOrder property on the root using the set function. For example, use set(groot,'defaultAxesLineStyleOrder',{'-*',':','o'}).

Example: {'-*',':','o'}

ColorOrderIndexNext color to use in color order1 (default) | positive integer

Next color to use in the color order, specified as a positive integer. New plots added to the axes use colors based on the current value of the color order index. To use the first color for the next plot added to the axes, set the property to 1.

After a hold on command, subsequently called plotting functions continue to cycle through the color-order, beginning with the current value of the color order index. Reset the color-order by setting the index to 1.

If the specified index exceeds the number of colors defined by the current ColorOrder property, then plotting functions use the mod function to determine the index value as:

mod(ColorOrderIndex value, number of colors in ColorOrder)

Example: 5

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

LineStyleOrderIndexNext line style to use in line style order1 (default) | positive integer

Next line style to use in line style order, specified as a positive integer. New plots added to the axes use line styles based on the current value of the line style order index. To use the first line style, set this property to 1.

After a hold on command, subsequently called plotting functions continue to cycle through the line-style order, beginning with the current value of the line style order index.

If the specified index exceeds the number of line styles defined by the current LineStyleOrder property, plotting functions use the mod function to determine the index value as:

mod(LineStyleOrderIndex value,number of line styles  in LineStyleOrder)

    Note:   The default LineStyleOrder has only one line style.

Example: 1

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Color and Transparency Mapping

expand all

CLimColor limits for objects using colormap[0 1] (default) | two-element vector of the form [cmin cmax]

Color limits for objects in axes that use the colormap, specified as a two-element vector of the form [cmin cmax]. This property determines how data values map to the colors in the colormap where:

  • cmin specifies the data value that maps to the first color in the colormap.

  • cmax specifies the data value that maps to the last color in the colormap.

The axes linearly interpolates data values between cmin and cmax across the colormap. Values outside this range use either the first or last color, whichever is closest.

For information on changing the colormap, see the colormap function. For information on color mapping, see the caxis function.

If the associated mode property is set to 'auto', then MATLAB chooses the color limits. If you assign a value to this property, then MATLAB sets the mode to 'manual' and does not automatically choose the color limits.

CLimModeSelection mode for CLim'auto' (default) | 'manual'

Selection mode for the CLim property, specified as one of these values:

  • 'auto' — Set the CLim property to span the CData limits of the graphics objects displayed in the axes.

  • 'manual' — Use the manually specified values. To specify the values, set the CLim property. The axes does not change the values when the limits of the axes children change.

ALimAlpha limits for images, patches, and surfaces with transparency[0 1] (default) | two-element vector of the form [amin amax]

Alpha limits for images, patches, and surfaces with transparency, specified as a two-element vector of the form [amin amax]. This property determines how values in the AlphaData properties of image, patch, and surface objects map to the figure alpha map, where:

  • amin specifies the data value mapped to the first alpha value in the figure alpha map.

  • amax specifies the data value mapped to the last alpha value in the figure alpha map.

The axes linearly interpolates data values between amin and amax across the figure alpha map. Values outside this range use either the first or last alpha map value, whichever is closest.

The Alphamap property of the figure contains the alpha map. For more information, see the alpha function.

If the associated mode property is set to 'auto', then MATLAB chooses the alpha limits. If you set this property, then MATLAB sets the mode to 'manual' and does not automatically choose the alpha limits.

ALimModeSelection mode for ALim'auto' (default) | 'manual'

Selection mode for the ALim property, specified as one of these values:

  • 'auto' — Use values that span the AlphaData of the axes children contained in the Children property.

  • 'manual' — Use the manually specified values. To specify the values, set the ALim property.

AmbientLightColorBackground light color[1 1 1] (default) | RGB triplet | color string

Background light color, specified as an RGB triplet or a color string. Ambient light is a directionless light that shines uniformly on all objects in the axes when there is a visible light object in the axes.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [1 0 1]

Example: 'm'

Example: 'magenta'

Multiple Plots

expand all

NextPlotProperties to reset when adding new plot'replace' (default) | 'add' | 'replacechildren'

Properties to reset when adding a new plot to the axes, specified as one of these values:

  • 'replace' — Reset all axes properties, except Position and Units, to their default values and delete all axes children before displaying the new plot. Using this value is similar to using cla reset.

  • 'add' — Use the existing axes to add more plots to the axes and do not reset properties.

  • 'replacechildren' — Remove all child objects before adding new plots, but do not reset axes properties. This is similar to using cla.

The newplot function simplifies the use of the NextPlot property and is useful for writing custom graphing functions. Figures also have a NextPlot property.

SortMethodOrder for rendering objects'depth' (default) | 'childorder'

Order for rendering objects, specified as one of these values:

  • 'depth' — Draw objects in back-to-front order based on the current view. Use this value to ensure that objects in front of other objects are drawn correctly.

  • 'childorder' — Draw objects in the order in which they are created by graphics functions, without considering the relationship of the objects in three dimensions. This value can result in faster rendering, particularly if the figure is very large, but can also result in improper depth sorting of the objects displayed

Visibility

expand all

VisibleVisibility of axes'on' (default) | 'off'

Visibility of axes, specified as one of these values:

  • 'on' — Display the axes.

  • 'off' — Hide the axes without deleting it. You still can access the properties of an invisible axes object.

ClippingClipping of objects to axes limits'on' (default) | 'off'

Clipping of objects to the axes limits, specified as one of these values:

  • 'on' — Do not display parts of plotted objects that are outside the axes limits.

  • 'off' — Display all plotted objects, even if parts of them appear outside the axes limits. Parts can appear outside the limits if you create a plot, set hold on, freeze the axis scaling, and then add a plot that is larger than the original plot.

The axes and individual objects in the axes have a Clipping property that controls the clipping behavior. If the Clipping property for the axes is 'on', then each individual object in the axes controls its own clipping behavior. To disable clipping for all objects in the axes, set the Clipping property for the axes to 'off'. This table lists the results for different combinations of Clipping property values.

Clipping Property for AxesClipping Property for Individual ObjectResult
'on''on'Individual object is clipped (default)
'on''off'Individual object is not clipped
'off''on'No objects in axes are clipped
'off''off'No objects in axes are clipped

ClippingStyleBoundaries used for clipping'3dbox' (default) | 'rectangle'

Boundaries used for clipping, specified as one of these values:

  • '3dbox' — Clip plotted objects to the six sides of the axes box defined by the axis limits.

  • 'rectangle' — Clip plotted objects to a rectangular boundary enclosing the axes in any given view.

The ClippingStyle property does not affect the display of objects if the Clipping property is set to 'off' for either the object or the axes.

Location and Size

expand all

PositionSize and position of axes within figure or uipanel[0.1300 0.1100 0.7750 0.8150] (default) | four-element vector

Size and position of the axes within the figure or uipanel that contains the axes, specified as a four-element vector of the form [left bottom width height]. The left and bottom elements define the distance from the lower-left corner of the container to the lower-left corner of the axes. The width and height elements are the axes dimensions.

By default, the values are measured in units normalized to the container. To change the units, set the Units property.

The axes dimensions are the largest possible values that conform to all other properties and do not extend outside the Position rectangle. Other axes properties that affect the axes size and shape include DataAspectRatio, PlotBoxAspectRatio, and CameraViewAngle.

Example: [0 0 1 1]

TightInsetMargins for text labelsfour-element vector of the form [left bottom right top]

This property is read only.

Margins for the text labels, specified as a four-element vector of the form [left bottom right top]. The elements define the distances between the bounds of the Position property and the extent of the axes text labels and title. By default, the values are measured in units normalized to the figure or uipanel that contains the axes. To change the units, set the Units property.

The Position property and the TightInset property define the tightest bounding box that encloses the axes and its labels and title. The figure shows the region defined by combining the TightInset values and the Position values.

For more information, see Axes Resize to Accommodate Titles and Labels.

OuterPositionSize and location of axes, including labels and margins[0 0 1 1] (default) | four-element vector

Size and location of axes, including the labels and margins, specified as a four-element vector of the form [left bottom width height]. This vector defines the extents of the rectangle that encloses the outer bounds of the axes. The left and bottom elements define the distance from the lower-left corner of the figure or uipanel that contains the axes to the lower-left corner of the rectangle. The width and height elements are the rectangle dimensions.

By default, the values are measured in units normalized to the container. To change the units, set the Units property. The default value of [0 0 1 1] includes the whole interior of the container.

The figure shows the region defined by the OuterPosition enclosed in the red rectangle. The green rectangle is the region defined by the Position property.

For more information, see Axes Resize to Accommodate Titles and Labels.

ActivePositionPropertyPosition property to hold constant during resize operation'outerposition' (default) | 'position'

Position property to hold constant during resize operation, specified as one of these values:

  • 'outerposition' — Hold the OuterPosition property constant. Resizing the figure does not clip any of the text.

  • 'position' — Hold the Position property constant.

A figure can change size if you interactively change resize it or during a printing or exporting operation.

UnitsPosition units'normalized' (default) | 'inches' | 'centimeters' | 'points' | 'pixels' | 'characters'

Position units, specified as one of the values in this table.

UnitsDescription
'normalized' (default)Normalized with respect to the container, which is typically the figure or a uipanel. The lower-left corner of the container maps to (0,0) and the upper-right corner maps to (1,1).
'inches'Inches.
'centimeters'Centimeters.
'characters'Based on the size of characters in the default system font. The width of one character unit is the width of the letter x. The height of one character unit is the distance between the baselines of two lines of text.
'points'Points. One point equals 1/72 inch.
'pixels'Pixels. Pixel size depends on the screen resolution.

When specifying the units as a Name,Value pair during object creation, you must set the Units property before specifying the properties that you want to use these units, such as Position.

Aspect Ratio

expand all

ProjectionType of projection onto 2-D screen'orthographics' (default) | 'perspective'

Type of projection onto 2-D screen, specified as one of these values:

  • 'orthographic' — Maintain the correct relative dimensions of graphics objects regarding the distance of a given point from the viewer, and draw lines that are parallel in the data on the screen.

  • 'perspective' — Incorporate foreshortening, which allows you to perceive depth in 2-D representations of 3-D objects. Perspective projection does not preserve the relative dimensions of objects. Instead, it displays a distant line segment smaller than a nearer line segment of the same length. Lines that are parallel in the data might not appear parallel on screen.

DataAspectRatioRelative length of data units along each axis[1 1 1] (default) | three-element vector of the form [dx dy dz]

Relative length of data units along each axis, specified as a three-element vector of the form [dx dy dz]. This vector defines the relative x, y, and z data scale factors. For example, specifying this property as [1 2 1] sets the length of one unit of data in the x-direction to be the same length as two units of data in the y-direction and one unit of data in the z-direction.

The DataAspectRatio property interacts with the PlotBoxAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control how MATLAB scales the x-axis, y-axis, and z-axis.

Setting a value for the DataAspectRatio disables the "stretch-to-fill figure shape" behavior if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all set to 'auto'.

If the associated mode property is set to 'auto', then MATLAB chooses the ratio values. If you set this property, then MATLAB sets the mode to 'manual'.

Example: [1 1 1]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

DataAspectRatioModeSelection mode for DataAspectRatio'auto' (default) | 'manual'

Selection mode for the DataAspectRatio property, specified as one of these values:

  • 'auto' — Use values that make best use of the area provided by the figure.

  • 'manual' — Use the manually specified values. To specify the values, set the DataAspectRatio property. Changing DataAspectRatioMode to 'manual' disables the "stretch-to-fill figure shape" behavior if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all 'auto'.

    This table describes the behavior for various combinations of properties when you disable the stretch-to-fill behavior.

    XLimitMode, YLimitMode, and ZLimitMode

    DataAspectRatioMode

    PlotBoxAspectRatioMode

    Behavior

    'auto'

    'auto'

    'auto'

    The axes chooses limits that span the data range in all dimensions.

    'auto'

    'auto'

    'manual'

    The axes chooses limits that span the data range in all dimensions and modifies DataAspectRatio to achieve the specified PlotBoxAspectRatio within the limits.

    'auto'

    'manual'

    'auto'

    The axes chooses limits that span the data range in all dimensions and modifies PlotBoxAspectRatio to achieve the specified DataAspectRatio within the limits.

    'auto'

    'manual'

    'manual'

    The axes chooses limits that completely fit and center the plot within the specified PlotBoxAspectRatio given the specified DataAspectRatio (this might produce empty space around 2 of the 3 dimensions).

    'manual'

    'auto'

    'auto'

    The axes honors the specified limits and modifies the DataAspectRatio and PlotBoxAspectRatio as necessary.

    'manual'

    'auto'

    'manual

    The axes honors the specified limits and PlotBoxAspectRatio values and modifies the DataAspectRatio values as necessary.

    'manual'

    'manual'

    'auto'

    The axes honors the specified limits and DataAspectRatio values and modifies the PlotBoxAspectRatio values as necessary.

    One set to 'manual' and two set to 'auto'

    'manual'

    'manual'

    The axes selects the remaining limits to honor the specified aspect ratios and limit.

    Two set to 'manual' and one set to 'auto', or all three set to 'manual'

    'manual'

    'manual'

    The axes ignores the PlotBoxAspectRatio value and uses the specified limits and DataAspectRatio

PlotBoxAspectRatioRelative length of each axis[1 1 1] (default) | three-element vector of the form [px py pz]

Relative length of each axis, specified as a three-element vector of the form [px py pz] defining the relative x-axis, y-axis, and z-axis scale factors. The plot box is a box enclosing the axes data region as defined by the axis limits.

The PlotBoxAspectRatio property interacts with the DataAspectRatio, XLimMode, YLimMode, and ZLimMode properties. Setting the PlotBoxAspectRatio disables the "stretch-to-fill figure shape" behavior, if DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode are all 'auto'.

If the associated mode property is set to 'auto', then MATLAB chooses the ratio values. If you set this property, then MATLAB sets the mode to 'manual'.

Example: [1,0.75,0.75]

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

PlotBoxAspectRatioModeSelection mode for PlotBoxAspectRatio'auto' (default) | 'manual'

Selection mode for the PlotBoxAspectRatio property, specified as one of these values:

  • 'auto' — Use values that make best use of the area provided by the figure.

  • 'manual' — Use the manually specified values. To specify the values, set the PlotBoxAspectRatio property. Changing PlotBoxAspectRatioMode to 'manual' disables the "stretch-to-fill figure shape" behavior if PlotBoxAspectRatioMode, DataAspectRatioMode, and CameraViewAngleMode are all 'auto'.

This table describes the behavior for various combinations of properties when you disable the stretch-to-fill behavior.

XLimitMode, YLimitMode, and ZLimitMode

DataAspectRatioMode

PlotBoxAspectRatioMode

Behavior

'auto'

'auto'

'auto'

The axes chooses limits that span the data range in all dimensions.

'auto'

'auto'

'manual'

The axes chooses limits that span the data range in all dimensions and modifies DataAspectRatio to achieve the specified PlotBoxAspectRatio within the limits.

'auto'

'manual'

'auto'

The axes chooses limits that span the data range in all dimensions and modifies PlotBoxAspectRatio to achieve the specified DataAspectRatio within the limits.

'auto'

'manual'

'manual'

The axes chooses limits that completely fit and center the plot within the specified PlotBoxAspectRatio given the specified DataAspectRatio (this might produce empty space around 2 of the 3 dimensions).

'manual'

'auto'

'auto'

The axes honors the specified limits and modifies the DataAspectRatio and PlotBoxAspectRatio as necessary.

'manual'

'auto'

'manual

The axes honors the specified limits and PlotBoxAspectRatio values and modifies the DataAspectRatio values as necessary.

'manual'

'manual'

'auto'

The axes honors the specified limits and DataAspectRatio values and modifies the PlotBoxAspectRatio values as necessary.

One set to 'manual' and two set to 'auto'

'manual'

'manual'

The axes selects the remaining limits to honor the specified aspect ratios and limit.

Two set to 'manual' and one set to 'auto', or all three set to 'manual'

'manual'

'manual'

The axes ignores the PlotBoxAspectRatio value and uses the specified limits and DataAspectRatio

View

expand all

CameraPositionLocation of camerathree-element vector of the form [x y z]

Location of camera, or the viewpoint, specified as a three-element vector of the form [x y z]. This vector defines the axes coordinates of the location. Changing the CameraPosition property changes the point from which you view the axes.

The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

If the Projection is 'perspective', then as you change the CameraPosition, the amount of perspective also changes.

If the associated mode property is set to 'auto', then MATLAB chooses the camera location. If you set this property, then MATLAB sets the mode to 'manual'.

Data Types: single | double

CameraPositionModeSelection mode for CameraPosition'auto' (default) | 'manual'

Selection mode for the CameraPosition property, specified as one of these values:

  • 'auto' — Calculate the CameraPosition value such that the camera lies a fixed distance from the target along the azimuth and elevation specified by the current view, as returned by the view function. Functions like rotate3d, zoom, and pan, change this mode to 'auto' to perform their actions.

  • 'manual' — Use the manually specified value. To specify the value, set the CameraPosition property.

This table summarizes the camera behavior for various combinations of CameraViewAngleMode, CameraTargetMode, and CameraPositionMode property values.

CameraViewAngleModeCameraTargetModeCameraPositionModeBehavior
'auto''auto''auto'

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

'auto''auto''manual'

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene.

'auto''manual''auto'

Sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

'auto''manual''manual'

Sets CameraViewAngle to capture entire scene.

'manual''auto''auto'

Sets CameraTarget to plot box centroid, sets CameraPosition along the view axis.

'manual''auto''manual'

Sets CameraTarget to plot box centroid.

'manual''manual''auto'

Sets CameraPosition along the view axis.

'manual''manual''manual'

Uses specified camera values

CameraTargetPoint used as camera targetthree-element vector of the form [x y z]

Point used as camera target, specified as a three-element vector of the form [x y z]. This vector defines the axes coordinates of the point. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

If the associated mode property is set to 'auto', then MATLAB chooses the camera target point. If you set this property, then MATLAB sets the mode to 'manual'.

Data Types: single | double

CameraTargetModeSelection mode for CameraTarget'auto' (default) | 'manual'

Selection mode for the CameraTarget property, specified as one of these values:

  • 'auto' — Position the camera target at the centroid of the axes plot box.

  • 'manual' — Use the manually specified camera target value. To specify a value, set the CameraTarget property.

This table summarizes the camera behavior for various combinations of CameraViewAngleMode, CameraTargetMode, and CameraPositionMode property values.

CameraViewAngleModeCameraTargetModeCameraPositionModeBehavior
'auto''auto''auto'

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

'auto''auto''manual'

Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene.

'auto''manual''auto'

Sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

'auto''manual''manual'

Sets CameraViewAngle to capture entire scene.

'manual''auto''auto'

Sets CameraTarget to plot box centroid, sets CameraPosition along the view axis.

'manual''auto''manual'

Sets CameraTarget to plot box centroid.

'manual''manual''auto'

Sets CameraPosition along the view axis.

'manual''manual''manual'

Uses specified camera values

CameraUpVectorVector defining upwards direction[0 1 0] (default for 2-D view) | [0 0 1] (default for 3-D view) | three-element direction vector of the form [x y z]

Vector defining upwards direction, specified as a three-element direction vector of the form [x y z]. For an illustration, see Camera Graphics Terminology.

If the associated mode property is set to 'auto', then MATLAB chooses the vector values. If you set this property, then MATLAB sets the mode to 'manual'.

Example: [sin(45) cos(45) 1]

CameraUpVectorModeSelection mode for CameraUpVector'auto' (default) | 'manual'

Selection mode for the CameraUpVector property, specified as one of these values:

  • 'auto' — Use [0 0 1] for 3-D views so that the positive z-direction is up. Use [0 1 0] for 2-D views so that the positive y-direction is up.

  • 'manual' — Use the manually specified vector defining the upwards direction. To specify a value, set the CameraUpVector property.

CameraViewAngleField of view6.6086 (default) | scalar angle in range [0,180)

Field of view, specified as a scalar angle greater than 0 and less than or equal to 180. Changing the camera view angle affects the size of graphics objects displayed in the axes, but does not affect the degree of perspective distortion. The greater the angle, the larger the field of view and the smaller objects appear in the scene. For an illustration, see Camera Graphics Terminology.

If the associated mode property is set to 'auto', then MATLAB chooses the field of view value. If you set this property, then MATLAB sets the mode to 'manual'.

Example: 15

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

CameraViewAngleModeSelection mode for CameraViewAngle'auto' (default) | 'manual'

Selection mode for the CameraViewAngle property, specified as one of these values:

  • 'auto' — Select the field of view as the minimum angle that captures the entire scene, up to 180 degrees.

  • 'manual' — Use the manually specified field of view. To specify a value, set the CameraViewAngle property.

    This table summarizes the camera behavior for various combinations of CameraViewAngleMode, CameraTargetMode, and CameraPositionMode property values.

    CameraViewAngleModeCameraTargetModeCameraPositionModeBehavior
    'auto''auto''auto'

    Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

    'auto''auto''manual'

    Sets CameraTarget to plot box centroid, sets CameraViewAngle to capture entire scene.

    'auto''manual''auto'

    Sets CameraViewAngle to capture entire scene, sets CameraPosition along the view axis.

    'auto''manual''manual'

    Sets CameraViewAngle to capture entire scene.

    'manual''auto''auto'

    Sets CameraTarget to plot box centroid, sets CameraPosition along the view axis.

    'manual''auto''manual'

    Sets CameraTarget to plot box centroid.

    'manual''manual''auto'

    Sets CameraPosition along the view axis.

    'manual''manual''manual'

    Uses specified camera values

View(obsolete) Azimuth and elevation of view[0 90] (default) | two-element vector of the form [azimuth elevation]

Azimuth and elevation of view, specified as a two-element vector of the form [azimuth elevation] defined in degree units.

This property is obsolete. Use the CameraPosition, CameraTarget, CameraUpVector, and CameraViewAngle properties instead.

Example: [45 45]

Identifiers

expand all

TypeType of graphics object'axes'

This property is read only.

Type of graphics object returned as the string 'axes'.

TagTag to associate with axes'' (default) | any string

Tag to associate with the axes, specified as a string. Tags provide a way to identify graphics objects. Use this property to find all objects with a specific tag within a plotting hierarchy, for example, searching for the tag using findobj.

Example: 'January Data'

UserDataData to associate with axes[] (default) | scalar, vector, or matrix | cell array | character array | table | structure

Data to associate with the axes object, specified as a scalar, vector, matrix, cell array, character array, table, or structure. MATLAB does not use this data.

To associate multiple sets of data or to attach a field name to the data, use the getappdata and setappdata functions.

Example: 1:100

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct | table | cell

Parent/Child

expand all

ParentParent of axesfigure object | uipanel object

Parent of axes, specified as figure object or a uipanel object.

ChildrenChildren of axesempty GraphicsPlaceholder array | array of graphics objects

Children of axes, returned as an array of graphics objects. Use this property to view a list of the children or to reorder the children by setting the property to a permutation of itself.

You cannot add or remove children using the Children property of the axes. To add a child to this list, set the Parent property of the child graphics object to the axes object.

HandleVisibilityVisibility of object handle'on' (default) | 'off' | 'callback'

Visibility of object handle in the Children property of the parent, specified as one of these values:

  • 'on' — List the axes object.

  • 'off' — Do not list the axes object. Use this option to hide object handles when a callback invokes a function that could damage the GUI, such as evaluating a user-typed string.

  • 'callback' — List the axes object in the Children property of the parent from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. Use this option to protect a GUI from command-line users, while allowing callbacks to have access to objects.

If the axes object is not listed in the Children property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Interactive Control

expand all

CurrentPointLocation of last mouse click2-by-3 array

Location of last mouse click, specified as a 2-by-3 array in the axes coordinate system. The CurrentPoint property contains the coordinates of two points defined by the location of the pointer at the last mouse click, with respect to the requested axes.

If the click is within the axes in orthogonal projection, then the two points lie on the line that is perpendicular to the plane of the screen and that passes through the pointer. This is true for both 2-D and 3-D views.

The 3-D coordinates are the points, in the axes coordinate system, where this line intersects the front and back surfaces of the axes volume (which is defined by the axes x, y, and z limits).

The returned matrix is of the form:

[xfront yfront zfront
 xback  yback  zback]

The first row defines the point nearest to the camera position. The second row specified the point furthest from the camera position.

If the click is outside the axes in orthogonal projection, but within the figure, the returned values are:

  • Back point — Point in the plane of the camera target (which is perpendicular to the viewing axis).

  • Front point — Point in the camera position plane (which is perpendicular to the viewing axis).

These points lie on a line that passes through the pointer and is perpendicular to the camera target and camera position planes.

The values of the current point when using perspective projection can be different from the same point in orthographic projection because the shape of the axes volume can be different.

Clicking outside of the axes volume in perspective projection returns the front point as the current camera position at all times. Only the back point updates with the coordinates of a point that lies on a line extending from the camera position through the pointer and intersecting the camera target at that point.

For related information, see the axes Projection, CameraPosition, and CameraTarget properties. Also, see the figure CurrentPoint properties.

ButtonDownFcnMouse-click callback'' (default) | function handle | cell array | string

Mouse-click callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • String that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you click the axes. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The axes object — You can access properties of the axes object from within the callback function.

  • Event data — This argument is empty for this property. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

    Note:   If the PickableParts property is set to 'none' or if the HitTest property is set to 'off', then this callback does not execute.

Example: @myCallback

Example: {@myCallback,arg3}

UIContextMenuContext menuuicontextmenu object

Context menu, specified as a uicontextmenu object. Use this property to display a context menu when you right-click the axes. Create the context menu using the uicontextmenu function.

    Note:   If the PickableParts property is set to 'none' or if the HitTest property is set to 'off', then the context menu does not appear.

SelectedSelection state'off' (default) | 'on'

Selection state, specified as one of these values:

  • 'on' — Selected. If you click the axes when in plot edit mode, then MATLAB sets its Selected property to 'on'. If the SelectionHighlight property also is set to 'on', then MATLAB displays selection handles around the axes.

  • 'off' — Not selected.

SelectionHighlightDisplay of selection handles when selected'on' (default) | 'off'

Display of selection handles when selected, specified as one of these values:

  • 'on' — Display selection handles when the Selected property is set to 'on'.

  • 'off' — Never display selection handles, even when the Selected property is set to 'on'.

Callback Execution Control

expand all

PickablePartsAbility to capture mouse clicks'visible' (default) | 'all' | 'none'

Ability to capture mouse clicks, specified as one of these values:

  • 'visible' — Can capture mouse clicks only when visible. The Visible property must be set to 'on'. The HitTest property determines if the axes responds to the click or if an ancestor does.

  • 'all' — Can capture mouse clicks regardless of visibility. The Visible property can be set to 'on' or 'off'. The HitTest property determines if the axes responds to the click or if an ancestor does.

  • 'none' — Cannot capture mouse clicks. Clicking the axes passes the click to the object below it in the current view of the figure window, which is typically the axes or the figure. The HitTest property has no effect.

If you want an object to be clickable when it is underneath other objects that you do not want to be clickable, then set the PickableParts property of the other objects to 'none' so that the click passes through them.

HitTestResponse to captured mouse clicks'on' (default) | 'off'

Response to captured mouse clicks, specified as one of these values:

  • 'on' — Trigger the ButtonDownFcn callback of the axes. If you have defined the UIContextMenu property, then invoke the context menu.

  • 'off' — Trigger the callbacks for the nearest ancestor of the axes that has a HitTest property set to 'on' and a PickableParts property value that enables the ancestor to capture mouse clicks.

    Note:   The PickableParts property determines if the axes object can capture mouse clicks. If it cannot, then the HitTest property has no effect.

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

    Note:   There are two callback states to consider:

    • The running callback is the currently executing callback.

    • The interrupting callback is a callback that tries to interrupt the running callback.

    Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue.

If the ButtonDownFcn callback of the axes is the running callback, then the Interruptible property determines if it another callback can interrupt it:

  • 'on' — Interruptible. Interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause command.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes. For more information, see Interrupt Callback Execution.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — Not interruptible. MATLAB finishes executing the running callback without any interruptions.

BusyActionCallback queuing'queue' (default) | 'cancel'

Callback queuing specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks.

    Note:   There are two callback states to consider:

    • The running callback is the currently executing callback.

    • The interrupting callback is a callback that tries to interrupt the running callback.

    Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue.

If the ButtonDownFcn callback of the axes tries to interrupt a running callback that cannot be interrupted, then the BusyAction property determines if it is discarded or put in the queue. Specify the BusyAction property as one of these values:

  • 'queue' — Put the interrupting callback in a queue to be processed after the running callback finishes execution. This is the default behavior.

  • 'cancel' — Discard the interrupting callback.

Creation and Deletion Control

expand all

CreateFcnCreation callback'' (default) | function handle | cell array | string

Creation callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • String that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you create the axes. Setting the CreateFcn property on an existing axes has no effect. You must define a default value for this property, or define this property using a Name,Value pair during axes creation. MATLAB executes the callback after creating the axes and setting all of its properties.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The axes object — You can access properties of the axes object from within the callback function. You also can access the axes object through the CallbackObject property of the root, which can be queried using the gcbo function.

  • Event data — This argument is empty for this property. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

Example: @myCallback

Example: {@myCallback,arg3}

DeleteFcnDeletion callback'' (default) | function handle | cell array | string

Deletion callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • String that is a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

Use this property to execute code when you delete the axes. MATLAB executes the callback before destroying the axes so that the callback can access its property values.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The axes object — You can access properties of the axes object from within the callback function. You also can access the axes object through the CallbackObject property of the root, which can be queried using the gcbo function.

  • Event data — This argument is empty for this property. Replace it with the tilde character (~) in the function definition to indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see Callback Definition.

Example: @myCallback

Example: {@myCallback,arg3}

BeingDeletedDeletion status of axes'off' (default) | 'on'

This property is read only.

Deletion status of axes, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the axes begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the axes no longer exists.

Check the value of the BeingDeleted property to verify that the axes is not about to be deleted before querying or modifying it.

Was this topic helpful?