creo-toolkit（克里奥工具包）

Creo Parametric TOOLKIT API Reference

Creo Parametric TOOLKIT is PTC's C-language API for customizing Creo Parametric. It provides controlled access to the Creo database and user interface through a library of C functions.

API Style and Conventions

Naming Convention

All functions follow: Pro<ObjectType><Action>()

ProSolidRegenerate()      // Object=Solid, Action=Regenerate
ProFeatureDelete()        // Object=Feature, Action=Delete
ProSurfaceAreaEval()      // Object=Surface, Action=AreaEval
ProEdgeLengthEval()       // Object=Edge, Action=LengthEval

Action Verbs

Function Arguments

• First argument: target object
• Input arguments before output arguments
• Return type: ProError (enumerated status)

Common Error Codes

PRO_TK_NO_ERROR        // Success
PRO_TK_BAD_INPUTS      // Invalid arguments
PRO_TK_E_NOT_FOUND     // Item not found
PRO_TK_USER_ABORT      // User cancelled
PRO_TK_GENERAL_ERROR   // General failure
PRO_TK_OUT_OF_MEMORY   // Memory allocation failed
PRO_TK_BAD_CONTEXT     // Wrong mode/state

Object Handles

Opaque Handles (OHandle)

Memory pointers to Creo structures - volatile, may become invalid after regeneration:

typedef void* ProMdl;
typedef struct sld_part* ProSolid;
typedef struct geom* ProSurface;
typedef struct curve_header* ProEdge;
typedef struct entity* ProAxis;
typedef struct entity* ProCsys;

Database Handles (DHandle)

Persistent identifiers with type, ID, and owner:

typedef struct pro_model_item {
    ProType type;
    int id;
    ProMdl owner;
} ProModelitem, ProGeomitem;

Converting Between Handles

// OHandle to DHandle
ProSurfaceIdGet(surface, &id);
ProModelitemInit(owner, PRO_SURFACE, id, &modelitem);

// DHandle to OHandle  
ProSurfaceInit(modelitem.owner, modelitem.id, &surface);

Application Structure

Required Entry Points

#include "ProToolkit.h"

int user_initialize(int argc, char *argv[], 
                    char *version, char *build,
                    wchar_t err_buff[80])
{
    // Setup menus, notifications, initialization
    // Must contain at least one Pro* API call
    return 0;  // 0=success, non-zero=failure
}

void user_terminate()
{
    // Cleanup code
}

Registry File (creotk.dat)

name MyApplication
startup dll
exec_file C:\path\to\myapp.dll
text_dir C:\path\to\text
allow_stop TRUE
end

Application Modes

Visit Functions

Pattern for traversing collections:

ProError MyVisitAction(ProFeature* feature, 
                       ProError status,
                       ProAppData app_data)
{
    // Process feature
    return PRO_TK_NO_ERROR;  // Continue visiting
    // return PRO_TK_E_FOUND; // Stop visiting
}

ProError MyFilter(ProFeature* feature, ProAppData app_data)
{
    // Return PRO_TK_CONTINUE to skip
    // Return any other value to visit
    return PRO_TK_NO_ERROR;
}

// Usage
ProSolidFeatVisit(solid, MyVisitAction, MyFilter, &my_data);

Common Visit Functions

• ProSolidFeatVisit() - Features in solid
• ProSolidSurfaceVisit() - Surfaces in solid
• ProSolidAxisVisit() - Axes in solid
• ProSolidCsysVisit() - Coordinate systems
• ProSolidQuiltVisit() - Quilts
• ProFeatureSurfaceVisit() - Surfaces in feature
• ProAsmcompVisit() - Assembly components

Expandable Arrays (ProArray)

Dynamic arrays for variable-size data:

ProArray my_array;

// Allocate: count, element_size, growth_increment
ProArrayAlloc(0, sizeof(ProFeature), 10, &my_array);

// Add element
ProFeature feat;
ProArrayObjectAdd(&my_array, PRO_VALUE_UNUSED, 1, &feat);

// Get size
int size;
ProArraySizeGet(my_array, &size);

// Access elements
ProFeature* features = (ProFeature*)my_array;
for (int i = 0; i < size; i++) {
    // Use features[i]
}

// Free
ProArrayFree(&my_array);

ProSelection Object

References geometry in assembly context:

ProSelection selection;
ProModelitem modelitem;
ProAsmcomppath comp_path;

// Create selection
ProSelectionAlloc(&comp_path, &modelitem, &selection);

// Extract info
ProSelectionModelitemGet(selection, &modelitem);
ProSelectionAsmcomppathGet(selection, &comp_path);

// Free
ProSelectionFree(&selection);

Models and File Operations

ProMdl model;
ProName name;
ProMdlType type;

