Create and specify properties of text, image, and area annotations
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.
a = Simulink.Annotation(path,Name,Value)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.
sys — System or subsystem to contain annotationSystem or subsystem to contain annotation, specified as a character vector or string scalar.
Data Types: char | string
name — Name of new annotationName of new annotation, specified as a character vector.
Data Types: char
path — Path to new annotationPath 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
Selected — Option to select annotation'off' (default) | on/off logical valueOption 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
Name — Text of annotationText of annotation, specified as a character vector or string scalar.
Same as Text.
Data Types: char | string
Text — Text of annotationText 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 valueOption 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.
FontName — Font name'auto' (default) | character vector | string scalarThis 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 scalarThis 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). |
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 valueOption 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.
FixedHeight — Option to control annotation height'off' (default) | on/off logical valueOption 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. |
To enable VerticalAlignment, set
FixedHeight to
'off'.
FixedWidth — Option to control annotation width'off' (default) | on/off logical valueOption 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 arraySpace 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 arrayLocation 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.
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
Description — Description of annotationDescription of annotation, specified as a character vector or string scalar.
Data Types: char | string
Tag — Text tag for annotationText tag for annotation, specified as a character vector or string scalar.
Data Types: char | string
UserData — Data to associate with annotationData 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
ClickFcn — MATLAB® code that executes when you click annotationMATLAB code that executes when you click annotation, specified as a character vector or string scalar.
For more information, see Associate a Click Function with an Annotation.
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 valueOption 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 Associate a Click Function with an Annotation.
LoadFcn — MATLAB code to execute when model containing annotation loadsMATLAB code to execute when model containing annotation is loaded, specified as a character vector or string scalar. For more information, see Annotation Callback Functions.
Data Types: char | string
DeleteFcn — MATLAB code to execute before programmatically deleting annotationMATLAB code to execute before programmatically deleting annotation, specified as a character vector or string scalar.
For more information, see Annotation Callback Functions.
Data Types: char | string
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 Programmatically.
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 annotationThis property is read-only.
Text in annotation, without formatting, returned as a vector.
Handle — Annotation handleThis property is read-only.
Annotation handle, returned as a double.
Parent — System that contains annotationThis property is read-only.
System that contains annotation, returned as a character vector.
Path — Path to annotationThis property is read-only.
Path to annotation, returned as a character vector.
Programmatically create, modify, and view an annotation.
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 light blue background to the annotation.
a.FontSize = 18;
a.BackgroundColor = 'lightBlue';To view and briefly highlight the new annotation, use the view function.
view(a)
Programmatically create an annotation with custom properties.
Open a model.
new_system('CreateAnnotationModel') open_system('CreateAnnotationModel')
Create an annotation with custom properties specified as comma-separated pairs consisting of the property and value by using the Simulink.Annotation function. For example, apply an 18-point font and light blue background to the annotation.
a = Simulink.Annotation('CreateAnnotationModel/This is an annotation.',... 'FontSize',18,'BackgroundColor','lightblue');
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.
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 Describe Models Using Notes and Annotations.
You have a modified version of this example. Do you want to open this example with your edits?