====== XT Command System ======

XT所有的应用功能都通过命令来Command来实现，Command属于应用层，它并不直接负责UI层与用户的交互，但是它通过UI层的提供的接口定制对话框、响应用户的交互操作以及功能参数与对话框对应控件的匹配更新，它与UI层利用字符串进行消息的传递，并不直接传递参数给控件对象，因此它与UI层是解耦的，在用户完成输入之后点击确认按钮，Command会调用相应的内核API完成功能。下图说明了Command几个典型的应用场景的流程图。

{{ pics:command_loop.png }}

下表这列出了流程图中各环节所对应的Command函数，它们一般需要用户根据功能的具体情况重新实现：
^Action^Function Name^
|设置功能参数| setParam|
|获取对话框配置文件|getUISettingXml|
|通过右键菜单调用时根据节点上下文设置命令参数| setContextParam|
|通过右键菜单调用时检查节点上下文是否匹配命令| checkContextParam|
|初始化对话框|initWindow|
|交换内存数据与对话框控件状态|onDataExchange|
|响应控件的交互事件|onControlEvent|
|检查命令的上下文是否满足命令条件|checkContext|
|执行功能|execute|
|更新框架与视图|updateFrame|
|脚本记录|exchangeScript|

XT所有的命令通过命令管理器注册管理、创建以及销毁。命令的构造函数、析构函数、ID与名字可通过宏REGISTER_CMD完成并与给定文档类型绑定。需要注意的是文档对应的所有命令的对话框配置文件都放置于文档所属的资源目录下的uisetting文件夹，getUISettingXml获取的是相对于该文件夹的相对路径。

XT中命令分为以下几种类型（它通过重新实现函数CommandType getType()指定）：
^类型枚举量^说明^
| Command_Dialog | 普通命令，拥有交互对话框（一般须通过const char * getUISettingXml()指定对话框定制XML文件），用户必须通过对话框完成命令的执行，执行完会保存脚本记录 |
| Command_NoDialog | 无对话框命令，命令执行时保存脚本记录|
| Command_Infinit | 无限交互命令，在命令激活状态下，用户可以连续完成某项操作（如连续选择顶点连成线段）|
| Command_Silent | 静默命令，无对话框且命令执行时不保存脚本记录 |

所有的命令都从ICommand继承，ICommand提供了exchangeParam接口，该接口主要用来完成脚本的记录与解析；提供了onDataExchange接口用来数据与界面更新交互；提供了onControlEvent接口以响应命令对话框的控件事件。\\
命令每次执行完之后会将最后的参数状态写入到%TEMP%/XT/status目录中，XT启动命令时会首先通过接口exchangeParam读取参数值，然后调用initWindow初始化窗口。
命令窗口在与命令交换数据时有两种模式，一种是DX_Get,即窗口界面的数据更新到命令中，另一种是DX_Set,即将命令数据更新到窗口界面中。

针对可编辑对象的定义命令，XT从ICommand继承了对象命令类（ItemCommand），在注册该命令的时候可以将命令与对象类型绑定，在编辑对象的时候，通过实现接口setEditItem将对象数据传入到命令中，从而可以在一套命令代码里同时实现对象的创建、修改，有效提高代码的复用性。特别的，对某些类型的对象，依赖其属性的不同值有不同的界面交互方式，XT从ItemCommand继承实现了CatagoryEditCmd，开发者可以继承CatagoryEditCmd命令对不同的属性值进行命令的分发。

命令提供了一系列宏定义方便开发者交换数据，详细可参见以下章节。

  * [[reference::cmdsys#checkcmd|勾选框命令]]
  * [[reference::cmdsys#combocmd|下拉框命令]]
  * [[reference::cmdsys#editcmd|编辑框命令]]
  * [[reference::cmdsys#cmdui|命令交互]]
  * [[reference::cmdsys#exchangemacro|数据交换宏定义]]
  * [[reference::cmdsys#scriptmacro|脚本宏定义]]

----

{{anchor:combocmd}}
**下拉框命令**
下拉框命令主要用于绑定工具栏上的快捷下拉框，它的命令参数为ComboParam，它必须实现getActionSetting、setParam、getParam接口以为下拉框定制下拉选项json字符串。可参考void CmdSetSearchType::getActionSetting(std::string * setting)。

{{anchor:checkcmd}}
**状态命令**
状态命令主要用于绑定工具栏上的勾选框，它的命令参数为CheckParam，它必须实现setParam、getParam接口以获取或更新勾选框状态。

{{anchor:editcmd}}
**状态命令**
状态命令主要用于绑定工具栏上的编辑框，它的命令参数为EditParam，它必须实现setParam、getParam接口以获取或更新编辑框状态。

{{anchor:cmdui}}
**命令交互**
命令可通过onControlEvent响应用户对控件的交互操作事件，事件类型列举说明如下
^控件事件^触发场景^
| Event_Any | 响应所有交互事件 |
| Event_Clicked |  |
| Event_DblClicked | 双击列表控件子项或树控件的子项 |
| Event_Droped | 拖动某控件到指定控件时触发 |
| Event_EditChanged | 目录输入框当用户选择有效文件或目录时触发 |
| Event_WidgetAction | 当控件通过action关键字被设定右键菜单，用户点击菜单时触发 |
| Event_PanelEnabled | 当面板控件被勾选激活时触发 |
| Event_PanelDisabled | 当面板控件被勾掉失活时触发 |


{{anchor:exchangemacro}}
**数据交换宏定义**
^宏定义^说明^
| DX_Edit | 与编辑框控件交换整形、浮点数、字符串数据 |
| DX_Check | 与勾选框交换布尔型数据|
| DX_Combo | 与下拉框交换整型数据，下拉框每一个选项对应一个整数|
| DX_Edit_Vector3 | 与三个编辑框控件交换矢量数据，编辑框控件名字以给定字符串为前缀分别以.x,.y,.z结尾|
| DX_SubCheck | 与指定容器控件的子勾选控件交换布尔数据|
| DX_UnitEdit | 值经过单位转换之后与编辑框控件交换整形、浮点数、字符串数据，编辑框须指定“unit”属性 |
| DX_UnitEdit_Vector3| 值经过单位转换之后与三个编辑框控件交换矢量数据，编辑框控件名字以给定字符串为前缀分别以.x,.y,.z结尾，编辑框须指定“unit”属性 |

{{anchor:scriptmacro}}
**脚本宏定义**
用于与脚本进行数据传递（Script Exchange）。XT的脚本采用类Json格式，脚本的参数都有一个参数名，参数值可以是整形值、浮点数、布尔值或者字符串，也可以是上述类型的数组（由[]标定），也可以是若干参数组成的结构体（由{}标定)。脚本最多支持一个层次的结构体参数。XT平台提供了下面四种宏方便开发者使用。

^宏定义^说明^示例^
| SX_JParam | 三个参数，分别是脚本类指针、参数名、参数变量 | SX_JParam(param, "name", m_oParam.strName); |
| SX_JParam_Array | 四个参数，分别是脚本类指针、参数名、数组变量、数组个数 | SX_JParam_Array(param, "data", m_oParam.data, 3); |
| SX_JSubParam | 四个参数，分别是脚本类指针、参数结构体名、二级参数名、参数变量 | SX_JSubParam(param, "group1", "name", m_oParam.strName); |
| SX_JSubParam_Array | 五个参数，分别是脚本类指针、参数结构体名、二级参数名、数组变量、数组个数 | SX_JSubParam_Array (param, "group1", "data", m_oParam.data, 3); |