SAM GUI、Toolset 与交互类 API / SAM GUI, Toolset, and Interaction APIs

本篇只讨论 SAM 的窗口、模块、工具集、菜单、Form 和 Dialog。启动与插件扫描见 09-sam-secondary-development-guide.md，Python/PYD 见 11-sam-command-python-pyd-api.md。

1. GUI 类层次

QApplication
  `-- SAMApp

RibbonMainWindow
  `-- SAMMainWindow
        `-- SAMBasicMainWindow

SAMGuiObjectManager
  +-- SAMModuleGui
  `-- SAMToolsetGui

SAMMode
  `-- SAMGuiMode
        `-- SAMForm
              `-- SAMCreateEditForm

QDialog
  `-- SAMDialog
        `-- SAMDataDialog

Module 表示 Part、Mesh、Job 等工作环境；Toolset 表示可复用的菜单、工具栏和业务工具；Form/Mode 控制一次操作的生命周期；Dialog 只负责界面和输入。

2. 应用和主窗口

2.1 SAMApp

继承 QApplication，管理 SAM GUI 生命周期和 Kernel 初始化。

static SAMApp* getSAMApp();
SAMMainWindow* getSAMMainWindow();
QString getProductName() const;
void getVersionNumbers(int&, int&, int&) const;
QString getKernelInitializationCommand() const;
void init();
void create();
void lock();
void unlock();
bool isLocked() const;
int run();
void refreshWindow();
void refresh();
int completeStartup();

• init()：初始化 Kernel、Python 和基础服务。
• create()：完成主窗口、模块和插件 GUI 的创建。
• run()：进入 Qt 事件循环。
• lock()/unlock()：控制 GUI 可操作状态，不能代替线程管理。

2.2 SAMMainWindow

SAM 主窗口高层接口，管理 Module、Toolset、消息区、CLI、画布和 Form。

void registerToolset(SAMGuiObjectManager*, uint opts);
SAMModuleGui* getModule(const QString&) const;
QObjectList getModules() const;
void writeToMessageArea(...);
void printPyLog(...);
void writeToCliOutput(...);
SAMForm* i_getForm(...);
SAMProcedureForm* i_getProcedureForm(...);
SAMGuiMode* i_getProcedure(...);
void i_showToolsets();

2.3 SAMBasicMainWindow

customApp.py 实际创建的主窗口实现。

void create();
void registerModule(const QString& displayedName,
                    const QString& moduleName,
                    const QString& initCommand);
void registerModule(const QString& displayedName,
                    const QString& moduleName);
SAMModuleGui* getModule(const QString&) const;
int getNumModules() const;
QMenuBar* getMenubar() const;
SAMMenu* getToolMenuPane() const;
QWidget* getToolbox() const;
SAMPromptArea* getPromptArea() const;
void writeToMessageArea(const QString&);
void printPyLog(const QString&);
void writeToCliOutput(const QString&);
void hideCli();
void showCli();
void hideMessageArea();
void showMessageArea();
QWidget* appendTreeTab(...);
QWidget* i_getCanvas() const;
void addCanvasArea(...);
void setCanvasArea(...);
void i_showToolsets();

3. Module 与 Toolset

3.1 SAMGuiObjectManager

Module 和 Toolset 共用的 GUI 管理基类。

位置标志：

GUI_IN_NONE
GUI_IN_MENUBAR
GUI_IN_TOOL_PANE
GUI_IN_TOOLBAR
GUI_IN_TOOLBOX
GUI_IN_ALL

主要 API：

void hide(uint location);
void show(uint location);
QString getKernelInitializationCommand() const;
SAMForm* getForm(...);
SAMProcedureForm* getProcedureForm(...);
SAMGuiMode* getProcedure(...);
void i_addForm(SAMForm*);
void i_cancelAllForms();
static bool i_addImportModule(const char*);
SAMToolbarGroup* getToolbarGroup(...);
void sendCommandString(const QString&, bool replay, bool journal);

3.2 SAMModuleGui

代表一个工作模块。Module 切换时会控制相应 Toolset、菜单、树页签和显示对象类型。

QString getModuleName() const;
static SAMModuleGui* getCurrentModuleGui();
void hide(uint);
void show(uint);
void doCustomTasks();
QObjectList getToolsets() const;
SAMForm* getForm(...);
SAMProcedureForm* getProcedureForm(...);
SAMGuiMode* getProcedure(...);
QString getToolsetKernelInitializationCommands() const;
void registerToolset(SAMToolsetGui*, uint opts);
void unregisterToolset(const QString&);
uint getTypesToDisplay() const;

常见显示类型包括 PART、ASSEMBLY、ODB、XY_PLOT、SKETCH。

3.3 SAMToolsetGuiInterface

Qt 插件壳必须实现的接口：

class SAMToolsetGuiInterface
{
public:
    virtual ~SAMToolsetGuiInterface() {}
    virtual void registerToolset() = 0;
};

#define SAMToolsetGuiPlugin_iid "SAM.Pre.ToolsetGuiPlguin"
Q_DECLARE_INTERFACE(SAMToolsetGuiInterface,
                    SAMToolsetGuiPlugin_iid)

registerToolset() 是插件被发现后进入 SAM 注册流程的入口。

3.4 SAMToolsetGui

业务工具集的基类。

SAMToolsetGui(const QString& toolsetName);
void addMenuObject(QMenu*);
void addToolbarGroup(QToolBar*);
void addToolboxGroup(QWidget*);
void hide(uint location);
void show(uint location);
void activate();
void deactivate();
QString getToolsetName() const;
void i_suspendFormsAndDialogs();

典型派生类负责：

1. 创建菜单和 Action；
2. 创建工具栏/Toolbox；
3. 连接 Qt 信号槽；
4. 创建或激活业务 Form；
5. 随 Module 切换显示或隐藏。

4. 菜单类

4.1 SAMMenu

继承 QMenu：

SAMMenu(SAMGuiObjectManager* owner,
        const QString& title,
        SAMMenu* parent = nullptr);

owner 让菜单进入 SAM 的可见性、生命周期和快捷键管理体系。

4.2 SAMMenuCommand

继承 QAction：

SAMMenuCommand(owner, parent, label, icon);
SAMMenuCommand(owner, parent, label);
void i_setAccelerator(const QString&);

注册菜单的基本写法：

SAMMenu* toolsMenu = new SAMMenu(this, tr("&Tools"));
SAMMenuCommand* command =
    new SAMMenuCommand(this, toolsMenu, tr("&Run Command"));

toolsMenu->addAction(command);

connect(command, &QAction::triggered,
        this, &YourToolsetGui::onRunCommand);

菜单注册本身由 DLL 完成。槽函数可以只弹 Qt 窗口，也可以启动 Form，或向 Kernel 发送 Python 命令。

5. Mode 与 Form

5.1 SAMGuiMode

Mode 是一次交互操作的控制器，拥有命令列表、当前 Dialog 和状态。

SAMGuiMode(SAMGuiObjectManager* owner);
SAMGuiObjectManager* getOwner() const;
virtual void activate();
virtual void deactivate();
virtual int commit() = 0;
virtual int continueMode() = 0;
virtual void cancel(QObject* target = 0,
                    const char* message = 0);
void setModeName(const QString&);
QString getModeName() const;
SAMDialog* getCurrentDialog() const;
bool isKeyword(QObject*) const;
virtual bool okToCancel();
virtual int onCmdCommit(int);
virtual int onCmdGetNext(int);
virtual bool issueCommands(bool replay = true,
                           bool journal = false);
virtual QString getCommandString();
virtual void sendCommandString(const QString&,
                               bool replay,
                               bool journal);
virtual bool doCustomChecks();
virtual void doCustomTasks();

典型生命周期：

activate
  -> 创建/显示第一个 Dialog
  -> 用户修改输入
  -> Apply/OK
  -> onCmdCommit
  -> verifyKeywordValues/doCustomChecks
  -> getCommandString
  -> issueCommands/sendCommandString
  -> Kernel 返回
  -> doCustomTasks
  -> 保持 Dialog 或 deactivate

5.2 SAMForm

继承 SAMGuiMode，用于有 Dialog 的命令流程。

SAMForm(SAMGuiObjectManager* owner);
void activate();
int commit();
int continueMode();
void cancel(...);
void setModal(bool);
int onCmdActivate(...);
int onCmdSuspend(...);
int onCmdResume(...);
virtual SAMDialog* getFirstDialog() = 0;
virtual SAMDialog* getNextDialog(...);
bool issueCommands(...);

5.3 SAMCreateEditForm

为创建和编辑两种场景提供公共参数处理：

enum Mode { CREATE, EDIT };
SAMCreateEditForm(SAMGuiObjectManager*, Mode);
Mode getExecutionMode() const;
int getNumArguments() const;
QString getArgument(int) const;
QString getArguments() const;

6. Dialog

6.1 SAMDialog

继承 QDialog，负责标准 Action Area。

标准按钮：

APPLY, CANCEL, CONTINUE, DEFAULTS, DISMISS,
NO, OK, YES, YES_TO_ALL

点击结果 ID：

ID_CLICKED_OK
ID_CLICKED_CONTINUE
ID_CLICKED_APPLY
ID_CLICKED_DEFAULTS
ID_CLICKED_CANCEL
ID_CLICKED_DISMISS

主要 API：

virtual void showModal();
virtual void show();
virtual void onActionButtonClicked(int);
virtual void onCmdDismiss(int);
virtual bool bailout();
QAbstractButton* appendActionButton(ButtonID);
QAbstractButton* appendActionButton(const QString&);
QAbstractButton* getActionButton(int id) const;

创建 OK、Apply、Cancel：

SAMDialog(owner,
          tr("Parameters"),
          SAMDialog::OK |
          SAMDialog::APPLY |
          SAMDialog::CANCEL);

6.2 SAMDataDialog

继承 SAMDialog，保存宿主 SAMGuiMode，把按钮操作交给 Mode。

SAMGuiMode* getMode() const;
virtual void onActionButtonClicked(int);
virtual void onCmdApply(int);
virtual void onCmdCancel(int);
virtual void onCmdContinue(int);
virtual void onCmdDefaults(int);
virtual void onCmdOk(int);
virtual bool bailout();
virtual void reject();
virtual void processUpdates();
void setMode(SAMGuiMode*);
void updateKeywordActivationState();

Apply 和 OK 的重要区别：

• Apply：提交当前输入，通常不关闭 Dialog。
• OK：提交当前输入，成功后通常关闭 Dialog 或进入下一阶段。
• 按钮只负责触发，真正业务提交应由 Mode/Form 管理。

7. GUI 开发边界

GUI DLL 适合：

• 菜单、按钮、面板、弹窗；
• 参数输入、控件联动；
• 当前 Module、Viewport、选区上下文；
• 命令发送、结果弹窗和 Message Area；
• 临时显示、高亮与视口刷新。

GUI DLL 不适合直接堆放：

• 大规模网格遍历；
• 跨多个 Model/Part 的复杂持久修改；
• 需要脚本重复调用的核心算法；
• 长时间阻塞 Qt 主线程的任务。

这些逻辑应放到 Python 编排层、PYD 或独立算法库。