Main Content

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.

Description

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

example

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.

example

Input Arguments

expand all

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

Data Types: char | string

Name of new annotation, specified as a character vector.

Data Types: char

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

expand all

Interaction

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

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

Same as Text.

Data Types: char | string

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

Same as Name.

Data Types: char | string

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.

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.

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

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

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

This property affects only plain text annotations.

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

ValueDescription
'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.

This property affects only plain text annotations.

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

ValueDescription
'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

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

ValueDescription
'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

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

ValueDescription
'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

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

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'.

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

ValueDescription
'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'.

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'.

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

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

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

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 of annotation, specified as a character vector or string scalar.

Data Types: char | string

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

Data Types: char | string

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

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

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.

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

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)

This property is read-only.

Annotation type, returned as '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.

This property is read-only.

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

This property is read-only.

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

This property is read-only.

Annotation handle, returned as a double.

This property is read-only.

System that contains annotation, returned as a character vector.

This property is read-only.

Path to annotation, returned as a character vector.

Object Functions

viewFind annotation
setImageSpecify image to display as annotation
deleteDelete annotation

Examples

collapse all

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