MATLAB Function Reference    
text

Create text object in current axes

Syntax

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

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,

is equivalent to:

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,

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

The statement,

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.

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
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
Default: '' (empty string)
CreateFcn
Defines a callback routine that executes when an text is created
Values: string
Default: '' (empty string)
DeleteFcn
Defines a callback routine that executes when the text is deleted (via close or delete)
Values: string
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