MATLAB Function Reference

text

Create text object in current axes

Syntax

• text(x,y,'string')
  text(x,y,z,'string')
  text(...'PropertyName',PropertyValue...)
  h = text(...)
  

Description

text is the low-level function for creating text graphics objects. Use text to place character strings at specified locations.

text(x,y,'string') adds the string in quotes to the location specified by the point (x,y).

text(x,y,z,'string') adds the string in 3-D coordinates.

text(x,y,z,'string','PropertyName',PropertyValue....) adds the string in quotes to location defined by the coordinates and uses the values for the specified text properties. See the text property list section at the end of this page for a list of text properties.

text('PropertyName',PropertyValue....) omits the coordinates entirely and specifies all properties using property name/property value pairs.

h = text(..) returns a column vector of handles to text objects, one handle per object. All forms of the text function optionally return this output argument.

See the String property for a list of symbols, including Greek letters.

Remarks

Specify the text location coordinates (the x, y, and z arguments) in the data units of the current axes (see "Examples"). The Extent, VerticalAlignment, and HorizontalAlignment properties control the positioning of the character string with regard to the text location point.

If the coordinates are vectors, text writes the string at all locations defined by the list of points. If the character string is an array the same length as x, y, and z, text writes the corresponding row of the string array at each point specified.

When specifying strings for multiple text objects, the string can be

• a cell array of strings
• a padded string matrix
• a string vector using vertical slash characters (`|') as separators.

Each element of the specified string array creates a different text object.

When specifying the string for a single text object, cell arrays of strings and padded string matrices result in a text object with a multiline string, while vertical slash characters are not interpreted as separators and result in a single line string containing vertical slashes.

text is a low-level function that accepts property name/property value pairs as input arguments, however; the convenience form,

• text(x,y,z,'string')
  

is equivalent to:

• text('XData',x,'YData',y,'ZData',z,'String','string')
  

You can specify other properties only as property name/property value pairs. See the text property list at the end of this page for a description of each property. You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types).

text does not respect the setting of the figure or axes NextPlot property. This allows you to add text objects to an existing axes without setting hold to on.

Examples

The statements,

• plot(0:pi/20:2*pi,sin(0:pi/20:2*pi))
  text(pi,0,' \leftarrow sin(\pi)','FontSize',18)
  

annotate the point at (pi,0) with the string sin().

The statement,

• text(x,y,'\ite^{i\omega\tau} = cos(\omega\tau) + i sin(\omega\tau)')
  

uses embedded TeX sequences to produce:

See Also

gtext, int2str, num2str, title, xlabel, ylabel, zlabel

The "Labeling Graphs" topic in the online Using MATLAB Graphics manual discusses positioning text.

Object Hierarchy

Setting Default Properties

You can set default text properties on the axes, figure, and root levels.

• set(0,'DefaulttextProperty',PropertyValue...)
  set(gcf,'DefaulttextProperty',PropertyValue...)
  set(gca,'DefaulttextProperty',PropertyValue...)
  

Where Property is the name of the text property and PropertyValue is the value you are specifying. Use set and get to access text properties.

Property List

The following table lists all text properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name	Property Description	Property Value
Defining the character string
Editing	Enable or disable editing mode.	Values: on, off Default: off
Interpreter	Enable or disable TeX interpretation	Values: tex, none Default: tex
String	The character string (including list of TeX character sequences)	Value: character string
Positioning the character string
Extent	Position and size of text object	Values: [left, bottom, width, height]
HorizontalAlignment	Horizontal alignment of text string	Values: left, center, right Default: left
Position	Position of text Extent rectangle	Values: [x, y, z] coordinates Default: [] empty matrix
Rotation	Orientation of text object	Values: scalar (degrees) Default: 0
Units	Units for Extent and Position properties	Values: pixels, normalized, inches, centimeters, points, data Default: data
VerticalAlignment	Vertical alignment of text string	Values: top, cap, middle, baseline, bottom Default: middle
Text Bounding Box
BackgroundColor	Color of text extent rectangle	Values: ColorSpec Default: none
EdgeColor	Color of edge drawn around text extent rectangle	Values: ColorSpec Default: none
LineWidth	Width of the line (in points) use to draw the box drawn around text extent rectangle	Values: scalar (points) Default: 0.5
LineStyle	Style of the line use to draw the box drawn around text extent rectangle	Values: -, --, :, -., none Default: -
Margin	Distance in pixels from the text extent to the edge of the box enclosing the text.	Values: scalar (pixels) Default: 2
Specifying the Font
FontAngle	Select italic-style font	Values: normal, italic, oblique Default: normal
FontName	Select font family	Values: a font supported by your system or the string FixedWidth Default: Helvetica
FontSize	Size of font	Values: size in FontUnits Default: 10 points
FontUnits	Units for FontSize property	Values: points, normalized, inches, centimeters, pixels Default: points
FontWeight	Weight of text characters	Values: light, normal, demi, bold Default: normal
Controlling the Appearance
Clipping	Clipping to axes rectangle	Values: on, off Default: on
EraseMode	Method of drawing and erasing the text (useful for animation)	Values: normal, none, xor, background Default: normal
SelectionHighlight	Highlight text when selected (Selected property set to on)	Values: on, off Default: on
Visible	Make the text visible or invisible	Values: on, off Default: on
Color	Color of the text	ColorSpec
Controlling Access to Text Objects
HandleVisibility	Determines if and when the the text's handle is visible to other functions	Values: on, callback, off Default: on
HitTest	Determines if the text can become the current object (see the figure CurrentObject property)	Values: on, off Default: on
General Information About Text Objects
Children	Text objects have no children	Values: [] (empty matrix)
Parent	The parent of a text object is always an axes object	Value: axes handle
Selected	Indicate whether the text is in a "selected" state.	Values: on, off Default: off
Tag	User-specified label	Value: any string Default: '' (empty string)
Type	The type of graphics object (read only)	Value: the string 'text'
UserData	User-specified data	Values: any matrix Default: [] (empty matrix)
Controlling Callback Routine Execution
BusyAction	Specifies how to handle callback routine interruption	Values: cancel, queue Default: queue
ButtonDownFcn	Defines a callback routine that executes when a mouse button is pressed on over the text	Values: string or function handle Default: '' (empty string)
CreateFcn	Defines a callback routine that executes when an text is created	Values: string or function handle Default: '' (empty string)
DeleteFcn	Defines a callback routine that executes when the text is deleted (via close or delete)	Values: string or function handle Default: '' (empty string)
Interruptible	Determines if callback routine can be interrupted	Values: on, off Default: on (can be interrupted)
UIContextMenu	Associates a context menu with the text	Values: handle of a uicontextmenu

texlabel

Text Properties