catia宏编写助手

概述

CATIA 宏开发助手

编写、调试和优化 CATIA V5/V6 自动化宏（CATScript/VBScript/VBA）。

Core Principles

CATScript vs VBScript vs VBA

• CATScript — Dassault's legacy scripting language, processed by stripping type info then running through VBScript engine. Has the MOST restrictions.
• VBScript — Standard Windows scripting, runs inside CATIA. Fewer restrictions than CATScript.
• VBA — Full Visual Basic for Applications, most capable. Use when complex type declarations are needed.

Default choice: Write as CATScript (.CATScript files) unless the user specifies otherwise. CATScript is the most widely compatible format but has critical limitations.

Critical CATScript Limitations (MUST follow)

These are hard limitations of the CATIA VBScript engine. Violating ANY of these will cause runtime errors. Every single one below has been verified to cause real failures in production. Do NOT assume "maybe it works".

1. NO GoTo across procedure boundaries or nested blocks
   • GoTo CANNOT jump into or out of For/If/Do blocks
   • GoTo within the same block level is OK (e.g., skip to end of a Sub)
   • Workaround: Use If/ElseIf/Else or boolean flag variables instead of GoTo for flow control
2. NO For Each...Next on CATIA collections
   • CATIA's collection objects do not support For Each enumeration
   • Workaround: Always use For i = 1 To Collection.Count ... Set obj = Collection.Item(i) ... Next
3. Next must NOT have a variable name
   • Next i → RUNTIME ERROR
   • Use bare Next only
4. NO Format() function
   • Format(value, "0.00") → Type mismatch error
   • CStr(value) is also unreliable for formatting
   • Workaround: Use string concatenation with &, or build formatting manually
5. NO As Type in Dim
   • Dim x As Integer → Syntax error in CATScript
   • Use Dim x (all variables are Variant)
6. NO On Error GoTo label
   • On Error GoTo ErrorHandler → Not supported
   • Only On Error Resume Next and On Error GoTo 0
7. Dim inside blocks
   • CATScript processes Dim as if all are hoisted to procedure top
   • Inline Dim works but without types; safer to declare all at top
8. NO CreateObject("Scripting.FileSystemObject")
   • May fail or be restricted. Use CATIA.FileSystem instead for file operations.
9. NO Type … End Type (user-defined types)
   • Not supported in CATScript. Use Classes or parallel arrays instead.
10. Array function limitations
    • Array() works but returns a Variant array
    • ReDim Preserve works
    • No multi-dimensional array literals
11. String functions are VBScript subset
    • InStr, Left, Right, Mid, Len, Replace, Split, Join — all work
    • StrConv — NOT supported
    • Like operator — NOT supported

Variable Naming Conventions

Standard Macro Structure

' ============================================
' Purpose: Brief description
' File: MacroName.CATScript
' ============================================

Sub CATMain()
    On Error Resume Next
    
    ' Get CATIA application
    Dim oCATIA
    Set oCATIA = CATIA
    
    ' Get active document
    Dim oDoc
    Set oDoc = oCATIA.ActiveDocument
    
    ' ... macro logic ...
    
    On Error GoTo 0
End Sub

Error Handling Pattern

' Disable auto error handling only when needed
On Error Resume Next
Dim result
result = someObject.SomeMethod()
If Err.Number <> 0 Then
    ' Handle error
    On Error GoTo 0
    MsgBox "Error: " & Err.Description
    Exit Sub
End If
On Error GoTo 0

String Formatting (NO Format())

' WRONG - causes type mismatch in CATScript:
MsgBox Format(value, "0.00")

' CORRECT - use concatenation:
MsgBox "Value: " & value

Collection Iteration Pattern

' WRONG - For Each doesn't work in CATScript:
For Each oView In oViews
    ...
Next

' CORRECT - use index-based loop:
Dim i
For i = 1 To oViews.Count
    Set oView = oViews.Item(i)
    ...
Next

API Reference Structure

The references/interfaces/ directory contains the complete CATIA V5 Automation IDL documentation, merged into plain text files by framework. Each file contains all interface definitions for that framework:

Each interface is separated by === interface_<Name> === markers. Search for interface_<InterfaceName> to find a specific API.

DraftingInterfaces (Drawing/Drafting)

Core object hierarchy:

CATIA.Application
  └── DrawingDocument
        └── DrawingRoot
              ├── Sheets (DrawingSheets)
              │     └── DrawingSheet (ActiveSheet)
              │           ├── Views (DrawingViews)
              │           │     └── DrawingView
              │           │           ├── Components (DrawingComponents)
              │           │           │     └── DrawingComponent
              │           │           ├── Dimensions (DrawingDimensions)
              │           │           │     └── DrawingDimension
              │           │           ├── Texts (DrawingTexts)
              │           │           │     └── DrawingText
              │           │           ├── Tables (DrawingTables)
              │           │           │     └── DrawingTable
              │           │           ├── Leaders (DrawingLeaders)
              │           │           ├── Arrows (DrawingArrows)
              │           │           ├── GDTs (DrawingGDTs)
              │           │           ├── Weldings (DrawingWeldings)
              │           │           ├── Threads (DrawingThreads)
              │           │           ├── Pictures (DrawingPictures)
              │           │           └── GenerativeBehavior
              │           └── DrawingPageSetup
              └── Parameters / Relations

Key interfaces to search in references/interfaces/DraftingInterfaces.txt:

