Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Text Properties

Control text appearance and behavior

Text properties control the appearance and behavior of a text object. By changing property values, you can modify certain aspects of the text.

Starting in R2014b, you can use dot notation to query and set properties.

t = text(0.5,0.5,'text here');
s = t.FontSize;
t.FontSize = 12;

If you are using an earlier release, use the get and set functions instead.

Text

expand all

Text to display, specified as a character array, string array, cell array, or numeric value.

Example: 'my label'

Example: string('my label')

Example: {'first line','second line'}

Example: 123

To include numeric variables with text, use the num2str function. For example:

x = 42;
str = ['The value is ',num2str(x)];

To include special characters, such as superscripts, subscripts, Greek letters, or mathematical symbols use TeX markup. For a list of supported markup, see the Interpreter property.

To create multiline text:

  • Use a string array, where each element contains a line of text, such as string({'line one','line two'}).

  • Use a cell array, where each cell contains a line of text, such as {'first line','second line'}.

  • Use a character array, where each row contains the same number of characters, such as ['abc'; 'ab '].

  • Use sprintf to create text with a new line character, such as sprintf('first line \n second line'). This property converts text with new line characters to cell arrays.

Text that contains only a numeric value is converted using sprintf('%g',value). For example, 12345678 displays as 1.23457e+07.

    Note:   The words default, factory, and remove are reserved words that will not appear in text when quoted as a normal characters. To display any of these words individually, precede them with a backslash, such as '\default' or '\remove'.

Interpretation of text characters, specified as one of these values:

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

  • 'latex' — Interpret characters 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 font type and color, and include special characters in the text.

This table lists the supported modifiers with the Interpreter property set to 'tex'. Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they only modify the next character or the characters within the curly braces.

ModifierDescriptionExample
^{ }Superscript'text^{superscript}'
_{ }Subscript'text_{subscript}'
\bfBold font'\bf text'
\itItalic font'\it text'
\slOblique font (usually the same as italic font)'\sl text'
\rmNormal font'\rm text'
\fontname{specifier}Font name — Set specifier as the name of a font family. You can use this in combination with other modifiers.'\fontname{Courier} text'
\fontsize{specifier}Font size — Set specifier as a numeric scalar value in point units to change the font size.'\fontsize{15} text'
\color{specifier}Font color — 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}Custom font color — Set specifier as a three-element RGB triplet.'\color[rgb]{0,0.5,0.5} text'

This table lists the supported special characters with the Interpreter property 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 Interpreter property to 'latex'. Use dollar symbols around the text, for example, use '$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

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.

The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters. For multiline text, 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/.

Font Style

expand all

Text color, specified as a three-element RGB triplet, a character vector of a color name, or 'none'. The default color is black with an RGB triplet value of [0 0 0]. If you set the color to 'none', then the text 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 the long and short color name options and the equivalent RGB triplet values.

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: 'blue'

Example: [0 0 1]

Font name, specified as the name of the font to use or 'FixedWidth'. To display and print properly, the font name must be a font that your system supports. The default font depends on the specific operating system and locale.

To use a fixed-width font that looks good in any locale, use 'FixedWidth'. 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'

Font size, specified as a scalar value greater than zero in point units. One point equals 1/72 inch. To change the font units, use the FontUnits property.

Example: 12

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

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.
'normalized'Interpret font size as a fraction of the axes height. If you resize the axes, the font size modifies accordingly. For example, if the FontSize is 0.1 in normalized units, then the text is 1/10 of the axes height.
'pixels'

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux® systems, the size of a pixel is determined by your system 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.

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.

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

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

  • 'bold' — Thicker character 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 still can result in the normal font weight.

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

Smooth font character appearance, specified as one of these values:

  • 'on' — Apply font smoothing. Reduce the appearance of jaggedness in the text characters to make the text easier to read.

  • 'off' — Do not apply font smoothing.

Text Box

expand all

