Annotate

Create an annotation that is pinned to the axes of a graph.

Annotate Create an annotation that is pinned to the axes of a graph.

Usage:

OBJ = Annotate(AX, TYPE, X, Y)

OBJ = Annotate(AX, TYPE, X, Y, 'PropertyName', Value, ...)

Inputs:

AX <1x1 axes handle>

- Handle to axes where annotation is to be pinned

TYPE <character array>

- Type of annotation to create

- 'line', 'arrow', 'doublearrow', 'textarrow',

'rectangle', 'ellipse', or 'textbox'

X <1x2 or 2x1 numeric vector>

- Annotation X position in axes data coordinates

- Must lie within the visible axes limits

- For annotation types 'line', 'arrow', 'doublearrow', and 'textarrow', X(1)

specifies the tail end of the arrow and X(2) specifies the tip of the arrow head

- For annotation types 'rectangle', 'ellipse', and 'textbox', X(1)

specifies the left edge/extent and X(2) specifies the right edge/extent

Y <1x2 or 2x1 numeric vector>

- Annotation Y position in axes data coordinates

- Must lie within the visible axes limits

- For annotation types 'line', 'arrow', 'doublearrow', and 'textarrow', Y(1)

specifies the tail end of the arrow and Y(2) specifies the tip of the arrow head

- For annotation types 'rectangle', 'ellipse', and 'textbox', Y(1)

specifies the bottom edge/extent and Y(2) specifies the top edge/extent

Optional property name/value pairs can be specified to control the

appearance of the annotation object. See 'annotation' documentation

and property pages for each annotation type for more details.

Outputs:

OBJ <1x1 Annotate object handle>

- The Annotate object provides the following properties for

interaction with the annotation object.

* 'Position' allows for setting/getting the annotation object

position in axes data coordinates defined as [X(1),X(2),Y(1),Y(2)].

Note, rounding errors can occur.

* 'Primitive' is the handle to the annotation object, which allows

for further customization of its appearance.

Description:

Annotate creates an annotation object of type TYPE which is automatically

pinned to the axes with handle AX at the position specified by vectors

X and Y in axes data coordinates.

A UIContextMenu is attached to the annotation object which replicates the

standard annotation customizations (color, line width, line style, etc.),

normally accessed through edit plot mode, without having to enter edit plot

mode. The UIContextMenu also provides move/resize and delete functionality.

Annotate.ButtonDownFcn(SRC, EVNT, TYPE) is a static method available to

be executed as a button down callback function. It interactively

creates an annotation object of type TYPE which is automatically pinned

to the axes ancestor of handle SRC.

Annotate.ButtonDownFcn(___, 'PropertyName', Value, ...) interactively

creates the annotation object and applies the settings specified by the

property name/value pairs.

The property 'ParentAnnotation' is added to the annotation object so

its "parent annotation" Annotate object, constructed with the button

down callback function, can be recovered and used to set/get the

annotation position in axes data coordinates.

Examples:

% programmatic placement through constructor

figure; x=0:0.1:6; y=sin(x); h=plot(x,y);

obj1 = Annotate(gca, 'ellipse', [1.5,2.5], [-0.8,0.4]);

obj2 = Annotate(gca, 'arrow', [x(1),x(10)]+0.2, [y(1),y(10)]);

obj3 = Annotate(gca, 'doublearrow', [4,3], [-0.6,0.4], 'linestyle', '--');

obj4 = Annotate(gca, 'line', [1,4], [0.6,0.6], 'color', 'r');

obj4.Position = [0.5,3.5,0.8,0.8]; % set new axes data coordinate position

obj5 = Annotate(gca, 'textbox', [2.5,4.5], [0.8,0.9], 'backgroundcolor', 'none', 'string', 'example textbox');

obj5.Primitive.EdgeColor = 'none'; obj5.Primitive.FontWeight = 'bold';

obj6 = Annotate(gca, 'textarrow', [4.5,x(55)], [0.2,y(55)], 'string', {'Programmatically','input text'});

% interactive placement through button down callback function

figure; x=0:0.1:6; y=sin(x); h=plot(x,y);

set(gca, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'textarrow'}); % manually input text, hit escape when done

set(h, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'rectangle'}); % can be set for axes child as well

% once created with the button down callback function, a primitive annotation could be set as the current object

% and a new axes data coordinate position could be specified with the following code

% obj = get(gco,'ParentAnnotation'); obj.Position = [1 3 0.0 0.5];

% support for multiple uipanels, tiled chart layouts, and axes

figure; x=0:0.1:6; y=sin(x); p0=uipanel(gcf,'position',[0,0,1,1]);

p1=uipanel(p0,'position',[0.0,0.0,0.5,1.0]); t1=tiledlayout(p1,2,1); ax1=nexttile(t1,2); plot(ax1,x,y,'r');

p2=uipanel(p0,'position',[0.5,0.0,0.5,1.0]); t2=tiledlayout(p2,2,1); ax2=nexttile(t2,1,[2,1]); plot(ax2,x,y,'b');

obj1 = Annotate(ax1, 'ellipse', [1.5,2.5], [-0.8,0.4]);

obj2 = Annotate(ax2, 'arrow', [x(1),x(10)]+0.2, [y(1),y(10)]);

set(ax1, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'arrow', 'color', 'b'});

set(ax2, 'ButtonDownFcn', {@Annotate.ButtonDownFcn, 'rectangle', 'color', 'r'});

References:

http://undocumentedmatlab.com/blog/pinning-annotations-to-graphs

http://undocumentedmatlab.com/blog/inactive-control-tooltips-event-chaining

http://undocumentedmatlab.com/blog/adding-dynamic-properties-to-graphic-handles

http://undocumentedmatlab.com/blog/ishghandle-undocumented-input-parameter