(完整)3_UG二次开发实用教程第三章.pdf

第 3 章 编程基础 3.1 UG/Open API 函数 3.1.1 函数名称的约定 UG/Open API 共有两类名称约定。一个是标准的UG/Open API 的函数名称约定；另一个是以前版本原有的名称约定。1、标准名称约定 格式：UF_ 说明：UF_，user funciton的简写，表示该函数为UG/Open API函数；，应用或模块的名称缩写。例如 modl 和 disp 分别是Modeling模块和Display功能的名称缩写；，表示其实现功能的语言描述，一般由下划线分开的动词和名词（或词组）组成。常用的动词有：ask（查询）、create（创建）、edit（编辑）、set（设置）、delete（删除）等。例如：UF_MODL_create_block1()为创建立方体的函数；UF_DISP_set_highlight()是高亮显示对象的函数；（2）非标准名称约定 格式：uc 和 uf 说明：代表UG/Open API C 程序，通常是四位数或三位数接一个字母。例如：uc1601是一个提示信息函数。3.1.2 函数参数的约定 UG/Open API 提供的函数遵守 ANSI/ISO C 的标准，并以下列格式在头文件中提供函数原型：(变量列表)；返回数据类型通常是 C 数据类型或 UG/Open API 自定义数据类型。参数的输入输出方式有 3 种：I（Input）、O（Output）或 OF（Output Free），说明见表 3-1。表 3-1 参数输入方式说明 元 素 描 述 I 表示参数为输入方式，参数在使用前必须赋值 O 表示参数为输出方式，使用前无须赋值 OF 表示参数为输出方式，且使用后需要释放内存。UG/Open API 提供的常用 释 放 内 存 函 数 有UF_free()、UF_free_string()和UF_STYLER_free_value()等，至于选择哪种释放函数需视具体情况而定。例如：函数 UF_PART_open()名称：UF_PART_open 使用环境:internal&external 语法格式:int UF_PART_open(char*part_name,tag_t*part,UF_PART_load_status_t*error_status);描述：加载一个 UG 部件文件到 UG 的界面环境中，并把它设为工作和当前显示部件，该函数的描述见表3-2。表 3-2 函数 UF_PART_open()参数描述 参数 输入输出 类型 描述 part_name 输入 char*要打开的部件文件名 part 输出 tag_t*打开部件的标识，当打开部件文件失败时为 NULL_TAG error_status 输出 UF_PART_load_status_t*当加载部件失败时该结构中将包含错误代码和部件文件名称，使用结 束后应使用函数UF_free_string_arry()和UF_free()释放内存 return 输出 int 返回代号：为 0 时表示正常；非 0 时表示错误代号 3.2 UG/Open API 的数据类型 除了 C 语言标准的数据类型外，UG/Open API 还提供了一些自定义的数据类型，如 tag_t 类型、结构类型（structure type）、枚举类型（enum type）、联合类型（union type）与指针类型（pointer type）等，它们统一用后缀“_t”表示，且这些数据类型的指针用反缀“_p_t”命名表示。数据类型约定如表 3-3 所示：表 3-3 数据类型约定 后缀 描 述 _t 数据类型(data type)_p_t 数据类型的指针(pointer to data type)_s 结构标识(structure tag)_u_t 联合类型(union type)_u_p_t 联合类型的指针(pointer to a union type)_f_t 函数指针(pointer to a function)3.2.1 tag_t 类型 UG/Open API 使用最多的数据类型是 tag_t，在 UG/Open API 的uf_defs.h 中定义如下：typedef unsigned int tag_t,*tag_p_t;在 UG 环境中，tag_t 是 UG 对象的句柄，即 UG 对象模型的唯一标识。它是一种不重复的无符号整型数值，主要用于标识应用程序中的对象，如部件、草图、曲线、属性和表达式等。UG 应用程序只能访问句柄，而不能直接访问句柄所指示的实际对象。程序一般通过调用 API 函数获取句柄，并且在其他 API 函数中使用这个句柄，以引用它指示的对象。在此过程中，句柄的实际值对程序来说是无关紧要的。此外，tag_p_t 是指向tag_t数据类型的指针。以部件对象为例，下面的代码首先获取工作部件的tag_t值，然后获取该句柄所引用部件对象的文件名。tag_t tWorkPart;tWorkPart=UF_ASSEM_ask_work_part();3.2.2 结构类型 UG/Open API 采用 C 语言的语法定义了一些常用的结构类型，将相应联系的不同类型数据封装在一起使用，这些结构类型用后缀“_s”表示，例如：struct UF_STYLER_item_value_type_s int reason;const char*item_id;int subitem_index;int count;int item_attr;int indicator;UF_STYLER_value_t value;typedef struct UF_STYLER_item_value_type_s UF_STYLER_item_value_type_t,*UF_STYLER_item_value_type_p_t;结构体 UF_STYLER_item_value_type_s 封装了对话框控件的基本属性，如 reason、item_id 和 value 等。UG/Open API 使用关键词 typedef将该结构类型定义为新类型 UF_STYLER_item_value_type_t，用户可以使用它定义结构变量，然后引用结构体内的数据成员，例如：UF_STYLER_item_value_type_t data;UF_STYLER_ask_value(dialog_id,&data);UF_STYLER_free_value(&data);3.2.3 枚举类型 枚举类型将变量的值一一列举出来，变量的值只限于列举出来的值的范围。UG/Open API 采用 C 语言的语法定义了一些常用的枚举类型，使用后缀“_e”表示。以枚举类型 UF_ASSEM_load_status_e 为例，下面给出其详细定义：enum UF_ASSEM_load_status_e UF_ASSEM_ok,UF_ASSEM_suppressed,UF_ASSEM_not_loaded,UF_ASSEM_instance_suppressed;typedef enum UF_ASSEM_load_status_e UF_ASSEM_load_status_t;枚举类型 UF_ASSEM_load_status_e 表示部件在装配体中的状态。UG/Open API 使 用 typedef 关 键 词 将 该 枚 举 类 型 定 义 为 新 类 型UF_ASSEM_load_status_t，例如：char sPartPath=“E:Examplepart.prt”;tag_t tPart=NULL_TAG;UF_PART_load_status_t error_status;UF_PART_open(sPartPath,&tPart,&error_status);3.2.4 联合类型 有时需要将不同数据类型的变量放在同一段内存单元中，这种使不同变量占用同一段内存的结构类型称为联合类型。联合类型与结构类型的定义形式相似，但含义不同。联合类型变量所占的内存长度等于其内部最长数据成员的长度，而结构类型变量所占的内存长度则是其各数据成员所占内存长度之和。UG/Open API 采用 C 语言的语法定义了一些常用的联合类型，使用后缀“_u”表示。以联合类型 UF_STYLER_value_u 为例，下面给出其详细定义：union UF_STYLER_value_u char *string;char *strings;int integer;int *integers;double real;double *reals;UF_UI_selection_p_t selection;UF_STYLER_notification_p_t notify;UF_UI_attachment_t attach;UF_UI_option_toggle_t option_toggle;typedef union UF_STYLER_value_u UF_STYLER_value_t;联合体 UF_STYLER_value_u 封装了对话框对话框控件的属性值，如string、integer 和 real 等。UG/Open API 使用 typedef 关键词将该联合类型定义为新类型UF_STYLER_value_t，它是UF_STYLER_item_value_type_t中的数据成员 value 的类型，例如：UF_STYLER_item_value_type_t data;double rValue;sel_data.item_id=REAL_BUTTOM_DIAMETER;UF_STYLER_ask_value(dialog_id,&sel_data);rValue =data.value.real;3.3 UG 对象类型及基本操作 UG 中的所有对象都是通过唯一的 tag_t 值进行标识，这些对象大致可以分为部件对象、UF 对象、表达式、链表和属性。3.3.1 部件对象 部件对象是 UG 最基本的操作对象之一，不仅包含了零件的几何信息，而且更包含了大量的非几何信息，非几何信息包括：创建部件的计算机类型；保存部件的 UG 版本；部件的历史信息(例如部件文件的保存记录等)；状态、描述和用户区的可永久保存在部件文件中的信息。UG/Open API 提供的访问和操作部件文件的函数包括部件文件的创建、打开、关闭、保存和信息的查询等。表 3-4 对部件对话操作的函数 函数 描述 UF_OBJ_cycle_objs_in_part()在部件中查询对象 UF_ATTR_ask_part_attrs()访问部件的属性 UF_PART_close()UF_PART_reopen()关闭和再打开部件 UF_PART_ask_part_name()获取部件的文件名 UF_PART_ask_customer_area()UF_PART_ask_description()UF_PART_ask_status()查询其他信息，包括：查询用户定义的数据、部件文件的描述信息，部件文件的状态信息 UF_PART_ask_part_history()查询部件文件的历史 UF_PART_ask_compression_flags()UF_PART_set_compression_flags()查询及设置部件文件的压缩标记 部件对象基本操作涉及的函数主要有 UF_PART_new、UF_PART_open、UF_PART_close_all、UF_PART_save 和 UF_PART_close。（1）UF_PART_new extern int UF_PART_new(char*part_name,int units,tag_t*part )；参数 part_name 是指向保存被创建文件路径和名称的字符串指针，units 是输入参数，表示被创建文件使用的单位制，1 表示米制，0 表示英制。part 是输出参数，是指向新创建部件文件的 tag_t。该函数的返回值是错误代码，可以利用函数 UF_get_fail_message 得到其所对应的错误信息。（2）UF_PART_open extern int UF_PART_open(char*part_name,tag_t*part,UF_PART_load_status_t*error_status )；参数 part_name 是指向保存被创建文件路径和名称的字符串指针，是输入参数。error_status 是输出参数，表示打开文件的操作是否产生错误。（3）UF_PART_close_all extern int UF_PART_close_all()将当前会话中的所有部件文件关闭。对于被修改的部件文件，UF_PART_close_all并不会导致这些文件被存盘，也不会提示用户存盘。UG仅仅向用户确认是否将当前部件文件关闭。（4）UF_PART_save extern int UF_PART_save()将当前会话中显示的部件文件存盘。由于UG 本身并不对部件文件自动存盘，所以存盘需求都需要户进行维护。（5）UF_PART_close extern int UF_PART_close(tag_t part,int scope,int mode )其中参数part是输入参数，表示关闭操作的部件的标识。参数scope是输入参数，表示被关闭文件涉及的范围。scope=1 表示关闭部件文件和其所有子装配；scope=0 表示仅仅关闭部件文件本身。参数 mode 是输入参数，表示是否请求用户确认。当 mode=0 时，如果被关闭的部件文件被修改过，则询问用户是否关闭；mode=1 表示即使文件被修改了，也要执行关闭操作；mode=2 时表示如果部件文件被修改了，则放弃关闭操作。3.3.2 UF 对象 UF 对象是那些具有标识的实体、包括几何对象和非几何对象。几何对象包括点、线、面、实体等；非几何对象有坐标系、矩阵、尺寸等。UG中所有具有标识的实体，如点、线、面、基准等，都可以称为对象。模型中包含的对象包括几何实体对象、非几何对象。其中几何实体又可细分为实体、点、直线、圆弧等。非几何实体对象则有坐标系对象、尺寸对象、颜色、线性等。UF 利用类型与子类型来区别部件文件中不同对象。每个UF 对象都有一种类型，在头文件 uf_object_types.h 中详细定义了这些对象的类型（type）和子类型（subtype），子类型可以更加精确地描述UF 对象，但是不是所有的对象都拥有子类型，例如：#define UF_group_type 15#define UF_dimension_type 26#define UF_dim_horizontal_subtype 1#define UF_dim_vertical_subtype 2#define UF_dim_parallel_subtype 3#define UF_dim_cylindrical_subtype 4#define UF_dim_perpendicular_subtype 5#define UF_dim_angular_minor_subtype 6#define UF_dim_angular_major_subtype 7#define UF_dim_arc_length_subtype 8#define UF_dim_radius_subtype 9#define UF_dim_diameter_subtype 10#define UF_dim_hole_subtype 11#define UF_dim_conc_circle_subtype 12#define UF_dim_ordinate_horiz_subtype 13#define UF_dim_ordinate_vert_subtype 14#define UF_dim_assorted_parts_subtype 15#define UF_dim_folded_radius_subtype 16#define UF_dim_chain_dimensions_subtype 17#define UF_dim_ordinate_origin_subtype 18#define UF_dim_perimeter_subtype 19#define UF_dim_chamfer_subtype 20 其中，UF_group_type 表示组类型，类型值为 15，无子类型；UF_dimension_type表示尺寸类型，类型值为 26，120 表示它的子类型的值，分别表示为垂直尺寸、水平尺寸、平等尺寸等。UG/Open API 提供的访问和操作 UF 对象的函数包括 UF 对象的查询、遍历、等。对象操作函数请参考头文件 uf_obj.h 中的定义。表 3-5 UF 对象基本操作函数 函数 描述 UF_OBJ_set_name()UF_OBJ_ask_name()UF_OBJ_delete_name()指定、查问及删除单个对象的名称 UF_OBJ_cycle_objs_in_part()UF_OBJ_cycle_all()UF_OBJ_cycle_by_name()UF_LAYER_cycle_by_layer()查询遍历对象，可以在指定部件中遍历对象，在当前工作部件中遍历对象，通过对象名称和图层查询对象 UF_MODL_delete_exp()UF_MODL_delete_feature()UF_OBJ_delete_object()UF_OBJ_delete_array_of_objects()对象删除 UF_UI_select_single()UF_UI_select_by_class()UF_UI_select_feature()UF_UI_select_sketch()对话选择 1、对象状态 对象的状态可通过使用函数 UF_0BJ_ask_status()来查询。对象共有下列几种状态：表 3-6 UF 对象状态标识 状态标识 描述 UF_OBJ_DELETED 被删除的状态 UF_OBJ_TEMPORARY 临时状态。例如临时坐标系由UF_CSYS_create_temp_csys 函数创建，不会被保存 UF_OBJ_CONDEMNED 不正常状态。一般由于对象被删除，但它是其它对象的参考，只有所有的这些参考被删除后，该对象才从模型中被删除，该状态的对象永远不被显示 UF_OBJ_ALIVE 激活状态 2、对象访问 在创建对象时，可以直接得到对象标识。但是，多数情况下需要访问已经在部件文件中存在的对象。一般可能通过以下两种方法来确定 UF 对象的标识：一是循环法。即可在获取目标体上面标识的循环过程中，插入下段程序。该段程序会高亮显示目标体上表面并弹出一个需用户确认的对话框，对话框中显示该对象的标识号。其中 tem_tag 为目标体上表面的标识。UF_DISP_set_highlight(tem_tag,1);Sprintf(mess,The object is%d!,i);uc1601(mess,1);UF_DISP_set_highlight(tem_tag,0);二是参数法。即可利用函数 UF_MODL_ask_face_data 获得目标体上表面的参数，包括表面的类型、表面的法向和表面的原点等信息。比如下面一段程序是为了获得圆柱体的圆柱表面。/通过圆柱特征标识，获得圆柱表面的链表 UF_MODL_ask_feat_faces(cyl_eid,&face_list);UF_MODL_ask_list_count(face_list,&num);for(i=0;i num;i+)UF_MODL_ask_list_item(face_list,i,&face);/获得每个圆柱表面的参数 UF_MODL_ask_face_data(face,&type,point,face_dir,box,&radius,&rad_data,&sense);/将类型为的 16（圆柱表面）表面取出赋给变量 tem_tag 并退出循环 if(type=16)tem_tag=face;break;/删除链表，释放内存 UF_MODL_delete_list(&face_list)3、设置可显示的UF 对象信息的函数。UG/Open API 提供了对可显示的 UF 对象的层、颜色、线型等属性进行设置和查询的接口。注意除了高亮状态外，其他信息都可以保存到 part文件中。表 3-7 设置可显示 UF 对象函数 函数 描述 UF_OBJ_ask_display_properties()用于查询可显示 UF 对象的显示属性 UF_OBJ_set_layer()用于设置可显示 UF 对象的层 UF_0BJ_set_color()用于设置可显示 UF 对象的颜色 UF_0BJ_set_blank_status()用于设置可显示 UF 对象的 blank 状态 UF_OBJ_set_line_width()用于设置可显示 UF 对象的线型 UF_OBJ_set_font()用于设置可显示 UF 对象的字体 UF_DISP_set_highlight()用 于 设 置 可 显 示UF对 象 的 高 亮(highlight)状态 3.3.4 表达式 3.3.4.1 表达式的定义 UG/Open API 创建的表达式和 UG 的交互界面产生的表达式同样在“表达式编辑器”中可见。表达式提供 UG 中的参数化建模的机制，表达式能控制特征，特征也随表达式的变化而改变。个表达式可在多个特征中使用，这样它的变化将能改变多个特征。表达式的形式一般是：“name=value”。表达式名的首字符必须是字母，其他字符可以是数字、字母、下划线等。表达式名是大小写敏感的，一个部件文件中的表达式名应唯。表达式值可以是数字和条件等式，表达式名可以用于表达式值中。3.3.4.2 表达式的使用 UF 函数允许用户创建、查询和编辑表达式和几何表达式，对表达式进行各种操作的函数包含在头文件uf_modl.h 中，对几何表达式进行各种操作的函数包含在头文件uf_gexp.h 中。如果表达式串中，仅仅提供表达式值，UG 软件会自动给它个名字。如表达式串定义如下：“diameter2”UG 会赋给它一个类似“p0”的名字。建议按下列形式赋值“radius=diameter2”可以用函数 UF_MODL_create_exp()创建表达式；当需要得到创建的表达式的标签时，使用函数 UF_MODL_create_exp_tag()。常用表达式操作函数如表 3-8 所示：表 3-8 常用表达式操作函数 函数 描述 UF_MODL_create_exp()创建表达式，没有返回 UF_MODL_create_exp_tag()创建表达式，返回新建表达式的标识 UF_MODL_import_exp()从文件输入表达式，即可引用其它部件的表达式文件，操作完成后必须用函数 UF_MODL_update()更新数据库 UF_MODL_dissect_exp_string()分解名字和值返回名字、值和表达式的标识 UF_MODL_eval_exp()输入表达式的名，返回表达式的值 UF_MODL_edit_exp()用新的值替换表达式中原有的值。使用后应用函数UF_MODL_update()来更新模型 UF_MODL_rename_exp()给已有表达式赋新的名称 UF_MODL_ask_exp()返回表达式名和表达式值 UF_MODL_ask_exps_of_feature()返回制约某特征的所有表达式的标识 UF_MODL_ask_exps_of_part()返回某部件文件的所有表达式的标识 UF_MODL_ask_exp_tag_string()输入表达式标识，返回该表达式串。UF_MODL_ask_exp_tag_value()通过表达式标识获得表达式值 下面举例说明函数 UF_MODL_edit_exp()的使用方法，代码实现的功能是将表达式 p1 的值改为 20。注意：函数 UF_MODL_edit_exp()的输入参数必须为整个表达式，并且编辑表达式后，必须更新模型才能及时反映其变化。char sExp=“p1=20”;UF_MODL_edit_exp(sExp);UF_MODL_update();3.3.5 链表对象 为了提高编程的灵活性，UG/Open API 提供了对象链表。它使用来存放对象或特征的标识，链表的每个节点保存一个对象或特征的标识。与链表有关的操用函数如表 3-9 所示，它们包含在头文件 uf_modl.h 中。表 3-9 链表操作函数 函数 描述 UF_MODL_create_list()创建一个链表，并返回链表的头指针 UF_MODL_put_list_item()插入元素到链表中。该函数只将对象加入到链表的尾部，不校验链表中是否有重复对象 UF_MODL_ask_list_count()获取链表中元素的个数。该函数计算从链表的头开始到第一个出现 NULL_TAG 节点之间的节点个数。因此，如果链表中包含 NULL_TAG，那么得不到链表的真实长度。UF_MODL_ask_list_item()查询链表中的对象标识。该函数通过标识在链表中的位置返回对象标识 UF_MODL_delete_list_item()将指定的对象从链表中删除 UF_MODL_delete_list()删除链表，并释放内存 下面举例说明链表的使用方法，代码实现的功能是利用曲线数组创建曲线链表，需要注意的是链表使用完后，需要利用UF_MODL_delete_list()删除不需要的链表。uf_list_p_t curves_list=NULL;int i=0,irc=0;UF_MODL_create_list(&curves_list);for(i=0;in_curves;i+)UF_MODL_put_list_item(curves_list,curvesi);UF_MODL_delete_list(&curves_list);List 两种应用场合。3.3.6 属性对象 UG 环境下的属性是用户附加到部件或对象上的字符串、整形数值、实型数值的字段，用于对部件或对象进行说明或做标记。UG/Open API 在头文件 uf_attr.h 中提供了与部件或对象属性的接口。与属性对象有关的操用函数如表 3-10 所示。部件属性对象是 UF_part_attribute_type 类型，它是关于整个部件的信息对象，例如模型的材料等属性。在每个 UG 部件中都有个部件属性对象，在单个的部件属性对象上可以附加多个属性项。UG提供了7种属性类型：UF_ATTR_any、UF_ATTR_string、UF_ATTR_integer、UF_ATTR_real、UF_ATTR_null、UF_ATTR_time、UF_ATTR_reference。UF_ATTR_any表示所有属性类型。表 3-10 链表操作函数 函数 描述 UF_ATTR_ask_part_attribute()获取工作部件的部件属性对象标识 UF_ATTR_ask_part_attrs()用于从加载到 UG 中的抽取属性对象的属性 UF_ATTR_ask_part_attrs_in_file()用于从磁盘文件中抽取部件的属性对象的属性，而不用把该部件加载到 UG 中 UF_ATTR_assign()给指定的部件属性或部件分派一个属性 UF_ATTR_count_attributes()计算属于某一个对象的指定类型的属性数 UF_ATTR_cycle()遍历对象某一类型的所有属性项，返回下一个属性标题及属性值 UF_ATTR_delete()从对象上删除指定类型的属性 UF_ATTR_delete_all()从对象上删除指定类型的所有属性 UF_ATTR_find_attribute()查找某一属性标题的特定属性类型 UF_ATTR_read_value()读取给定类型和标题的属性的值 任何确定存在的UG对象都具有唯一的标识，这里对象是指UG的part、object、Feature、Expression 等。