# 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')

marks two curves so you can easily distinguish them.

## See Also

    gtext, int2str, num2str, plot, title, xlabel

(c) Copyright 1994 by The MathWorks, Inc.