// Retrieve model
ProStringToWstring(name, "part_name");
ProMdlnameRetrieve(name, PRO_MDL_PART, &model);

// Get current model
ProMdlCurrentGet(&model);

// Save model
ProMdlSave(model);

// Erase from session
ProMdlErase(model);

Feature Creation Overview

Features are created using Element Trees - hierarchical data structures:

1. Allocate root element: PRO_E_FEATURE_TREE
2. Add feature type: PRO_E_FEATURE_TYPE
3. Add feature-specific elements (including references via ProSelectionToReference)
4. Get current model and create model selection
5. Call ProFeatureWithoptionsCreate() with options array

Standard Pattern (Recommended)

ProError CreateFeatureExample()
{
    ProElement feat_elemtree, elem_feattype;
    ProMdl model;
    ProModelitem model_item;
    ProSelection model_selection;
    ProFeature created_feature;
    ProErrorlist errors;
    ProFeatureCreateOptions *options = NULL;
    ProError status;

    /* 1. Allocate root element */
    status = ProElementAlloc(PRO_E_FEATURE_TREE, &feat_elemtree);

    /* 2. Add feature type */
    status = ProElementAlloc(PRO_E_FEATURE_TYPE, &elem_feattype);
    status = ProElementIntegerSet(elem_feattype, PRO_FEAT_xxx);
    status = ProElemtreeElementAdd(feat_elemtree, NULL, elem_feattype);

    /* 3. Add feature-specific elements... */

    /* 4. Get current model and create selection */
    status = ProMdlCurrentGet(&model);
    status = ProMdlToModelitem(model, &model_item);
    status = ProSelectionAlloc(NULL, &model_item, &model_selection);

    /* 5. Set creation options */
    status = ProArrayAlloc(1, sizeof(ProFeatureCreateOptions), 1, (ProArray*)&options);
    options[0] = PRO_FEAT_CR_DEFINE_MISS_ELEMS;

    /* 6. Create the feature */
    status = ProFeatureWithoptionsCreate(model_selection, feat_elemtree,
        options, PRO_REGEN_NO_FLAGS, &created_feature, &errors);

    /* 7. Cleanup */
    status = ProArrayFree((ProArray*)&options);
    status = ProElementFree(&feat_elemtree);
    status = ProSelectionFree(&model_selection);

    return status;
}

Setting Element Values (Preferred Type-Specific Functions)

/* Integer values */
ProElementIntegerSet(elem, PRO_FEAT_HOLE);

/* Double values */
ProElementDoubleSet(elem, 25.5);

/* Wide string values */
ProName wname;
ProStringToWstring(wname, "MY_FEATURE");
ProElementWstringSet(elem, wname);

/* Reference values (from selections) */
ProReference reference;
ProSelectionToReference(selection, &reference);
ProElementReferenceSet(elem, reference);

/* Collection values */
ProElementCollectionSet(elem, collection);

See references/element-trees.md and references/feature-creation-examples.md for detailed patterns.

Error Handling Pattern

ProError status;
status = ProSomeFunction(...);
if (status != PRO_TK_NO_ERROR) {
    switch (status) {
        case PRO_TK_BAD_INPUTS:
            // Handle invalid inputs
            break;
        case PRO_TK_E_NOT_FOUND:
            // Handle not found
            break;
        default:
            // Handle other errors
            break;
    }
}

Wide Strings

Creo uses wide character strings for internationalization:

wchar_t wname[PRO_NAME_SIZE];
char cname[PRO_NAME_SIZE];

// Convert string to wstring
ProStringToWstring(wname, "MyName");

// Convert wstring to string
ProWstringToString(cname, wname);

// Wide string operations
ProWstringCopy(dest, source, PRO_VALUE_UNUSED);
ProWstringCompare(str1, str2, PRO_VALUE_UNUSED, &result);
int length;
ProWstringLengthGet(wstr, &length);

Reference Files

For detailed information, see:

• references/element-trees.md - Feature creation with element trees
• references/feature-creation-examples.md - Complete feature examples (holes, chamfers, datum points/axes, remove surface)
• references/core-objects.md - Core object types and relationships
• references/common-functions.md - Common function patterns
• references/ui-programming.md - User interface programming
• references/utility-functions.md - ProUtil* helper functions from PTC examples (NOT official API)
• references/layers-relations-materials.md - Layers, relations, parameters, and material operations

Curve and Surface Collections

For features that operate on multiple edges or surfaces (chamfers, rounds, remove surface):

Curve Collection (Edges)

#include <ProCrvcollection.h>

ProCollection collection;
ProCrvcollinstr instr;
ProReference reference;

