MATLAB Function Reference

annotation - Create annotation objects

GUI Alternatives

Create several types of annotations with the Figure Palette and modify annotations with the Property Editor, components of the plotting tools. Directly manipulate annotations in plot edit mode. For details, see How to Annotate Graphs and Working in Plot Edit Mode in the MATLAB^® Graphics documentation.

Syntax

annotation(annotation_type) annotation('line',x,y) annotation('arrow',x,y) annotation('doublearrow',x,y) annotation('textarrow',x,y) annotation('textbox',[x y w h]) annotation('ellipse',[x y w h]) annotation('rectangle',[x y w h]) annotation(figure_handle,...) annotation(...,'PropertyName',PropertyValue,...) anno_obj_handle = annotation(...)

Description

annotation(annotation_type) creates the specified annotation type using default values for all properties. annotation_type can be one of the following strings:

'line'
'arrow'
'doublearrow' (two-headed arrow),
'textarrow' (arrow with attached text box),
'textbox'
'ellipse'
'rectangle'

annotation('line',x,y) creates a line annotation object that extends from the point defined by x(1),y(1) to the point defined by x(2),y(2), specified in normalized figure units.

annotation('arrow',x,y) creates an arrow annotation object that extends from the point defined by x(1),y(1) to the point defined by x(2),y(2), specified in normalized figure units.

annotation('doublearrow',x,y) creates a two-headed annotation object that extends from the point defined by x(1),y(1) to the point defined by x(2),y(2), specified in normalized figure units.

annotation('textarrow',x,y) creates a textarrow annotation object that extends from the point defined by x(1),y(1) to the point defined by x(2),y(2), specified in normalized figure units. The tail end of the arrow is attached to an editable text box.

annotation('textbox',[x y w h]) creates an editable text box annotation with its lower left corner at the point x,y, a width w, and a height h, specified in normalized figure units. Specify x, y, w, and h in a single vector.

To type in the text box, enable plot edit mode (plotedit) and double-click within the box.

annotation('ellipse',[x y w h]) creates an ellipse annotation with the lower left corner of the bounding rectangle at the point x,y, a width w, and a height h, specified in normalized figure units. Specify x, y, w, and h in a single vector.

annotation('rectangle',[x y w h]) creates a rectangle annotation with the lower left corner of the rectangle at the point x,y, a width w, and a height h, specified in normalized figure units. Specify x, y, w, and h in a single vector.

annotation(figure_handle,...) creates the annotation in the specified figure.

annotation(...,'PropertyName',PropertyValue,...) creates the annotation and sets the specified properties to the specified values.

anno_obj_handle = annotation(...) returns the handle to the annotation object that is created.

Annotation Layer

All annotation objects are displayed in an overlay axes that covers the figure. This layer is designed to display only annotation objects. You should not parent objects to this axes nor set any properties of this axes. See the See Also section for information on the properties of annotation objects that you can set.

Objects in the Plotting Axes

You can create lines, text, rectangles, and ellipses in data coordinates in the axes of a graph using the line, text, and rectangle functions. These objects are not placed in the annotation axes and must be located inside their parent axes.

Deleting Annotations

Existing annotations persist on a plot when you replace its data. This might not be what you want to do. If it is not, or if you want to remove annotation objects for any reason, you can do so manually, or sometimes programmatically, in several ways:

To manually delete, click the Edit Plot tool or invoke plottools, select the annotation(s) you want to remove, and do one of the following:
- Press the Delete key.
- Press the Backspace key.
- Select Clear from the Edit menu.
- Select Delete from the context menu (one annotation at a time).
If you obtained a handle for the annotation when you created it, use the delete function:
```
delete(anno_obj_handle)
```
There is no reliable way to obtain handles for annotations from a figure's property set; you must keep track of them yourself.
To delete all annotations at once (as well as all plot contents), type
```
clf
```

Normalized Coordinates

By default, annotation objects use normalized coordinates to specify locations within the figure. In normalized coordinates, the point 0,0 is always the lower left corner and the point 1,1 is always the upper right corner of the figure window, regardless of the figure size and proportions. Set the Units property of annotation objects to change their coordinates from normalized to inches, centimeters, points, pixels, or characters.

When their Units property is other than normalized, annotation objects have absolute positions with respect to the figure's origin, and fixed sizes. Therefore, they will shift position with respect to axes when you resize figures. When units are normalized, annotations shrink and grow when you resize figures; this can cause lines of text in textbox annotations to wrap. However, if you set the FontUnits property of an annotation textbox object to normalized, the text changes size rather than wraps if the textbox size changes.

You can use either the set command or the Inspector to change a selected annotation object's Units property:

set(gco,'Units','inches')  % or
inspect(gco)

For more information see Positioning Annotations in Data Space in the MATLAB Graphics documentation.