text

Purpose

Add text to current plot by creating text object.

Synopsis

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

Description

text is both a high-level graphics command for adding text to a plot, and a low-level graphics function for creating text objects.

Text objects are children of axes. text is an object creation function that accepts property name/property value pairs as input arguments. These properties, which control various aspects of the text object, are described under "Object Properties." You can also set and query property values after creating the object using the set and get commands.

text(x,y,'text') adds the string in the quotes to the location identified by the point (x,y) to the current axes. Specify the point (x,y) in units of the current plot's data. If x and y are vectors, text writes the string at all locations defined by the list of points. h is the handle of the created text object. The x, y pair can be followed by property name/property value ('PropertyName','PropertyValue') pairs to specify additional text properties.

If the text string is an array that is the same length as x and y, text writes the corresponding row of the text array at each point specified by x and y.

text(x,y,z,'text') adds text in three-dimensional coordinates. The x, y, z triple for three-dimensional can be followed by property name/property value ('PropertyName','PropertyValue') pairs to specify additional text properties.

text('PropertyName','PropertyValue'....) omits the x, y, pair (x, y, z triple for three-dimensional) entirely and specifies all properties using property name/property value pairs.

h = text(..) returns a handle to a text object.

Object Properties

This section lists property names along with the type of values each accepts.

ButtonDownFcn: Callback string, object selection.

Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the eval function to execute the specified function. Initially the empty matrix.

Children: Children of text.

Always the empty matrix; text objects have no children.

Clipping: Clipping mode.

on (Default.) Any portion of the text outside the axes rectangle is not displayed.

off Text object is not clipped.

Color: Text color.

A three-element RGB vector or one of MATLAB's predefined names, specifying the text color. The default text color is white. See the ColorSpec reference page for more information on specifying color.

EraseMode: Erase mode.

This property controls the technique MATLAB uses to draw and erase text objects. This property is useful in creating animated sequences, where control of individual object redraw is necessary to improve performance and obtain the desired effect.

normal (Default.) Redraws the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.

none The text is not erased when it is moved or destroyed.

xor The text is drawn and erased by performing an exclusive OR (XOR) with the color of the screen beneath it. When the text is erased, it does not damage the objects beneath it. Text objects are dependent on the color of the screen beneath them, however, and are correctly colored only when over the figure background color.

background Text is erased by drawing it in the figure's background color. This damages objects that are behind the erased text, but text objects are always properly colored.

Extent: Text extent rectangle.

A four-element read-only vector, [left,bottom,width,height], that defines the size and position of the text string. left and bottom are the distance from the lower-left corner of the figure window to the lower-left corner of the rectangle. width and height are the dimensions of the text rectangle. All measurements are in units specified by the Units property.

FontAngle: Italics for text object.

normal (Default.) Regular font angle.

italic Italics.

oblique Italics on some systems.

See the MATLAB Release Notes for more details on the FontAngle property.

FontName: Font family.

A string specifying the name of the font to use for the text object. To display and print properly, this must be a font that your system supports. The default font is Helvetica.

FontSize: Font point size.

An integer specifying the font size, in points, to use for text. The default point size is 12.

FontWeight: Bolding for text object.

normal (Default.) Regular font weight.

bold Bold weight.

HorizontalAlignment: Horizontal text alignment.

left (Default.) Text is left-justified with respect to its Position.

center Text is centered with respect to its Position.

right Text is right-justified with respect to its Position.

Interruptible: Callback interruptibility.

yes The callback specified by ButtonDownFcn is interruptible by other callbacks.

no (Default.) The ButtonDownFcn callback is not interruptible.

Parent: Handle of the text's parent object.

A read-only property that contains the handle of the text's parent object. The parent of a text object is the axes in which it is displayed.

Position: Location of text.

A two- or three-element vector, [x y (z)], that specifies the location of the text in three dimensions. If you omit the z value, it defaults to 0. All measurements are in units specified by the Units property. Initial value is [0 0 0].

Rotation: Text orientation.

One of seven predefined orientations: 0, ą90, ą180, or ą270. These seven possibilities define only four different orientations. For example, -90 and +270 produce the same result. On some systems, MATLAB supports arbitrary rotation angles. The default rotation is 0.

String: Text string.

The text string that is displayed.

Type: Type of graphics object.

A read-only string; always 'text' for a text object.

Units: Unit of measurement for screen display.

data (Default.) Data units of the parent axes.

pixels Screen pixels.

normalized Normalized coordinates, where the lower-left corner of the axes maps to (0,0) and the upper-right corner to (1.0,1.0).

inches Inches.

cent Centimeters.

points Points. Each point is equivalent to 1/72 of an inch.

This property affects the Extent and Position properties. All units are measured from the lower-left corner of the window. If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.

UserData: User-specified data.

Any matrix you want to associate with the text object. The object does not use this data, but you can retrieve it using the get command.

VerticalAlignment: Vertical text alignment.

top String is placed at the top of the specified y-position.

cap Font's capital letter height is placed at the specified y-position.

middle (Default.) String is placed at the middle of the specified y-position.

baseline Font's baseline is placed at the specified y-position.

bottom String is placed at the bottom of the specified y-position.

Visible: Text visibility.

on (Default.) Text is visible on the screen.

off Text is not visible on the screen.

Examples

The statements

plot([1 5 10],[1 10 20],'x')
text(5,10,' Action point')

annotate the point at (5,10) with the string Action point, while

plot(x1,y1,x2,y2)
text(x1,y1,'1'), text(x2,y2,'2')