一文带你全面了解 Microstation 中的 Keyin 配置

发表于 分类于 ， ， 本文字数： 5k 阅读时长 ≈ 5 分钟

本文将详细介绍 Microstation 中 Keyin 的配置，包括 Keyin 命令表的结构、各项参数等等，最后将分享如何通过代码的方式来自动生成 command 表。

Addin 中使用 XML 来定义命令表。

命令表结构

Keyin 命令表结构如下图所示：

keyinCommandStructure

命令表是一个 xml 文件，每个命令表中有且仅有一个 KeyinTree 根节点，其下由三部分组成，分别为 RootKeyinTable、SubKeyinTables 和 KeyinHandlers，它们分别表示根命令表、子命令表以及命令对应的处理函数映射。

command.xml 命令表代码示例如下：

使用 <!--xxx--> 包含的内容为注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?xml version="1.0" encoding="utf-8" ?>
<KeyinTree xmlns="http://www.bentley.com/schemas/1.0/MicroStation/AddIn/KeyinTree.xsd">
  <!--根命令表,其 ID 为 root-->
	<RootKeyinTable ID="rootId">
    <!--使用 keyword 定义根命令,通过 SubtableRef 来指向 KeyinTable 的 ID，指定下一级命令。CommandWord 表示命令的单词(不区分大小写)-->
		<Keyword SubtableRef="CommandsId" CommandWord="fenceExample">
      <!--定义 Keyword 的选项-->
			<Options Required="true" />
		</Keyword>
	</RootKeyinTable>

	<SubKeyinTables>
		<KeyinTable ID="CommandsId">
			<Keyword SubtableRef="FromCmdId" CommandWord="from">
				<Options Required="true" />
			</Keyword>
			<Keyword SubtableRef="ModifyCmdId" CommandWord="modify">
				<Options Required="true" />
			</Keyword>
			<Keyword CommandWord="clear">
				<Options Required="true" />
			</Keyword>
		</KeyinTable>

		<KeyinTable ID="FromCmdId">
			<Keyword CommandWord="element" />
			<Keyword CommandWord="points" />
		</KeyinTable>

		<KeyinTable ID="ModifyCmdId">
			<Keyword CommandWord="move"/>
			<Keyword CommandWord="clip"/>
			<Keyword CommandWord="stretch"/>
    </KeyinTable>
	</SubKeyinTables>

	<KeyinHandlers>
		<KeyinHandler Keyin="fenceExample from element" Function="ManagedFenceExample.Keyin.CmdPlaceFenceFromElement"/>
		<KeyinHandler Keyin="fenceExample from points" Function="ManagedFenceExample.Keyin.CmdPlaceFenceFromPoints"/>
		<KeyinHandler Keyin="fenceExample clear" Function="ManagedFenceExample.Keyin.CmdClearFence"/>
		<KeyinHandler Keyin="fenceExample modify move" Function="ManagedFenceExample.Keyin.CmdMoveFenceContents"/>
		<KeyinHandler Keyin="fenceExample modify clip" Function="ManagedFenceExample.Keyin.CmdClipFenceContents"/>
		<KeyinHandler Keyin="fenceExample modify stretch" Function="ManagedFenceExample.Keyin.CmdStretchFenceContents"/>
	</KeyinHandlers>
</KeyinTree>

上例中的代码命令可以表示为：

keyinCommand结构-代码命令示例

节点标签介绍

KeyinTree 节点包含 RootKeyinTable、SubKeyinTables 和 KeyinHandlers 三个部分。

KeyinTable 中有属性 ID，表示该表的名称。命令表的内容由一个或多个Keyword 元素组成，Keyword属性 SubtableRef 指向其下级命令表的 ID。这样，通过当前表中Keyword 的 SubtableRef 和下级表中 KeyinTable> 的 ID 就能构成一个命令树。

Mstn 中的命令由一到五个单词组成，因而，我们在定义自己的 commands.xml 时在 SubKeyinTables 段中最多可以定义四级命令。

Keyword 还必须有属性 CommandWord，这是用户在 Mstn 键入域中可输入的单词。Keyword 中还可以包含 Options 项，该项是对Keyword的进一步说明，其属性有 Required、Default、TryParse、Hidden 等。