• interface_DrawingSheet — GetPaperHeight(), GetPaperWidth(), Scale, etc.
• interface_DrawingView — x, y coordinates, GenerativeBehavior, lock status
• interface_DrawingComponent — Name, x, y, referenced view
• interface_DrawingComponents — Count, Item()
• interface_DrawingText — Text content, position, properties
• interface_DrawingTable — Table manipulation
• interface_DrawingDimension — Dimension properties
• interface_DrawingRoot — ActiveSheet, Sheets, Update, Isolate
• interface_DrawingDocument — DrawingRoot access
• interface_DraftingSettingAtt — Drafting settings

InfInterfaces (Infrastructure)

在 references/interfaces/InfInterfaces.txt 中搜索：

• interface_Application — CATIA.Application root
• interface_Document — Document base class
• interface_Documents — Open, Add, Item
• interface_Selection — User selection management
• interface_Window, interface_Windows — Window management
• interface_VisPropertySet — Color, line width, visibility

PartInterfaces (Part Design)

• Part, Bodies, Sketches, HybridShapes, etc.

ProductStructureInterfaces (Assembly)

• Product, Products, Constraints, etc.

MecModInterfaces (Mechanical Modeler)

• Sketcher, Factory2D, GeometricElements, etc.

Drafting2DLInterfaces (2D Layout for 3D Design)

• Layout2DRoot, Layout2DSheet, Layout2DView, Layout2DFactory

Searching the API Reference

To find a specific API method or property:

1. 在对应框架的 txt 文件中搜索 — 用 grep 或文本搜索工具在 references/interfaces/ 目录下搜索
2. 按接口名搜索 — 搜索 === interface_<InterfaceName> 定位到具体接口
3. 按方法名搜索 — 搜索方法名（如 GetPaperHeight、Add、Item）

搜索示例：

# 在 Drawing 文档中查找 GetPaperHeight
search: GetPaperHeight in references/interfaces/DraftingInterfaces.txt

# 查找所有 Component 相关接口
search: interface_DrawingComponent in references/interfaces/DraftingInterfaces.txt

# 查找枚举值
search: CatDrawingViewType in references/interfaces/DraftingInterfaces.txt

Macro Examples

所有宏示例合并保存在 references/macros/_all_examples.txt，每个宏用 === 文件名 === 分隔。

包含 11 个官方示例（Drafting + 2D Layout）：

Drawing/Drafting 示例：

• CAADriCreateView.CATScript — 在新图纸中创建生成视图
• CAADriSheet.CATScript — 创建和切换图纸页
• CAADriDetailSheet.CATScript — 创建细节图纸页
• CAADriDimension.CATScript — 创建尺寸标注
• CAADriDrawingTable.CATScript — 操作图纸表格
• CAADriInstantiateOuterDitto.CATScript — 实例化 2D 组件（外部 ditto）
• CAADriInstantiateInnerDitto.CATScript — 实例化 2D 组件（内部 ditto）
• CAADriDuplicateAView.CATScript — 复制视图
• CAADriSetPrintArea.CATScript — 设置打印区域
• CAADriUpdateSheets.CATScript — 更新图纸页

2D Layout 示例：

• CAA2dlIPrint2DLayout.CATScript — 打印 2D Layout

Known Pitfalls from Real-World Usage

These are NOT theoretical — every item below caused actual failures during macro development and debugging.

API Limitations

1. DrawingComponent.GetRealColor() does NOT work — Color reading fails silently. Returns wrong values or errors. Workaround: match by name prefix instead of color filtering.
2. DrawingSheet.GetPaperDimensions() does NOT exist — This method is not available on DrawingSheet. Use GetPaperHeight() and GetPaperWidth() separately.
3. DrawingSheet.GetPaperHeight() / GetPaperWidth() — These DO work — They return the paper size in millimeters as Double. Note: the "height" is the actual sheet height regardless of landscape/portrait orientation. For example, A3 landscape has height=297 (the short side).
4. View coordinates are relative to the Sheet origin — To get absolute sheet position: SheetX = View.x + Component.x, SheetY = View.y + Component.y.
5. 2D Component naming after Instantiate — Base name 2D Component.a becomes 2D Component.a.1, 2D Component.a.2, etc. Use prefix matching: Left(name, Len(prefix)) = prefix.
6. PaperSize enum values don't always match orientation — Always call GetPaperHeight() at runtime instead of relying on enum assumptions.

Language / Engine Pitfalls

1. MsgBox/InputBox only accept Strings — Always use CStr() to convert numbers before passing to MsgBox/InputBox. Passing a Double directly may cause type mismatch.
2. VBScript Select Case is case-insensitive — But CATIA object names (e.g., 2D Component.a) ARE case-sensitive. Do not rely on Select Case for name matching.
3. Dictionary object — CreateObject("Scripting.Dictionary") works in CATScript and is the recommended way to do key-value lookups, deduplication, and sorted grouping.
4. Chr() function — Chr(65) returns "A", works fine. But for Unicode characters beyond 255, use ChrW().

Coordinate System Notes

1. CATIA Drawing coordinate system — Origin (0,0) is at bottom-left of the sheet. X increases rightward, Y increases upward. This is standard mathematical orientation, NOT screen coordinates.
2. Custom coordinate overlay — When building custom zone grids (e.g., A1-Z99), the origin offset and grid spacing depend on paper size. Always read paper height at runtime with GetPaperHeight() rather than hardcoding.