Simulink.Annotation

Create and specify properties of text, image, and area annotations

Description

Annotations are visual elements that you can use to add descriptive notes and callouts to your model. You can programmatically access and modify them as Simulink.Annotation objects.

To get an existing Simulink.Annotation object, select the annotation. Then, use the getCurrentAnnotation function.

Creation

You can create a Simulink.Annotation object in multiple ways.

• To programmatically create an Annotation object, use the Simulink.Annotation function described on this page.

• To interactively create an Annotation object, see Annotate Models.

Syntax

a = Simulink.Annotation(sys,name)

a = Simulink.Annotation(path,Name,Value)

Description

a = Simulink.Annotation(sys,name) creates an annotation with the specified name and default properties in the specified system or subsystem.

a = Simulink.Annotation(path,Name,Value) creates an annotation with properties specified using name-value pairs. For example, Simulink.Annotation('model/annotation','BackgroundColor','yellow') creates an annotation with a yellow background. You can specify multiple name-value pairs. Enclose each property name in quotes.

Input Arguments

sys — System or subsystem to contain annotation

character vector | string scalar

System or subsystem to contain annotation, specified as a character vector or string scalar.

Data Types: char | string

name — Name of new annotation

character vector

Name of new annotation, specified as a character vector.

Data Types: char

path — Path to new annotation

character vector | string scalar

Path to new annotation, specified as a character vector or string scalar composed of the system name and the annotation name.

Example: Simulink.Annotation('model/annotation')

Data Types: char | string

Properties

Interaction

Selected — Option to select annotation

'off' (default) | on/off logical value

Option to select or deselect the annotation, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — Select annotation.

• 'off' — Remove selection from annotation.

Data Types: logical | char | string

Text

Name — Text of annotation

character vector | string scalar

Text of annotation, specified as a character vector or string scalar.

Same as Text.

Data Types: char | string

Text — Text of annotation

character vector | string scalar

Text of annotation, specified as a character vector or string scalar.

Same as Name.

Data Types: char | string

Interpreter — Option to format text style

'off' (default) | 'rich' | 'tex'

Option to format text style, specified as 'off' for plain text, 'rich' for rich text, or 'tex' for text that contains LaTeX commands. When you format a plain text annotation using the formatting toolbar, the annotation becomes a rich text annotation.

TeXMode — Option to render TeX markup

'off' (default) | on/off logical value

Option to render TeX markup, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — Render TeX markup.

• 'off' — Do not render TeX markup.

MarkupType — Option to make markup annotation

'model' (default) | 'markup'

Option to make markup annotation, specified as 'model' or 'markup'.

Note

Set the 'ShowMarkup' model parameter to 'on' to show markup annotations or 'off' to hide markup annotations.

Font

FontName — Font name

'auto' (default) | character vector | string scalar

This property affects only plain text annotations.

Font name, specified as a character vector or string scalar. The default value, 'auto', uses the default font specified for annotations in the Font Styles dialog box. To open the Font Styles dialog box, on the Format tab, click the Font Properties button arrow, then click Fonts for Model.

Data Types: char | string

FontSize — Font size, in points

-1 (default) | numeric scalar

This property affects only plain text annotations.

Font size, in points, specified as a numeric scalar. The default value, -1, uses the default font size for annotations specified in the Font Styles dialog box. To open the Font Styles dialog box, on the Format tab, click the Font Properties button arrow, then click Fonts for Model.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

FontWeight — Character thickness

'auto' (default) | 'normal' | 'bold' | 'light' | 'demi'

This property affects only plain text annotations.

Character thickness, specified as one of the values listed in the table.

Value	Description
'auto'	The default weight for annotations specified in the Font Styles dialog box. To open the Font Styles dialog box, on the Format tab, click the Font Properties button arrow, then click Fonts for Model.
'normal'	Normal font weight.
'bold'	Bold font weight.
'light'	Not recommended.
'demi'	Not recommended.

FontAngle — Angle of annotation font

'auto' (default) | 'normal' | 'italic' | 'oblique'

This property affects only plain text annotations.

Angle of annotation font, specified as one of the values listed in the table.

Value	Description
'auto'	The default font angle specified for annotations in the Font Styles dialog box. To open the Font Styles dialog box, on the Format tab, click the Font Properties button arrow, then click Fonts for Model.
'normal'	Normal font.
'italic'	Italic font.
'oblique'	Oblique font (usually the same as italic font).

Colors and Effects

BackgroundColor — Background color of annotation

