ProCmdActionAdd 解读

ProCmdActionAdd 是 Creo Toolkit 中用于定义命令的核心函数，允许开发者向 Creo Parametric 添加自定义操作。这些操作可以与 UI 元素（如按钮、菜单项或 Ribbon 命令）关联，当用户与这些元素交互时，绑定的响应函数会被触发，从而实现特定功能。

目录

参数原型

参数详解

 参数扩展介绍

name / action_name

access_cb / access_func 

access_type / priority

示例代码

注意事项

总结

---

参数原型

ProError ProCmdActionAdd (
    ProString name,                  // (In) 操作名称（必须唯一）
    uiCmdCmdActFn,                   // (In) 操作回调函数 action_cb
    uiCmdAccessFn,                   // (In) 访问控制函数 access_cb
    ProCmdAccess,                    // (In) 访问类型 access_type
    ProBoolean allow_in_non_active_window, // (In) 是否允许在非活动窗口中执行
    ProBoolean allow_in_accessory_window, // (In) 是否允许在辅助窗口中执行
    uiCmdCmdId *cmd_id              // (Out) 返回的命令 ID
);

参数详解

参数名	类型	说明
name	ProString	操作的名称，必须是唯一的。
action_cb	uiCmdCmdActFn	操作的回调函数，当操作被触发时调用。
access_cb	uiCmdAccessFn	访问控制函数，用于检查当前状态下是否允许执行该操作。
access_type	ProCmdAccess	访问类型（通常使用 AccessDefault）。
allow_in_non_active_window	ProBoolean	是否允许在非活动窗口中执行该操作：PRO_B_TRUE 允许，PRO_B_FALSE 不允许。
allow_in_accessory_window	ProBoolean	是否允许在辅助窗口中执行该操作：PRO_B_TRUE 允许，PRO_B_FALSE 不允许。
cmd_id	uiCmdCmdId *	返回的命令 ID，用于后续将操作与 UI 元素关联。

 参数扩展介绍

name / action_name

• 描述：命令在 Creo Parametric 中使用的名称。

• 要求：

  • 名称必须是唯一的。

  • 在您的应用程序或 Creo Parametric 中只能出现一次。

• 建议：

  • 为避免冲突，PTC 建议在命令名称前或后添加唯一标识符，例如 ptc_openfile 或 openfile_ptc。

access_cb / access_func 

（access_cb / access_func统称，均代指此位置的参数）

1. 功能描述

• access_func 是一个访问控制函数（回调函数），用于确定菜单按钮是否应显示为可用、不可用或隐藏。

• 作用：

  • 每次显示按钮时，都会调用此函数。

  • 根据按钮按下时的条件评估按钮的可访问性。

2. 函数原型

typedef uiCmdAccessState (*uiCmdAccessFn) (uiCmdAccessMode access_mode);

3. 返回值

返回值在枚举类型 uiCmdAccessState 中定义，可能的取值如下：

返回值	描述
ACCESS_REMOVE	按钮不可见，且如果包含菜单中的所有按钮都返回 ACCESS_REMOVE，则整个菜单可能会被移除。
ACCESS_INVISIBLE	按钮不可见。
ACCESS_UNAVAILABLE	按钮可见，但不可用且无法选择。
ACCESS_DISALLOW	按钮显示为可用，但选择时不会执行命令。
ACCESS_AVAILABLE	按钮可用且用户可以选择。

---

4. 使用场景

• ACCESS_REMOVE：

  • 当按钮不应显示时使用。

  • 如果整个菜单中的所有按钮都返回 ACCESS_REMOVE，则菜单可能会被移除。

• ACCESS_INVISIBLE：

  • 当按钮不应显示，但菜单应保留时使用。

• ACCESS_UNAVAILABLE：

  • 当按钮应显示为灰色（不可用）时使用。

• ACCESS_DISALLOW：

  • 当按钮应显示为可用，但选择时不执行任何操作时使用。

• ACCESS_AVAILABLE：

  • 当按钮应完全可用时使用。

---

5. 示例代码

以下是一个示例，展示如何使用 access_func 控制按钮的可访问性：

#include 
#include 

// 访问控制函数
uiCmdAccessState MyAccessCheck(uiCmdAccessMode access_mode) {
    // 根据条件返回不同的状态
    if (/* 某些条件 */) {
        return ACCESS_AVAILABLE; // 按钮可用
    } else if (/* 其他条件 */) {
        return ACCESS_UNAVAILABLE; // 按钮不可用
    } else {
        return ACCESS_INVISIBLE; // 按钮不可见
    }
}

int main() {
    ProError status;
    uiCmdCmdId cmdId;

    // 初始化 Creo Toolkit
    ProToolkitMain(0, NULL, NULL, NULL, NULL);

    // 定义操作
    status = ProCmdActionAdd(
        "MyAction",                   // 操作名称
        (uiCmdCmdActFn)MyAction,      // 回调函数
        MyAccessCheck,                // 访问控制函数
        AccessDefault,                // 访问类型
        PRO_B_TRUE,                   // 允许在非活动窗口中执行
        PRO_B_TRUE,                   // 允许在辅助窗口中执行
        &cmdId                        // 返回的命令 ID
    );

    if (status != PRO_TK_NO_ERROR) {
        printf("操作定义失败，错误代码：%d\n", status);
    } else {
        printf("操作定义成功！\n");
    }

    // 其他程序逻辑
    return 0;
}

 

