Main Content

Simulink.Annotation

创建并指定文本注释、图像注释和区域注释的属性

说明

注释是一种视觉元素,可用来为模型添加描述性说明和注解。您可以通过编程方式将它们作为 Simulink.Annotation 对象进行访问和修改。

要获取一个现有的 Simulink.Annotation 对象,请选择注释。然后使用getCurrentAnnotation 函数。

创建对象

您可以通过多种方式创建 Simulink.Annotation 对象。

  • 要以编程方式创建 Annotation 对象,请使用本页所述的 Simulink.Annotation 函数。

  • 要以交互方式创建 Annotation 对象,请参阅Annotate Models

描述

示例

a = Simulink.Annotation(sys,name) 在指定的系统或子系统中创建具有指定名称和默认属性的注释。

示例

a = Simulink.Annotation(path,Name,Value) 使用名称-值对组创建具有指定的属性的注释。例如,Simulink.Annotation('model/annotation','BackgroundColor','yellow') 创建一个具有黄色背景的注释。您可以指定多个名称-值对组。将每个属性名称括在引号中。

输入参量

全部展开

要包含注释的系统或子系统,指定为字符向量或字符串标量。

数据类型: char | string

新注释的名称,指定为字符向量。

数据类型: char

新注释的路径,指定为由系统名称和注释名称组成字符向量或字符串标量。

示例: Simulink.Annotation('model/annotation')

数据类型: char | string

属性

全部展开

交互

选择或取消选择注释的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 选择注释。

  • 'off' - 取消选择注释。

数据类型: logical | char | string

文本

注释的文本,指定为字符向量或字符串标量。

Text 相同。

数据类型: char | string

注释的文本,指定为字符向量或字符串标量。

Name 相同。

数据类型: char | string

格式化文本样式的选项,对于纯文本指定为 'off',对于富文本指定为 'rich',对于包含 LaTeX 命令的文本指定为 'tex'。当使用格式设置工具栏设置纯文本注释的格式时,注释将变为富文本注释。

呈现 TeX 标记的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 呈现 TeX 标记。

  • 'off' - 不呈现 TeX 标记。

生成标记注释的选项,指定为 'model''markup'

注意

'ShowMarkup' 模型参数设置为 'on' 以显示标记注释,或设置为 'off' 以隐藏标记注释。

字体

此属性仅影响纯文本注释。

字体名称,指定为字符向量或字符串标量。默认值 'auto' 使用在“字体样式”对话框中为注释指定的默认字体。要打开“字体样式”对话框,请在格式选项卡上,点击字体属性按钮箭头,然后点击模型字体

数据类型: char | string

此属性仅影响纯文本注释。

字体大小,以磅为单位,指定为数值标量。默认值 -1 使用“字体样式”对话框中指定的注释的默认字体大小。要打开“字体样式”对话框,请在格式选项卡上,点击字体属性按钮箭头,然后点击模型字体

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

此属性仅影响纯文本注释。

字符粗细,指定为下表中列出的值之一。

描述
'auto' 在“字体样式”对话框中指定的注释的默认粗细。要打开“字体样式”对话框,请在格式选项卡上,点击字体属性按钮箭头,然后点击模型字体
'normal'普通字体。
'bold'加粗字体。
'light'不推荐。
'demi'不推荐。

此属性仅影响纯文本注释。

注释字体的角度,指定为下表中列出的值之一。

描述
'auto' 在“字体样式”对话框中为注释指定的默认字体角度。要打开“字体样式”对话框,请在格式选项卡上,点击字体属性按钮箭头,然后点击模型字体
'normal'普通字体。
'italic'倾斜字体。
'oblique'伪斜体(通常与斜体相同)。

颜色和效果

注释的背景色,指定为下表中列出的值之一。

描述
'automatic'透明
'black'黑色
'white'白色
'red'红色
'green'绿色
'blue'蓝色
'cyan'青蓝色
'magenta'品红色
'yellow'黄色
'gray'灰色
'lightBlue'淡蓝
'orange'橙色
'darkGreen'深绿
RGB 值组成的数组,指定为 '[r,g,b]',其中 rgb 是颜色的红色、绿色和蓝色值,归一化到范围 0.01.0完全不透明的自定义颜色

数据类型: char | string

注释的前景颜色,指定为下表中列出的值之一。

描述
'black'黑色
'white'白色
'red'红色
'green'绿色
'blue'蓝色
'cyan'青蓝色
'magenta'品红色
'yellow'黄色
'gray'灰色
'lightBlue'淡蓝
'orange'橙色
'darkGreen'深绿
RGB 值组成的数组,指定为 '[r,g,b]',其中 rgb 是颜色的红色、绿色和蓝色值,归一化到范围 0.01.0完全不透明的自定义颜色

数据类型: char | string

显示阴影的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 显示阴影。

  • 'off' - 不显示阴影。

大小和位置

控制注释高度的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 注释不会调整大小以适应文本更改。可见文本可能会截断。

  • 'off' - 注释会自动调整大小以适应文本更改。

以交互方式调整注释大小会将此参数设置为 'on'

标注的垂直锚点,指定为下表中列出的值之一。

描述
'top'

在注释增大或缩小时,注释的顶部保持不变。

'middle'

在注释增大或缩小时,注释的中间位置保持不变。

'bottom'