'white' (default) | RGB value array | 'automatic' (transparent) | 'black' | 'red' | 'green' | 'blue' | ...

Background color of annotation, specified as one of the values listed in this table.

Value	Description
'automatic'	Transparent
'black'	Black
'white'	White
'red'	Red
'green'	Green
'blue'	Blue
'cyan'	Cyan
'magenta'	Magenta
'yellow'	Yellow
'gray'	Gray
'lightBlue'	Light blue
'orange'	Orange
'darkGreen'	Dark green
RGB value array, specified as '[r,g,b]' where r, g, and b are the red, green, and blue values of the color normalized to the range 0.0 to 1.0.	Fully opaque custom color

Data Types: char | string

ForegroundColor — Foreground color of annotation

'black' (default) | RGB value array | 'white' | 'red' | 'green' | 'blue' | ...

Foreground color of annotation, specified as one of the values listed in this table.

Value	Description
'black'	Black
'white'	White
'red'	Red
'green'	Green
'blue'	Blue
'cyan'	Cyan
'magenta'	Magenta
'yellow'	Yellow
'gray'	Gray
'lightBlue'	Light blue
'orange'	Orange
'darkGreen'	Dark green
RGB value array, specified as '[r,g,b]' where r, g, and b are the red, green, and blue values of the color normalized to the range 0.0 to 1.0.	Fully opaque custom color

Data Types: char | string

DropShadow — Option to display drop shadow

'off' (default) | on/off logical value

Option to display drop shadow, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — Display drop shadow.

• 'off' — Do not display drop shadow.

Size and Position

FixedHeight — Option to control annotation height

'off' (default) | on/off logical value

Option to control annotation height, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — The annotation does not resize to accommodate text changes. The visible text may be truncated.

• 'off' — The annotation automatically resizes to accommodate text changes.

Interactively resizing the annotation sets this parameter to 'on'.

VerticalAlignment — Vertical anchor point of annotation

'top' (default) | 'middle' | 'bottom' | 'cap' | 'baseline'

Vertical anchor point of annotation, specified as one of the values listed in this table.

Value	Description
'top'	The top of the annotation remains fixed as the annotation grows or shrinks.
'middle'	The middle of the annotation remains fixed as the annotation grows or shrinks.
'bottom'	The bottom of the annotation remains fixed as the annotation grows or shrinks.
'cap'	Not recommended.
'baseline'	Not recommended.

Dependencies

To enable VerticalAlignment, set FixedHeight to 'off'.

FixedWidth — Option to control annotation width

'off' (default) | on/off logical value

Option to control annotation width, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — The annotation does not resize to accommodate text changes. When text cannot fit inside the annotation bounds, it wraps onto the next line.

• 'off' — The annotation automatically resizes to accommodate text changes.

Interactively resizing the annotation sets this parameter to 'on'.

HorizontalAlignment — Horizontal alignment of text within annotation

'left' (default) | 'center' | 'right'

Horizontal alignment of text within annotation, specified as one of the values listed in the table.

Value	Result
'left'	Text in the annotation is left justified.
'center'	Text in the annotation is centered.
'right'	Text in the annotation is right justified.

InternalMargins — Space between bounding box and borders

[0 0 0 0] (default) | 1x4 array

Space between bounding box of text and borders of annotation, specified as a 1x4 array. The array provides the space between the text and each side of the annotation. The elements of the array specify the space at the left, top, right, and bottom sides in order ([left top right bottom]).

Supported coordinates are between -1073740824 and 1073740823, inclusive.

Data Types: double

Position — Location of annotation

[0 0 28 14] (default) | 1x4 array

Location of annotation, specified as a 1x4 array. The array provides the locations of the annotation sides, in pixels. The elements of the array specify the locations of the left, top, right, and bottom sides in order ([left top right bottom]).

The origin is the upper-left corner of the Simulink^® Editor canvas before any canvas resizing. Positive values are to the right of and down from the origin. Negative values are to the left of and up from the origin. Supported coordinates are between -1073740824 and 1073740823, inclusive.

Dependencies

• To programmatically move the location of the right side without moving the left side the same amount, FixedWidth must be set to 'on'.

• To programmatically move the location of the bottom side without moving the top side the same amount, FixedHeight must be set to 'on'.

Data Types: double

Metadata

Description — Description of annotation

character vector | string scalar

Description of annotation, specified as a character vector or string scalar.

Data Types: char | string

Tag — Text tag for annotation

character vector | string scalar

Text tag for annotation, specified as a character vector or string scalar.

