image thumbnail

Annotate

version 1.2.1.1 (12.4 KB) by Todd Baxter
Create an annotation that is pinned to the axes of a graph.

636 Downloads

Updated 21 Jun 2020

View License

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];

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

Cite As

Todd Baxter (2021). Annotate (https://www.mathworks.com/matlabcentral/fileexchange/63760-annotate), MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R2017a
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!