在注释增大或缩小时,注释的底部保持不变。

'cap'

不推荐。

'baseline'

不推荐。

依存关系

要启用 VerticalAlignment,请将 FixedHeight 设置为 'off'

控制注释宽度的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 注释不会调整大小以适应文本更改。当文本无法容纳在注释边界内时,它会换行到下一行。

  • 'off' - 注释会自动调整大小以适应文本更改。

以交互方式调整注释大小会将此参数设置为 'on'

注释内文本的水平对齐,指定为下表中列出的值之一。

结果
'left' 注释中的文本左对齐。
'center'注释中的文本居中。
'right'注释中的文本右对齐。

文本边界和注释边框之间的空间,指定为 1×4 数组。该数组提供文本和注释的每个边之间的空间。数组元素按顺序指定左侧、顶部、右侧和底部的空间 ([left top right bottom])。

支持的坐标在 -1073740824 和 1073740823 之间(包括二者)。

数据类型: double

注释的位置,指定为 1×4 数组。该数组以像素为单位提供注释边的位置。数组的元素按顺序指定左侧、顶部、右侧和底部的位置 ([left top right bottom])。

原点是尚未调整画布大小时 Simulink® 编辑器画布的左上角位置。位于原点右侧和下方的值为正值。位于原点左侧和上方的值为负值。支持的坐标在 -1073740824 和 1073740823 之间(包括二者)。

依存关系

  • 要以编程方式移动右侧的位置而不对左侧移动相同的量,必须将 FixedWidth 设置为 'on'

  • 要以编程方式移动底部的位置而不对顶部移动相同的量,必须将 FixedHeight 设置为 'on'

数据类型: double

元数据

注释的描述,指定为字符向量或字符串标量。

数据类型: char | string

注释的文本标记,指定为字符向量或字符串标量。

数据类型: char | string

要与注释相关联的数据。

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

回调函数

点击注释时执行的 MATLAB 代码,指定为字符向量或字符串标量。

有关详细信息,请参阅 Add Hyperlinks to Annotations

依存关系

UseDisplayTextAsClickCallback 设置为 'on' 时,ClickFcn 值与 NameText 值匹配。

数据类型: char | string

使用文本作为点击函数的选项,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 点击注释将运行由 Text 指定的注释文本,该文本解释为有效的 MATLAB 表达式。

  • 'off' - 点击注释将运行 ClickFcn 指定的函数(如果可用)。如果未指定点击函数,则点击注释不会运行函数。

有关详细信息,请参阅 Add Hyperlinks to Annotations

加载包含注释的模型时要执行的 MATLAB 代码,指定为字符向量或字符串标量。有关详细信息,请参阅 Add Hyperlinks to Annotations

数据类型: char | string

在以编程方式删除注释之前要执行的 MATLAB 代码,指定为字符向量或字符串标量。

有关详细信息,请参阅 Add Hyperlinks to Annotations

数据类型: char | string

信息(只读)

此 属性 为只读。

注释类型,以 'annotation' 形式返回。

此 属性 为只读。

注释的类型,对于基于文本的说明,指定为 'note_annotation',对于区域,指定为 'area_annotation',对于图像,指定为 'image_annotation'

要以编程方式创建区域,请参阅Create Area

要以编程方式创建仅包含图像的注释,请参阅setImage

此 属性 为只读。

检查注释是否为仅包含图像的注释,以 'on''off' 形式返回。

此 属性 为只读。

注释中的文本,不带格式,以向量形式返回。

此 属性 为只读。

注释句柄,以双精度形式返回。

此 属性 为只读。

包含注释的系统,以字符向量形式返回。

此 属性 为只读。

注释的路径,以字符向量形式返回。

对象函数

view查找注释
setImageSpecify image to display as annotation
deleteDelete annotation

示例

全部折叠

此示例说明如何以编程方式创建、修改和查看注释。

打开一个新模型。

open_system(new_system)

使用 Simulink.Annotation 函数创建一个具有默认属性的注释。

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

创建注释后,使用圆点表示法来设置属性值。例如,将 18 磅字体和黄色背景应用于注释。

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

要查看并短暂突出显示新注释,请使用 view 函数。

view(a)

创建名为 CreateAnnotationModel 的新模型并将其打开。

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

使用 Simulink.Annotation 函数创建一个字体大小为 18 磅、背景为浅蓝色的注释。

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

提示

  • 要以编程方式修改现有注释,请使用 find_system 函数获取注释句柄,然后使用 get_param 函数获取对象。例如:

    h = find_system(gcs,'FindAll','on','Type','annotation');
    a1 = get_param(h(1),'Object');
  • 如果一个注释调用了当前正在执行的回调函数,请使用 getCallbackAnnotation 来确定是哪个注释调用了它。该函数返回对应的 Annotation 对象。如果在一个包含多个回调调用的单独 MATLAB 文件中编写回调函数,此函数也很有用。

替代功能

您也可以使用 add_block 函数创建注释。例如:

  • add_block('built-in/Note','model/This is a note.','BackgroundColor','yellow') 创建具有黄色背景的注释。

  • add_block('built-in/Area','model/This is an Area.','Position',[120,100,230,200]) 在指定位置创建区域注释。

要以交互方式创建注释并编辑其属性,请参阅Annotate Models

版本历史记录

在 R2006a 之前推出