RootKeyinTable

KeyinTree 中必须包含 RootKeyinTable 标签，且只能有一个标签。

RootKeyinTable 中应至少包含一个 Keyword 标签，用于定义根命令单词。

Keyword

Keyword 标签用于定义命令的单词，它可以在 RootKeyinTable 和 KeyinTable 中使用。

Keyword 有如下属性：

属性名称 默认值 可选 作用
SubtableRef - - 指定下一级命令
CommandClass Inherit 是 指定命令类别
CommandWord - 必须 [必须] 用于定义命令单词

其中 CommandClass 属性表示命令的类别，当为 Inherit 时，表示继承上一个命令的类型。除了 Inherit 外，还有以下类别：

Placement、Viewing、Fence、Parameters、Locks、MacroCommand、Manipulation、Show、Plot、Newfile、Measure、Input、Celllib、Filedesign、Compress、Reference、Database、Dimension、Locate、Tutorial、WorkingSet、List、Undo、SubProcess、ViewParam、ViewImmediate、WindowManager、DialogManager

在 Keyword 中，可以添加 Option 标签来对 Keyword 进行设置。Option 标签是可选的，它拥有如下属性：

属性名称 默认值 是否可选
Required false 是
Default false 是
TryParse false 是
Hidden false 是

Required="true" 表示该命令字不是最后一个单词，必须有下级子节点；

Default="true" 表示该命令字为默认，当省略这一级命令字时取该命令字，在同一级别中只能有一个命令字为 Default 。

TryParse="true"表示该命令字后可跟用户输入的任意字符，这些不在命令表中的字符串将被传递到命令处理函数的 unparsed 参数中。比如 Active Color 命令后可跟 Red、Green、Blue 等，也可以跟一个数字，如 Active Color 245。我们不可能在命令表中列出每个这样的键入，此时可用 TryParse 属性。

Hidden="true" 表示该命令隐藏，用户在 Mstn 的命令浏览器中看不到该命令，但该命令仍然有效。这些隐藏的命令往往为程序所用或暂时不想对用户公开。

SubKeyinTables

SubKeyinTables 是可选标签。若命令大于 1 个单词时，需要用 SubKeyinTables 来定义剩余的单词。

SubKeyinTables 最多只能在配置文件中出现 1 次。它下面必须至少有一个 KeyinTable 子节点，每个 KeyinTable 都必须有一个唯一的 ID 属性值。

每个 KeyinTable 中应至少有 1 个 Keyword 子节点。

每个 KeyinTable 中的 Keyword 可以通过 SubtableRef = "ID" 的方式来指定到其它的 KeyinTable，从而形成命令链。

KeyinHandlers

KeyinHandlers 标签中只有 KeyinHandler 一种元素。KeyinHandler 中必须拥有 Keyin 和 Function 两个属性。

KeyinHandler 中的 Keyin 属性表示完整的键入命令字符串， 它的 Function 属性为该键入命令对应的处理函数名，该函数名格式为：命名空间名.类名.函数名(或称方法名) 。换句话说，当用户在 Mstn 中输入 Keyin 中的字符串时，就会调用到 Function 指定的函数。

将命令表嵌入 Addin

若要使命令表能够正确被 Microstsation 识别，需要在项目的工程配置文件 (*.csproj) 中的 Project 节点中增加如下配置：

1
2
3
4
5
6
<ItemGroup>
  <EmbeddedResource Include="填写commands.xml相对于.csproj文件的相对路径">
    <LogicalName>CommandTable.xml</LogicalName>
    <SubType>Designer</SubType>
  </EmbeddedResource>
</ItemGroup>

快速生成命令表

参考

本文参考以下文章，在此致以诚挚谢意！

  1. 自动检查Addin程序中XML格式命令表语法 - 中国BDN社区-博客 - 中国BDN社区 - Bentley Communities
  2. 第4章、给Addins添加命令 - 中国BDN社区-威客 - 中国BDN社区 - Bentley Communities
  3. Learning MicroStation Addins Step by Step 4 - 中国BDN社区-博客 - 中国BDN社区 - Bentley Communities