UG-NX二次开发基础-OpenAPI.doc

CHAPTER22UG NX 5.0二次开发基础内容提要 UG/Open API基础概念和语法知识 UG/Open API常用对话框及其应用 提示消息的发布与获取Open/API（用户函数）是一个程序集合，使得程序员能够访问和操作NX对象模型。除此之外，Open/API还提供了工具用来编辑和连接与UG NX 5.0风格一致的程序。UG/Open二次开发模块是UG NX 5.0软件的二次开发工具集，可用于各种二次开发工作。利用该模块可对UG NX 5.0系统进行用户化剪裁和开发，满足用户的开发需求。使用UG NX 5.0的二次开发时，用户需要具有一定的C语言基础。UG/Open包括以下几个部分。（1）UG/Open API开发工具：提供UG NX 5.0软件直接编程接口，支持C、C+、Fortran和Java等主要高级语言。（2）UG/Open UIStyle开发工具：是一个可视化编辑器，用于创建类似于UG NX 5.0的交互界面。利用该工具，用户可为UG/Open应用程序开发独立于硬件平台的交互界面。（3）UG/Open Menuscript开发工具：对UG NX 5.0软件操作界面进行用户化开发，使得用户无须编程即可对UG NX 5.0标准菜单进行添加、重组、剪裁或在UG NX 5.0中集成自己开发的软件功能。（4）UG/Open GRIP开发工具：是一个类似于APT的UG NX 5.0内部开发语言，用户可利用该工具生成NC自动化或自动建模等特殊应用。22.1 UG/Open API语法基础由于UGOpen API是UG NX 5.0中最常用的二次开发工具，因此国内外有大量的UG NX 5.0用户投入了大量的精力对UGOpen API的编程进行研究，而且已经掌握了大量的编程技巧，并开发了许多实际的应用。本书在编写过程中，参考了他们的许多经验。22.1.1 概述作为UG NX 5.0与外部应用程序之间的接口，UGOpen API是一系列函数的集合。通过UGOpen API的编程，用户几乎能够实现所有的UG NX 5.0功能。开发者可以通过用C+语言编程来调用这些函数，从而实现用户的需求。（1）对UG part文件及相应模型进行操作，包括建立UG NX 5.0模型、查询模型对象、建立并遍历装配体及创建工程图等。（2）在UG NX 5.0中创建交互式程序界面。（3）创建并管理用户定义对象等。应用函数时应注意，所有的UG/Open API 应用必须及时进行初始化和终止，以确保获取或释放UG/Open API的执行许可权限。初始化函数是UF_initialize，开始调用UG/Open API的函数时应先调用UF_initialize来获取执行许可权限。一般来说，变量声明完成后，第一个调用的UG/Open API函数就是UF_initialize。终止函数是UF_terminate，不再需要调用UG/Open API的函数时，必须先调用UF_terminate来释放执行许可。UG/Open API 程序能在两种不同的环境（依赖于程序的连接方式）下运行，即Internal环境（也叫“Internal开发模式”）和External模式。其中Internal环境下的程序只能在UG NX 5.0的界面环境（session）下运行，在运行这些程序时它们被加载到UG NX 5.0的运行空间中（UG NX 5.0分配的内存）。External模式开发的程序能在各种操作系统（Windowns NT/2000/XP及UNIX）下运行，不在UG NX 5.0环境中或作为UG NX 5.0的子进程运行。尽管没有图形显示，但UG/Open API提供了函数用于打印机或绘图仪输出，也可以输出成CGM文件或其他数据文件。下面在Visual C+中创建一个基于UG/Open API AppWizard 的项目，来说明初始化函数和终止函数的应用。【例22-1】 UG/Open API中初始化函数和终止函数的应用。操作步骤如下。检查Visual C+的安装目录Microsoft Visual Studiocommonmsdev98Template下是否有文件ugopen.awx及ugopen.hlp，若有，进入步骤2；否则从UG安装目录$UG_BASE_DIR/ugopen下将这两个文件复制并粘贴到目录Microsoft Visual Studiocommonmsdev98Template下。启动Visual C+，选择【File】【New】命令，弹出【New】对话框，如图22-1所示。图22-1 【New】对话框 选择 选项卡，在选项卡下面的列表框中选择【UG/Open APPWizard V18】，在 文本框中输入项目名称“Example”，单击 按钮。在弹出的对话框中按图22-2所示设置选项。图22-2 设置选项1单击 按钮，在弹出的对话框中设置选项，如图22-3所示。图22-3 设置选项2单击 按钮，系统弹出【New Project Information】窗口，如图22-4所示。窗口中列出了用户选择的所有信息。确认无误后单击 按钮，系统将在指定的目录下创建一个UG NX 5.0二次开发框架。图22-4 【New Project Information】对话框按快捷键F7，编译Example工程，一般会出现编译成功的信息，如图22-5所示。图22-5 编译成功的界面打开【FileView】选项卡，单击【Examplefiles】前的 + 。然后单击【Source Files】前面的，双击【Example.cpp】，文件的内容如图22-6所示。下面给出“Example.h”和“Example.cpp”两个文件的内容，在“Example.cpp”文件中可以找到函数：extern C DllExport void ufusr( char *parm, int *returnCode, int rlen )其函数体中包含着UG/Open API中的初始化函数UF_initialize和终止函数UF_terminate。在进行应用开发时，只需要把相应的代码（代码中的黑体部分）添加到相应的位置，即可完成应用开发。图22-6 打开Example.cpp文件Example.h文体内容如下：/* Example.h* Description:* Example header file.*/static void PrintErrorMessage( int errorCode );Example.cpp文件内容如下：/ Example.cpp/ Description:/ Contains Unigraphics entry points for the application./ Include files#include #include #include #if ! defined ( _hp9000s800 ) & ! defined ( _sgi ) & ! defined ( _sun )#include using std:ostrstream;using std:endl;using std:ends;#else#include #endif#include #include Example.h/-/ Activation Methods/-/ Explicit Activation/ This entry point is used to activate the application explicitly, asin/ File-Execute UG/Open-User Function.extern C DllExport void ufusr( char *parm, int *returnCode, int rlen ) /* Initialize the API environment */ int errorCode = UF_initialize(); if ( 0 = errorCode ) /* TODO: Add your application code here */ /* Terminate the API environment */ errorCode = UF_terminate(); /* Print out any error messages */ PrintErrorMessage( errorCode );/-/ Utilities/-/ Unload Handler/ This function specifies when to unload your application from Unigraphics./ If your application registers a callback (from a MenuScript item ora/ User Defined Object for example), this function MUST return/ UF_UNLOAD_UG_TERMINATE.extern C int ufusr_ask_unload( void ) return( UF_UNLOAD_UG_TERMINATE );/* PrintErrorMessage* Prints error messages to standard error and the Unigraphics status* line. */static void PrintErrorMessage( int errorCode ) if ( 0 != errorCode ) /* Retrieve the associated error message */ char message133; UF_get_fail_message( errorCode, message ); /* Print out the message */ UF_UI_set_status( message ); / Construct a buffer to hold the text. ostrstream error_message; / Initialize the buffer with the required text. error_message endl Error: endl message endl endl ends; / Write the message to standard error cerr error_message.str(); 在创建几何模型、遍历模型或执行其他一些基本操作时，必须首先创建或打开一个Unigraphics Part文件。22.1.2 UG/Open API函数名称及数据类型作为Unigraphics二次开发的一个重要模块，UG/Open API在函数名称和数据类型方面都有自己的一些独特风格，本章将分别予以介绍。UG/Open API的函数名称一般采用标准名称约定，其格式为： UF_名称中各部分的说明如下。（1）UF：表示 UG/Open API 函数。（2）：通常是模块功能和首字母的缩写，例如MODL和 DISP 是 Modeling 模块和Display功能的缩写。（3）：被下画线分开的动词和名词，例如UF_MODL_create_block1是UG/Open API Modeling模块中创建立方体的函数，UF_DISP_set_highlight是高亮显示对象的函数。在数据类型方面，除了标准的C语言数据类型外，UG/Open API还提供了一些自定义的数据类型，如tag_t类型、结构类型、联合类型与指针类型等。下面介绍几种常用的类型。1tag_t数据类型UG/Open API使用最多的数据类型是tag_t，在UG/Open API的uf_def.h中对该类型的定义如下：typedef unsigned int tag_t, *tag_p_t;该类型把UG/Open API与对象模型联系起来。当UG的模型被加载到UG环境中后，tag_t相当于对象的唯一标识。大部分的UG/Open API函数参变量列表中都有一个tag_t 指针或tag_t 类。它类似于C语言中的指针，例如当要查询一个点对象的坐标时，送入查询函数中的tag_t应是点类型的几何对象，而不是线或面等其他几何对象的tag_t。此外，tag_p_t是指向tag_t数据类型的指针。以部件对象为例，下面的代码首先获取部件的tag_t值，然后获取该句柄所引用部件对象的文件名。tag_t tPart;tPart=UF_ASSEM_ask_work_part();char sFile256+1;UF_PART_ask_part_name(tPart,sFile);由于代码中加入了函数UF_ASSEM_ask_work_part()，因此调试程序时应加入头文件#include 。UG/Open API 拥有大量用于创建及修改Unigraphics对象的函数和过程。UG/Open API的部分函数不提供错误信息，在创建对象时一般返回对象的标识（tag_t）。当返回的对象标识为NULL_TAG 时，表示创建对象时出现了错误。2结构类型（Structure type）UG/Open API采用C语言的语法定义了一些常用的结构类型，将相互联系的不同类型的数据封装在一起使用。这些结构类型用后缀“_s”表示，下面给出一个使用结构类型的例子。typedef struct UF_ASSEM_options_sint reason;const char *item_id;int subitem_index;int count;int item_attr;int indicator;UF_ASSEM_options_s,*UF_ASSEM_options_s_t;3联合类型（Union type）有时需要将不同数据类型的变量放在同一段内存单元中，这种使不同变量占用同一段内存的结构类型称为“联合类型”。联合类型与结构类型的定义形式相似，但含义不同。联合类型变量所占的内存长度等于其内部最长数据成员的长度乘以变量个数，而结构类型变量所占的内存长度则是其各数据成员所占内存长度之和。UG/Open API采用C语言的语法定义了一些常用的联合类型，使用后缀“_u”表示，下面给出一个使用联合类型的例子。union UF_ASSEM_options_uchar *assemchar;int integer;int *integers;double assem;double *assems;UF_UI_selection_p_t selection;typedef union UF_ASSEM_options_u UF_ASSEM_options_t;4枚举类型（Enum type）枚举类型将变量的值一一列举出来，变量的值只限于列举出来的值的范围。UG/Open API采用C语言的语法定义了一些常用的枚举类型，使用后缀“_e”表示。下面给出一个使用枚举类型的例子。enum UF_ASSEM_options_eUF_ASSEM_ok,UF_ASSEM_cancel,UF_ASSEM_not_loaded,UF_ASSEM_suppressed,;typedef enum UF_ASSEM_options_e UF_ASSEM_options_t;22.1.3 UG/Open对象类型与操作所有的UG NX 5.0对象类型都通过它们唯一的标识来引用，这些UG NX 5.0对象分类如下。（1）部件对象（Part object）。（2）UF对象（UF objects），指uf_object_types.h中说明的对象。（3）表达式（Expressions）。对于每一类对象，UG/Open API中都有明确的函数对它们进行操作，下面分别介绍。1部件对象部件对象是UG NX 5.0最基本的操作对象之一，它包含了部件中大量的几何与非几何信息。每一个加载到UG NX 5.0环境中的part文件，都有一个关联的部件对象（part object）代表它，系统会为每一个部件对象分配一个标记符（tag）。UG/Open API提供的访问和操作部件文件的函数包括部件文件的创建、打开、关闭、保存和信息的查询等，这些函数主要封装在头文件uf_part.h中，包括：UF_ATTR_ask_part_attrs()访问part的属性UF_OBJ_cycle_objs_in_part() 在part中查询对象UF_PART_close()关闭partUF_PART_reopen()再打开partUF_PART_ask_part_name() 获取part的文件名UF_PART_set_display_part() 设置显示部件UF_PART_ask_part_history() 获取部件的历史UF_PART_ask_customer_area() 查询用户定义的数据UF_PART_ask_description()查询part的描述信息UF_PART_ask_status() 查询part的状态信息UF_PART_set_customer_area() 设置用户定义的数据UF_PART_set_description() 设置part的描述信息UF_PART_set_status() 设置part的状态信息UF_PART_ask_compression_flags() 查询part的压缩标记UF_PART_set_compression_flags()设置part的压缩标记下面给出一个例子来讲述Part文件的创建、打开、关闭和存盘等操作。【例22-2】 Part文件的创建、打开和关闭操作。操作步骤如下。在例22-1中加入下面的头文件：#include uf_part.h#include uf_obj.h把下面的代码添加到例22-1中黑体代码所在的位置，按快捷键F7，编译Example工程，出现编译成功的信息。UF_PART_load_status_t error_status ;char part_name133 = I: ExampleDebugtest.prt;int units = 1 ; / 单位采用米制tag_t part;UF_PART_new (part_name, units, &part); / 创建test.prtif ( part = NULL_TAG ) uc1601(创建Part错误, 1);UF_PART_close_all ( ); /退出之前关闭所有parterrorCode = UF_terminate();return;elseuc1601(test创建成功,1);uc1601(test被设为显示part并且被打开, 1);UF_PART_set_display_part (part ); / 显示test.prtUF_PART_open (part_name, &part, &error_status);UF_free_string_array(error_status.n_parts,error_status.file_names);UF_free (error_status.statuses );启动UG NX 5.0软件，选择【文件】【打开】命令，弹出【执行用户函数】对话框如图22-7所示。图22-7 【执行用户函数】对话框在 下拉列表框中选择文件夹“ExampleDebug”，选中文件“Example.dll”，然后单击 按钮，弹出的消息对话框如图22-8所示，提示用户test创建成功。图22-8 运行“Example.dll”文件后弹出的【消息】对话框单击 按钮，弹出【消息】对话框如图22-9所示，提示用户test被设置为显示并且被打开。图22-9 提示用户打开“test.part”文件的【消息】对话框继续单击 按钮，Part文件“test.part”被打开，如图22-10所示。接下来可以创建模型，单击 按钮后打开文件夹“I:ExampleDebug”，即可发现文件“test.part”。图22-10 新建零件界面2UF 对象UG NX 5.0中的大部分公共对象都是头文件uf_object_types.h和uf_obj.h中定义的对象。所有这些对象都有明确的函数与它们对应，只有特定的对象子类和可显示的UF对象有另外的函数与它们对应。UF对象的可用方法如下。（1）指定、查询及删除单个对象的名称，例如：UF_OBJ_set_name() 指定对象名UF_OBJ_ask_name() 查询对象名UF_OBJ_delete_name() 删除对象名（2）查询遍历对象，例如：UF_OBJ_cycle_objs_in_part() 在part中遍历对象UF_OBJ_cycle_all() 在当前工作part中遍历对象UF_OBJ_cycle_by_name() 通过对象名称查询对象因为UG NX 5.0中对象存储方式的独特，所以函数UF_OBJ_cycle_objs_in_part()比函数UF_OBJ_cycle_all()、UF_OBJ_cycle_by_name()和UF_LAYER_cycle_by_layer()更为有效。因此建议使用UF_OBJ_cycle_objs_in_part()而不是UF_OBJ_cycle_all()、 UF_OBJ_cycle_by_name()或UF_LAYER_cycle_by_layer()。3表达式表达式提供UG NX 5.0中的参数化建模的机制，它能控制特征，特征也随表达式的变化而改变。一个表达式可在多个特征中使用，这样它的变化将能改变多个特征。表达式的一般形式是：name = valuename为表达式名称，value为表达式的值。表达式可以是数字或条件等式。表达式名可以用于表达式值中，其首字符必须是字母，其他字符可以是数字、字母或下画线等。表达式名是大小写敏感的。一个part文件中的表达式名应唯一。下面是一些表达式值的例子：Length = 1.5 + 2 * sin (angle)position = if(width = 2) (1.5 * width) else (2)一般说来表达式的使用函数都在头文件 uf_modl.h中定义。如果表达式串中仅仅提供表达式值，UG NX 5.0会自动为其命名。如表达式串定义为diameter / 2，UG NX 5.0会赋给它一个类似于f0的名字。当然我们建议按下列形式赋值：radius = diameter / 2。下面列出了头文件 uf_modl_general.h中定义的常用表达式操作函数：UF_MODL_create_exp()创建表达式UF_MODL_create_exp_tag()得到创建的表达式的标签UF_MODL_dissect_exp_string()分解名字和值返回名字、值和表达式的标签UF_MODL_ask_exp()返回表达式名和表达式值UF_MODL_eval_exp()输入表达式的名，返回表达式值UF_MODL_edit_exp()用新的值替换表达式中原有的值UF_MODL_update()用新的值替换表达式中原有的值, 使用后应用函数来更新模型UF_MODL_rename_exp()给已有表达式赋新的名称UF_MODL_ask_exps_of_feature( )返回制约某特征的所有表达式的标签UF_MODL_ask_exps_of_part()返回某部件（part）的所有表达式的标签UF_MODL_ask_exp_tag_string( )输入表达式标签，返回该表达式串下面给出一个例子来说明常用表达式操作函数的使用方法。【例22-3】 创建一个长方体并显示出表达式信息。操作步骤如下。在例22-1中加入下面的头文件：#include uf_modl.h把下面的代码添加到例22-1中黑体代码所在的位置，按快捷键F7，编译Example工程，出现编译成功的信息。char *block_len3 = 10,20,30;double block_orig3 = 0.0,0.0,0.0;tag_t blk_obj;int number_of_exps=0, i;UF_UI_open_listing_window();/ 创建长方体特征UF_MODL_create_block1(UF_NULLSIGN, block_orig, block_len, &blk_obj);tag_t *exps;/ 查询长方体特征所包含的表达式UF_MODL_ask_exps_of_feature(blk_obj,&number_of_exps ,&exps );char * string;char *name3 ;name0 = l;name1 = w;name2 = h;string = 0;UF_MODL_ask_exps_of_feature(blk_obj,&number_of_exps ,&exps );for ( i = 0 ; i Free(pidl);pMalloc-Release();启动UG NX 5.0软件，选择【文件】【执行】【NX打开】命令，弹出如图22-17所示的对话框。选择生成的动态库文件“Example.dll”，单击 按钮，弹出如图22-19所示的文件夹选择对话框。图22-19 执行“Example.dll”文件生成的文件夹选择对话框在调试上面的程序时应加入下面的头文件：#include#include 22.2.3 选择菜单列表对话框UG/Open API的选择菜单对话框有两种，即单选菜单列表对话框和多选菜单列表对话框，分别通过子过程uc1603和uc1605实现，下面将具体介绍。uc1603用于显示一个选择菜单对话框，该菜单可以包含14个菜单选项，并可以通过变量参数设定默认的选择项。若变量参数为0，则不设定默认选项，同时【确定】按钮变灰。菜单选项的返回值介于5和18之间，即使用者选择菜单项1，那么返回值是5，使用者选择菜单项14，那么返回值是18。下面是返回值的说明。（1）1：回退。（2）2：取消。（3）518：选中了的菜单项。（4）19：不允许状态，不能启动对话框。uc1605解决多项选择菜单的问题，与uc1603不同，该子过程没有默认的选择项，数组变量的每一个元数的初值是0。下面介绍返回值及参数。（1）1：回退。（2）2：取消。（3）3：接收。（4）4：有多个选项被选择。（5）8：不允许状态，不能启动对话框。【例22-7】 创建单选菜单列表对话框和多选菜单列表对话框。操作步骤如下。把下面的代码添加到例22-1中黑体字代码所在的位置，按快捷键F7，编译Example工程，出现编译成功的信息。char SingleMenuStr=单选菜单列表对话框;int OkDefault=1;char MenuOptions38=选项1,选项2,选项3;int NumOfOption=3;uc1603(SingleMenuStr,OkDefault,MenuOptions,NumOfOption);启动UG NX 5.0，选择【文件】【执行】【NX打开】命令，弹出如图22-17所示对话框。选择生成的动态库文件“Example.dll”，单击 按钮，出现如图22-20所示的单选菜单列表对话框。图22-20 执行“Example.dll”文件生成的单选菜单列表对话框把下面的代码添加到例22-1中黑体字代码所在的位置，执行与上面相同的操作，即可得到如图22-21所示的多选菜单列表对话框。char SingleMenuStr=多选菜单列表对话框;int *ItemMenu;char MenuOptions38=选项1,选项2,选项3;int NumOfOption=3;uc1605(SingleMenuStr,0,MenuOptions,NumOfOption,ItemMenu); 图22-21 执行“Example.dll”文件生成的多选菜单列表对话框22.2.4 对象选择对话框UG/Open API提供了专门的接口“UF_UI”模块，让开发人员开发的应用能够从Unigraphics图形界面选取几何对象。常用的对象选择对话框有两种：单对象选择对话框与按类选择对话框。UF_UI模块中的函数主要实现两种功能：一种是通过有过滤功能的函数，把开发者定义的可选对象选出来；一种是弹出对话框，让用户在可选对象中选择一个或多个对象。这些函数都在头文件uf_ui.h中定义。下面介绍这两个常用的对话框。注意，调用这两种对话框之前UG环境中必须有工作部件存在。1按类选择对话框按类选择对话框通过函数UF_UI_select_with_class_dial