Color of box outline, specified as 'none', a three-element RGB triplet, or a character vector of a color name. The default edge color of 'none' makes the box outline 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 the long and short color name options and the equivalent RGB triplet values.

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: 'blue'

Example: [0 0 1]

Color of text box background, specified as 'none', a three-element RGB triplet, or a character vector of a color name. The default background color of 'none' makes the text box background transparent.

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 the long and short color name options and the equivalent RGB triplet values.

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: 'blue'

Example: [0 0 1]

The space around the text within the text box, specified as scalar numeric value in point units.

MATLAB uses the Extent property value plus the Margin property value to determine the size of the text box.

Example: 8

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

Line style of box outline, specified as one of the options in this table.

Line StyleDescriptionResulting Line
'-'Solid line

'--'Dashed line

':'Dotted line

'-.'Dash-dotted line

'none'Line is invisible 

Width of box outline, specified as a scalar numeric value in point units. One point equals 1/72 inch.

Example: 1.5

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

Location and Size

expand all

Location of the text, specified as a two-element vector of the form [x y] or a three-element vector of the form [x y z]. If you omit the third element, z, then MATLAB sets it to 0.

Specify the position using numeric values. To convert datetime or duration values to the appropriate numeric values for a particular coordinate direction, see ruler2num.

By default, the position value is defined in data units. To change the units, use the Units property.

Example: [0.5 0.5 0]

This property is read only.

Size and location of the rectangle that encloses the text, not including the margin, returned as a four-element vector of the form [left bottom width height]. The first two elements, left and bottom, define the position of the lower left corner of the rectangle. The last two elements, width and height, define the dimensions of the rectangle.

By default, the extent value is defined in data units. To change the units, use the Units property.

Example: [0.5 0.5 0.4 0.2]

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

UnitsDescription
'data' (default)Data coordinates.
'normalized'Normalized with respect to the axes. The lower left corner of the axes maps to (0,0) and the upper right corner maps to (1,1).
'inches'Inches.
'centimeters'Centimeters.
'characters'Based on the default system font character size.
  • Character width = width of letter x.

  • Character height = distance between the baselines of two lines of text.

'points'Points. One point equals 1/72 inch.
'pixels'

Pixels.

Starting in R2015b, distances in pixels are independent of your system resolution on Windows and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux systems, the size of a pixel is determined by your system resolution.

All units, except for 'data', are measured from the lower left corner of the axes. This property affects the Position and Extent properties.

If you specify the Position and Units properties as Name,Value pairs when creating the text object, then the order of specification matters. To define the position with particular units, set the Units property before the Position property.

Text orientation, specified as a scalar value in degrees. The default rotation of 0 degrees makes the text horizontal. For vertical text, set this property to 90 or -90. Positive values rotate the text counterclockwise. Negative values rotate the text clockwise.

Example: 90

Example: -90

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

Horizontal alignment of the text with respect to the x value in the Position property, specified as one of the values in this table. The vertical line indicates where the x value lies in relation to the text.

ValueResult
'left' (default)

'center'

'right'

Vertical alignment of the text with respect to the y value in the Position property, specified as one of the values in this table. The horizontal line indicates where the y value lies in relation to the text.

ValueResult
'middle'

'top'

'cap'

'bottom'

'baseline'

Visibility

expand all

State of visibility, specified as one of these values:

  • 'on' — Display the text.

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

Clipping of the text to the axes plot box, which is the box defined by the axis limits, specified as one of these values:

  • 'off' — Do not clip the text. Portions of it might appear outside the axes plot box.

  • 'on' — Clips the text to the axes plot box.

    • If the axes ClippingStyle property is set to '3dbox', which is the default, then MATLAB either displays the entire text or none of the text, depending on the text position. If the point defined by the text Position property lies inside the axes, then MATLAB displays the entire text. If the point lies outside the axes, then MATLAB displays none of it.

    • If the axes ClippingStyle property is set to 'rectangle', then MATLAB displays portions of the text lying inside the axes plot box and does not display portions of the text lying outside the axes plot box.

    Note:   If the Clipping property of the associated axes is set to 'on', which is the default, then each individual object controls its own clipping behavior. If the Clipping property of the axes is set to 'off', then MATLAB does not clip any objects in the axes, regardless of the Clipping property of the individual object.

    Note:   EraseMode has been removed. You can delete code that accesses the EraseMode property with minimal impact. If you were using EraseMode to create line animations, use the animatedline function instead.

