本文介绍如何使用Toolkit在工程图插入注释。在工程图插入注释功能是一个很好的二次开发进阶起点，涉及到多个函数的调用和数据的关联。

1.注释在Toolkit中数据表达方式

注释在Toolkit中设计到的数据重点包含ProDtlnote、ProDtlnotedata、ProDtlnoteline、ProDtlnotetext、ProDtlattach等类型。

ProDtlnote是一个结构体，记录了注释的类型、唯一标识等信息，其类型与ProModelitem一样，为pro_model_item结构体：

1
2
3
4
5
6
typedef struct pro_model_item
{
  ProType  type;
  int      id;
  ProMdl owner;
} ProModelitem, ProGeomitem, ProExtobj, ProFeature, ProProcstep, ProSimprep, ProExpldstate, ProLayer, ProDimension, ProDtlnote, ProDtlsyminst, ProGtol, ProCompdisp, ProDwgtable, ProNote, ProAnnotationElem, ProAnnotation, ProAnnotationPlane, ProSymbol, ProSurfFinish, ProMechItem, ProMaterialItem, ProCombstate, ProLayerstate, ProApprnstate, ProSolidBody;

ProDtlnotedata记录了注释的各种属性，包括文本、摆放方式等内容，在ProDtlnote.h中给出了定义：

1
typedef struct pro_notedata *ProDtlnotedata;

ProDtlnoteline则记录了注释中文本的信息。一个ProDtlnoteline包含多行文字，每行对应一个ProDtlnotetext对象，ProDtlnoteline使用ProArray保存多行文字信息。

1
2
typedef struct prodtl_text      *ProDtlnotetext;
typedef struct prodtl_text_line *ProDtlnoteline;

ProDtlattach则记录了ProDtlnotedata的摆放方式，包括自由、垂直与表面等各种Creo的选项。

1
typedef struct prodtl_attach_new *ProDtlattach;

上述五种数据的关系如下图所示。

图 插入注释主要涉及对象及其关系

2.代码和流程

如之前文章所述，Toolkit使用C语言采用面向过程的方式进行编程，所以按照面向对象的思想可以把上面各种数据结构的数据看成各个对象的属性形成树状结构，但具体操作起来还是采用面向过程的方式进行设置，插入注释主要涉及的函数和对象如下图所示。

图 插入注释主要涉及的函数和对象

2.1 申请和释放内存

ProDtlnotedata、ProDtlnoteline、ProDtlnotetext、ProDtlattach四个对象在使用前均需要申请内存，同时在使用完成后释放，示例代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
// 一个notedata有多个line，每个line对应多个text（行）,每个都要先申请内存，函数结束后释放
status = ProDtlnotedataAlloc(mdl, &notedata);
status = ProDtlnotelineAlloc(&line);
status = ProDtlnotetextAlloc(&text);
// ProDtlattach也需要申请内存，但需要根据具体摆放的位置和方式进行确定，在后面的代码会说明

// ……在这里添加具体操作代码

// 申请的内存必须得释放
status = ProDtlnotedataFree(notedata);
status = ProDtlnotetextFree(text);
status = ProDtlnotelineFree(line);
status = ProDtlattachFree(attachment);

之后采用倒推的方式， 一步一步设置好ProDtlnotetext、ProDtlnoteline、ProDtlattach，再设置ProDtlnotedata，最后生成ProDtlnote。

2.2 设置ProDtlnotetext

ProDtlnotetext记录了每一行的文字包括了文字内容、宽度、高度等信息，可以使用ProDtlnotetextHeightSet等相关函数对上一步申请过内存的ProDtlnotetext对象进行设定，示例代码如下：

1
2
3
4
5
6
7
8
9
10
11
ProError ProUsrSetDtlText(ProMdl mdl, ProDtlnotetext *text, double height, double width, double slant, double thickness, wchar_t *wtext)
{
  ProError status;
  // 设定一行的字体等
  status = ProDtlnotetextHeightSet(*text, height);
  status = ProDtlnotetextWidthSet(*text, width);
  status = ProDtlnotetextSlantSet(*text, slant);
  status = ProDtlnotetextThicknessSet(*text, thickness);
  status = ProDtlnotetextStringSet(*text, wtext);
  return status;
}

2.3 设置ProDtlnoteline

ProDtlnoteline中只要添加对应的ProDtlnotetext即可，如果有多行，可重复上面的操作并添加。ProDtlnoteline添加ProDtlnotetext通过ProDtlnotelineTextAdd函数完成，代码如下：

1
2
// line加一行，可以加多次代表多行
status = ProDtlnotelineTextAdd(line, text);

2.4 设置ProDtlattach

本例采用自由摆放的方式，通过鼠标点选屏幕坐标确定坐标位置。ProDtlattach可以通过ProDtlattachAlloc函数完成，注意函数参数需要提前准备好即可：

1
2
3
4
5
6
7
ProMouseButton mouse_button;
ProPoint3d pos;
status = ProMousePickGet(PRO_LEFT_BUTTON, &mouse_button, pos);
if (status != PRO_TK_NO_ERROR)
    return status;
// 设定摆放方式。这里是FREE，定位在之前的鼠标点击位置
status = ProDtlattachAlloc(PRO_DTLATTACHTYPE_FREE, NULL, pos, NULL, attachment);

2.5 设置ProDtlnotedata

ProDtlnotedata的操作主要是加入对应的ProDtlnoteline和ProDtlattach，同时如文字颜色等属性也可以在此设置。

添加ProDtlnoteline由ProDtlnotedataLineAdd函数完成：

1
2
// line加入notedata
status = ProDtlnotedataLineAdd(notedata, line);

添加ProDtlattach由ProDtlnotedataAttachmentSet函数完成：

1
status = ProDtlnotedataAttachmentSet(*notedata, *attachment);

设定文字颜色则由ProDtlnotedataColorSet函数完成：

1
status = ProDtlnotedataColorSet(*notedata, &color);

2.6 生成ProDtlnote

最终通过ProDtlnoteCreate创建ProDtlnotedata确定的注释对象，再使用ProDtlnoteShow显示注释对象ProDtlnote即可：

1
2
status = ProDtlnoteCreate(mdl, NULL, notedata, &note);
status = ProDtlnoteShow(&note);

完整代码可在Github.com下载。代码在VS2010,Creo 2.0 M060 X64下编译通过。