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 theSimulink.Annotation
function described on this page.To interactively create an
Annotation
object, see Annotate Models.
Description
creates an annotation with properties specified using name-value pairs. For example,
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.
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 byText
, which is interpreted as a valid MATLAB expression.'off'
— Clicking the annotation runs the function specified byClickFcn
, 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
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 theget_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 correspondingAnnotation
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
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)