Technique to draw and erase objects, specified as one of these values:

  • 'normal' — Redraw the affected region of the display, performing the three-dimensional analysis necessary to correctly render all objects. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and, therefore, are less accurate.

  • 'none' — Do not erase the object when it is moved or destroyed. After you erase the object with EraseMode,'none', it is still visible on the screen. However, you cannot print the object because MATLAB does not store any information on its former location.

  • 'xor' — Draw and erase the object by performing an exclusive OR (XOR) with the color of the screen beneath it. This mode does not damage the color of the objects beneath it. However, the object color depends on the color of whatever is beneath it on the display.

  • 'background' — Erase the object by redrawing it in the axes background color, or the figure background color if the axes Color property is 'none'. This damages objects that are behind the erased object, but properly colors the erased object.

MATLAB always prints figures as if the EraseMode property of all objects is set to 'normal'. This means graphics objects created with EraseMode set to 'none', 'xor', or 'background' can look different on screen than on paper. On screen, MATLAB mathematically combines layers of colors and ignores three-dimensional sorting to obtain greater rendering speed. However, MATLAB does not apply these techniques to the printed output. Use the getframe command or other screen capture applications to create an image of a figure containing nonnormal mode objects.

Identifiers

expand all

This property is read only.

Type of graphics object, returned as 'text'. Use this property to find all objects of a given type within a plotting hierarchy, for example, searching for the type using findobj.

User-specified tag to associate with the text, specified as a character vector. 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'

Data to associate with the text object, specified as any MATLAB data, for example, 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

Parent/Child

expand all

Parent of text, specified as an axes, group, or transform object.

The text has no children. You cannot set this property.

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

  • 'on' — The text object handle is always visible.

  • 'off' — The text object handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

  • 'callback' — The text object handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the text at the command-line, but allows callback functions to access it.

If the text 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

Interactive edit mode, specified as one of these values:

  • 'off' — Do no allow interactive text editing. To change the text, you must set the String property. This is the default value.

  • 'on' — Allow interactive text editing. MATLAB places an insert cursor within the text and typing changes the text. To apply the new text, do any of the following:

    • Press the Esc key.

    • Click anywhere away from the text.

    • Reset the Editing property to 'off'.

    MATLAB updates the String property to contain the new text and resets the Editing property to 'off'.

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

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector 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 text. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

  • The text object — You can access properties of the text 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}

Context menu, specified as a uicontextmenu object. Use this property to display a context menu when you right-click the text. 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.

Selection state, specified as one of these values:

  • 'on' — Selected. If you click the text 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 text.

  • 'off' — Not selected.

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

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 text 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 text responds to the click or if an ancestor does.

  • 'none' — Cannot capture mouse clicks. Clicking the text 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.

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

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

  • 'off' — Trigger the callbacks for the nearest ancestor of the text 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 text object can capture mouse clicks. If it cannot, then the HitTest property has no effect.

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

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 text 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

Creation callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector 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 text. Setting the CreateFcn property on an existing text has no effect. You must define a default value for this property, or define this property using a Name,Value pair during text creation. MATLAB executes the callback after creating the text 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 text object — You can access properties of the text object from within the callback function. You also can access the text 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}

Deletion callback, specified as one of these values:

  • Function handle

  • Cell array containing a function handle and additional arguments

  • Character vector 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 text. MATLAB executes the callback before destroying the text 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 text object — You can access properties of the text object from within the callback function. You also can access the text 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}

This property is read only.

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

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

Was this topic helpful?