creo-toolkit

Naming Convention

All functions follow: Pro()

```c

ProSolidRegenerate() // Object=Solid, Action=Regenerate

ProFeatureDelete() // Object=Feature, Action=Delete

ProSurfaceAreaEval() // Object=Surface, Action=AreaEval

ProEdgeLengthEval() // Object=Edge, Action=LengthEval

```

Action Verbs

| Verb | Purpose |

|------|---------|

| Get | Read directly from database |

| Set | Write to database |

| Eval | Simple calculation result |

| Compute | Numerical analysis (geometry-based) |

| Visit | Traverse items with callback |

| Create | Create new object |

| Delete | Remove object |

| Alloc/Free | Memory management |

Function Arguments

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

Common Error Codes

```c

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

```

Opaque Handles (OHandle)

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

```c

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:

```c

typedef struct pro_model_item {

ProType type;

int id;

ProMdl owner;

} ProModelitem, ProGeomitem;

```

Converting Between Handles

```c

// OHandle to DHandle

ProSurfaceIdGet(surface, &id);

ProModelitemInit(owner, PRO_SURFACE, id, &modelitem);

// DHandle to OHandle

ProSurfaceInit(modelitem.owner, modelitem.id, &surface);

```

Required Entry Points

```c

#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

| Mode | Description | Use Case |

|------|-------------|----------|

| DLL | Dynamic linking into Creo | Production deployment |

| Multiprocess (spawn) | Separate process | Development/debugging |

| Asynchronous | Independent process | Batch operations |

Pattern for traversing collections:

```c

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

Dynamic arrays for variable-size data:

```c

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);

```

References geometry in assembly context:

```c

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);

```

```c

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);

```

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)

```c

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)

```c

/ 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.

```c

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;

}

}

```

Creo uses wide character strings for internationalization:

```c

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);

```

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

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

Curve Collection (Edges)

```c

#include

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

```c

#include

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);

```

```c

#include

/ 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);

```

```c

#include

/ 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);

```

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.

For custom menus in Pro/TOOLKIT:

```c

#include

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;

}

```

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

| Task | Required Headers |

|------|------------------|

| Feature creation | ProFeature.h, ProElement.h, ProElemId.h, ProFeatType.h, ProFeatForm.h |

| Hole features | ProHole.h |

| Rounds/Chamfers | ProRound.h, ProChamfer.h, ProCrvcollection.h |

| Datum features | ProDtmPln.h, ProDtmAxis.h, ProDtmPnt.h, ProDtmCsys.h |

| Extrusions | ProExtrude.h, ProStdSection.h, ProSection.h |

| Selections | ProSelection.h, ProSelbuffer.h |

| Parameters | ProParameter.h, ProParamval.h |

| Materials | ProMaterial.h, ProMdlUnits.h |

| Layers | ProLayer.h |

| Relations | ProRelSet.h |

| Menus | ProMenu.h, ProMenuBar.h |

| Dialogs | ProUIDialog.h, ProUI*.h |