ProCrvcollectionAlloc(&collection);
ProCrvcollinstrAlloc(PRO_CURVCOLL_ADD_ONE_INSTR, &instr);
ProSelectionToReference(edge_selection, &reference);
ProCrvcollinstrReferenceAdd(instr, reference);
ProCrvcollectionInstructionAdd(collection, instr);

/* Optional: add tangent chain */
ProCrvcollinstrAlloc(PRO_CURVCOLL_ADD_TANGENT_INSTR, &instr);
ProCrvcollectionInstructionAdd(collection, instr);

/* Set in element */
ProElementCollectionSet(elem, collection);

Surface Collection

#include <ProSrfcollection.h>

ProCollection collection;
ProSrfcollinstr instr;
ProReference reference;
ProSrfcollref instr_ref;

ProSrfcollectionAlloc(&collection);
ProSrfcollinstrAlloc(1, PRO_B_TRUE, &instr);
ProSrfcollinstrIncludeSet(instr, 1);

ProSelectionToReference(surface_selection, &reference);
ProSrfcollrefAlloc(PRO_SURFCOLL_REF_SINGLE, reference, &instr_ref);
ProSrfcollinstrReferenceAdd(instr, instr_ref);
ProSrfcollectionInstructionAdd(collection, instr);

Layer Operations

#include <ProLayer.h>

/* Create layer */
ProLayer layer;
layer.owner = model;
ProStringToWstring(layer.layer_name, "MY_LAYER");
ProLayerCreate(&layer);

/* Add item to layer */
ProLayerItem item;
item.type = PRO_FEATURE;
item.id = feature_id;
ProLayerItemAdd(&layer, &item);

/* Set display status */
ProLayerDisplaystatusSet(&layer, PRO_LAYER_TYPE_BLANK);
ProWindowRepaint(-1);

Custom Relation Functions

#include <ProRelSet.h>

/* Register function for use in relations dialog */
ProRelfuncArg *args;
ProArrayAlloc(1, sizeof(ProRelfuncArg), 1, (ProArray*)&args);
args[0].type = PRO_PARAM_DOUBLE;
args[0].attributes = PRO_RELF_ATTR_NONE;

ProRelationFunctionRegister("my_calc", args,
    MyReadFunc,    /* For RHS - returns value */
    MyWriteFunc,   /* For LHS - sets value */
    NULL, PRO_B_FALSE, NULL);

Utility Functions Note

Functions starting with ProUtil* (e.g., ProUtilVectorCross, ProUtilMatrixInvert, ProUtilFeatCreate) are custom helper functions from PTC's example code, NOT official Pro/TOOLKIT API. They are found in headers like UtilMath.h, UtilMatrix.h, UtilFeats.h. To use them, either include the source files from PTC's examples or implement equivalent functionality.

Menu System (Legacy Menus)

For custom menus in Pro/TOOLKIT:

#include <ProMenu.h>

int menu_id;
int action;

/* Register menu from .mnu file */
ProMenuFileRegister("MYMENU", "mymenu.mnu", &menu_id);

/* Set button actions */
ProMenubuttonActionSet("MYMENU", "Option1", MyAction, NULL, 1);
ProMenubuttonActionSet("MYMENU", "Option2", MyAction, NULL, 2);
ProMenubuttonActionSet("MYMENU", "MYMENU", MyMenuExit, NULL, -1);

/* Create and process menu */
ProMenuCreate(PROMENUTYPE_MAIN, "MYMENU", &menu_id);
ProMenuProcess("MYMENU", &action);

/* Action callback */
int MyAction(ProAppData data, int value)
{
    /* Process selection based on value */
    return 0;
}

/* Exit menu */
int MyMenuExit(ProAppData data, int value)
{
    ProMenuDeleteWithStatus(value);
    return 0;
}

Best Practices

1. Always check return status of Pro* functions
2. Free allocated memory - ProArray, ProSelection, ProElement, ProReference, etc.
3. Use PRO_TK_NO_ERROR for success checks
4. Include proper headers - ProToolkit.h first, then object-specific headers
5. Validate wchar_t size with ProWcharSizeVerify() in user_initialize
6. Use DLL mode for production, multiprocess for debugging
7. Unlock applications before distribution with protk_unlock.bat
8. Base makefiles on PTC-provided samples for correct compiler flags
9. Use ProFeatureWithoptionsCreate instead of ProFeatureCreate for better control
10. Use type-specific element setters (ProElementIntegerSet, ProElementDoubleSet) over ProValueData
11. Convert selections to references using ProSelectionToReference for element trees
12. Use PRO_FEAT_CR_DEFINE_MISS_ELEMS option to prompt for missing elements during development
13. **Distinguish ProUtil* functions** - they are NOT official API, come from example code

Common Headers by Task