Data Types: char | string

UserData — Data to associate with annotation

user data

Data to associate with annotation.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | table | cell | function_handle | categorical | datetime | duration | calendarDuration | fi

Callback Functions

ClickFcn — MATLAB^® code that executes when you click annotation

character vector | string scalar

MATLAB code that executes when you click annotation, specified as a character vector or string scalar.

For more information, see Add Hyperlinks to Annotations.

Dependencies

When UseDisplayTextAsClickCallback is set to 'on', the ClickFcn value matches the Name and Text value.

Data Types: char | string

UseDisplayTextAsClickCallback — Option to use text as click function

'off' (default) | on/off logical value

Option to use text as click function, specified as 'on' or 'off', or numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type OnOffSwitchState.

• 'on' — Clicking the annotation runs the annotation text specified by Text, which is interpreted as a valid MATLAB expression.

• 'off' — Clicking the annotation runs the function specified by ClickFcn, if available. If a click function is not specified, clicking the annotation does not run a function.

For more information, see Add Hyperlinks to Annotations.

LoadFcn — MATLAB code to execute when model containing annotation loads

character vector | string scalar

MATLAB code to execute when model containing annotation is loaded, specified as a character vector or string scalar. For more information, see Add Hyperlinks to Annotations.

Data Types: char | string

DeleteFcn — MATLAB code to execute before programmatically deleting annotation

character vector | string scalar

MATLAB code to execute before programmatically deleting annotation, specified as a character vector or string scalar.

For more information, see Add Hyperlinks to Annotations.

Data Types: char | string

Information (Read-Only)

Type — Annotation type

'annotation' (default)

This property is read-only.

Annotation type, returned as 'annotation'.

AnnotationType — Type of annotation

'note_annotation' | 'area_annotation' | 'image_annotation'

This property is read-only.

Type of annotation, specified as 'note_annotation' for a text-based note, 'area_annotation' for an area, or 'image_annotation' for an image.

To programmatically create an area, see Create Area.

To programmatically create an image-only annotation, see setImage.

IsImage — Check whether annotation is image-only annotation

'off' (default) | 'on'

This property is read-only.

Check whether annotation is an image-only annotation, returned as 'on' or 'off'.

PlainText — Text in annotation

vector

This property is read-only.

Text in annotation, without formatting, returned as a vector.

Handle — Annotation handle

double

This property is read-only.

Annotation handle, returned as a double.

Parent — System that contains annotation

character vector

This property is read-only.

System that contains annotation, returned as a character vector.

Path — Path to annotation

character vector

This property is read-only.

Path to annotation, returned as a character vector.

Object Functions

view	Find annotation
setImage	Specify image to display as annotation
delete	Delete annotation

Examples

Create Annotation

This example shows how to create, modify, and view an annotation programmatically.

Open a new model.

open_system(new_system)

Create an annotation with default properties using the Simulink.Annotation function.

a = Simulink.Annotation(gcs,'This is an annotation.');

After creating the annotation, use dot notation to set property values. For example, apply an 18-point font and yellow background to the annotation.

a.FontSize = 18;
a.BackgroundColor = 'yellow';

To view and briefly highlight the new annotation, use the view function.

view(a)

Create Annotation with Custom Properties

Create and open a new model named CreateAnnotationModel.

new_system('CreateAnnotationModel')
open_system('CreateAnnotationModel')

Use the Simulink.Annotation function to create an annotation with an 18-point font size and light blue background.

a = Simulink.Annotation(...
    'CreateAnnotationModel/This is an annotation.', ...
    'FontSize',18, ...
    'BackgroundColor','lightblue');

Tips

• To programmatically modify an existing annotation, use the find_system function to get the annotation handle, then use the get_param function to get the object. For example:

  h = find_system(gcs,'FindAll','on','Type','annotation');
  a1 = get_param(h(1),'Object');

• If an annotation invoked a currently executing callback function, use the getCallbackAnnotation to determine which annotation invoked it. The function returns the corresponding Annotation object. This function is also useful if you write a callback function in a separate MATLAB file that contains multiple callback calls.

Alternative Functionality

You also can create annotations using the add_block function. For example:

• add_block('built-in/Note','model/This is a note.','BackgroundColor','yellow') creates a note annotation with a yellow background.

• add_block('built-in/Area','model/This is an Area.','Position',[120,100,230,200]) creates an area annotation at the specified position.

To interactively create an annotation and edit its properties, see Annotate Models.

Version History

Introduced before R2006a