Simulink.Annotation

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

全页展开

说明

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

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

创建对象

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

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

  • 要以交互方式创建 Annotation 对象，请参阅为模型添加注解。

语法

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

描述

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]'，其中 r、g 和 b 是颜色的红色、绿色和蓝色值，归一化到范围 0.0 到 1.0。完全不透明的自定义颜色

数据类型: char | string

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

值描述
'black'黑色
'white'白色
'red'红色
'green'绿色
'blue'蓝色
'cyan'青蓝色
'magenta'品红色
'yellow'黄色
'gray'灰色
'lightBlue'淡蓝
'orange'橙色
'darkGreen'深绿
RGB 值组成的数组，指定为 '[r,g,b]'，其中 r、g 和 b 是颜色的红色、绿色和蓝色值，归一化到范围 0.0 到 1.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 代码，指定为字符向量或字符串标量。

有关详细信息，请参阅 向注解添加超链接。

依赖关系

当 UseDisplayTextAsClickCallback 设置为 'on' 时，ClickFcn 值与 Name 和 Text 值匹配。

数据类型: char | string

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

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

  • 'off' - 点击注解将运行 ClickFcn 指定的函数（如果可用）。如果未指定点击函数，则点击注解不会运行函数。

有关详细信息，请参阅 向注解添加超链接。

加载包含注解的模型时要执行的 MATLAB 代码，指定为字符向量或字符串标量。有关详细信息，请参阅 向注解添加超链接。

数据类型: char | string

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

有关详细信息，请参阅 向注解添加超链接。

数据类型: 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.');

Annotation with the text "This is an annotation"

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

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

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

view(a)

The annotation with the text "This is an annotation" is highlighted in yellow.

打开实时脚本

创建名为 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]) 在指定位置创建区域注解。

要以交互方式创建注解并编辑其属性，请参阅为模型添加注解。

版本历史记录

在 R2006a 之前推出

另请参阅

| |

主题