6. 注意事项

1. 条件评估：

   • 访问控制函数应根据当前上下文动态评估按钮的可访问性。

2. 性能影响：

   • 访问控制函数会在每次显示按钮时调用，因此应尽量简洁高效。

3. 用户体验：

   • 根据业务逻辑合理设置按钮的可访问性，避免用户困惑。

---

总结

• access_func 用于控制按钮的可访问性，支持多种状态（如可见、不可见、可用、不可用等）。

• 返回值：

  • ACCESS_REMOVE：按钮不可见，菜单可能被移除。

  • ACCESS_INVISIBLE：按钮不可见。

  • ACCESS_UNAVAILABLE：按钮可见但不可用。

  • ACCESS_DISALLOW：按钮显示为可用但不执行命令。

  • ACCESS_AVAILABLE：按钮完全可用。

• 使用场景：

  • 根据业务逻辑动态控制按钮的显示和可用状态。

通过以上解读，开发者可以灵活使用 access_func 参数，实现按钮的动态控制。

access_type / priority

• 描述：命令的优先级。操作的优先级指的是添加的操作相对于其他 Creo Parametric 操作的优先级别。

• 优先级定义：

  • 优先级在枚举类型 uiCmdPriority 中定义，可能的取值如下：

    typedef int uiCmdPriority;
    #define uiCmdPrioDefault      ((uiCmdPriority) 0)
    #define uiProeImmediate       ((uiCmdPriority) 2)
    #define uiProeAsynch          ((uiCmdPriority) 3)
    #define uiProe2ndImmediate    ((uiCmdPriority) 5)
    #define uiProe3rdImmediate    ((uiCmdPriority) 6)
    #define uiCmdNoPriority       ((uiCmdPriority) 999)

    详细说明：

    • uiCmdPrioDefault：默认优先级，适用于大多数常规命令。

    • uiProeImmediate：立即执行优先级。

    • uiProeAsynch：异步执行优先级，独立于其他操作。

    • uiProe2ndImmediate：第二级立即执行优先级。

    • uiProe3rdImmediate：第三级立即执行优先级。

    • uiCmdNoPriority：无优先级。

uiProeImmediate、uiProe2ndImmediate 和 uiProe3rdImmediate

• 描述：普通优先级操作，会取消所有其他操作（异步操作除外）。

• 说明：

  • 这些优先级的按钮可能会导致 Menu Manager 菜单 被取消。

  • 取消这些菜单可能会导致依赖于 Creo Parametric 会话模式和上下文的函数出现意外行为。

  • 例如，当从活动的简化表示中选择对象时，ProSelect() 函数可能会表现出意外行为。

  • 建议：

    • 如果菜单按钮依赖于 Creo Parametric 会话的上下文，应使用较低的优先级。

示例代码

以下是一个完整的示例，展示如何使用 ProCmdActionAdd 定义操作并将其与按钮关联：

#include 
#include 
#include 

// 回调函数
void MyAction(uiCmdCmdId command, uiCmdValue *p_value) {
    printf("操作已触发！\n");
}

// 访问控制函数
ProBoolean MyAccessCheck(uiCmdCmdId command, ProAppData data) {
    return PRO_B_TRUE; // 允许执行
}

int main() {
    ProError status;
    uiCmdCmdId cmdId;

    // 初始化 Creo Toolkit
    ProToolkitMain(0, NULL, NULL, NULL, NULL);

    // 定义操作
    status = ProCmdActionAdd(
        "MyAction",                   // 操作名称
        (uiCmdCmdActFn)MyAction,      // 回调函数
        MyAccessCheck,                // 访问控制函数
        AccessDefault,                // 访问类型
        PRO_B_TRUE,                   // 允许在非活动窗口中执行
        PRO_B_TRUE,                   // 允许在辅助窗口中执行
        &cmdId                        // 返回的命令 ID
    );

    if (status != PRO_TK_NO_ERROR) {
        printf("操作定义失败，错误代码：%d\n", status);
    } else {
        printf("操作定义成功！\n");
    }

    // 其他程序逻辑
    return 0;
}

注意事项

1. 操作名称唯一性：

   • 确保 name 是唯一的，否则会返回 PRO_TK_E_FOUND 错误。

2. 回调函数：

   • 回调函数应尽量简洁，避免长时间阻塞主线程。

3. 访问控制函数：

   • 如果不需要复杂的权限检查，可以将 access_cb 设置为 NULL，并使用 AccessDefault。

4. 命令 ID：

   • 返回的命令 ID（cmd_id）用于后续将操作与 UI 元素关联。

总结

• 功能：ProCmdActionAdd 用于定义操作，并绑定回调函数和访问控制函数。

• 核心参数：

  • name：操作名称，必须唯一。

  • action_cb：回调函数，定义操作触发时的逻辑。

  • access_cb：访问控制函数，控制操作的可执行性。

  • cmd_id：返回的命令 ID，用于后续将操作与 UI 元素关联。

• 返回值：需根据返回值判断函数执行是否成功，并处理可能的错误。