Add-ins support typing commands. With the popularity of XML, the command table defined in Add-ins no longer uses the format of the resource file table in the MDL but it is now defined in the XML format. One of the main contents of this part is to introduce the format of the XML command table in detail. Second, how to embed the command table in the Add-in program and how to write commands in the Add-in program.

The following is an analysis and description of a specific XML format command table. The command list comes from \ Bentley\ MicroStationCONNECTSDK\ examples\ Elements\ ManagedFenceExample\ commands.xml in the MicroStation SDK.

There is one and only one KeyinTree node in each command table, and there are three parts under it, namely RootKeyinTable, SubKeyinTables, and KeyinHandlers, which respectively represent the root key-in table, sub-key-in table, and the name of the processing function corresponding to the command key-in.

 

<?xml version="1.0" encoding="utf-8" ?>
<KeyinTree xmlns="http://www.bentley.com/schemas/1.0/MicroStation/AddIn/KeyinTree.xsd">

    <RootKeyinTable ID="root">
        <Keyword SubtableRef="Commands" CommandWord="FENCEEXAMPLE">
            <Options Required="true" />
        </Keyword>
    </RootKeyinTable>

    <SubKeyinTables>
        <KeyinTable ID="Commands">            
            <Keyword SubtableRef="FromCmd" CommandWord="FROM">
                <Options Required="true" />
            </Keyword>
          <Keyword SubtableRef="ModifyCmd" CommandWord="MODIFY">
            <Options Required="true" />
          </Keyword>
          <Keyword CommandWord="CLEAR">
            <Options Required="true" />
          </Keyword>
        </KeyinTable>

        <KeyinTable ID="FromCmd">
          <Keyword CommandWord="ELEMENT" />
          <Keyword CommandWord="POINTS" />
        </KeyinTable>

      <KeyinTable ID="ModifyCmd">
        <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>

There are attribute IDs in <RootKeyinTable> and <KeyinTable>, indicating the name of the table. The content of the command table consists of one or more <Keyword> elements, and the <Keyword> attribute SubtableRef points to the ID of its subordinate command table. In this way, a command tree can be formed by the SubtableRef of <Keyword> in the current table and the ID of <KeyinTable> in the lower table. The commands in MicroStation consist of one to five words, so we can define up to four levels of commands in the <SubKeyinTables> section when defining our own commands.xml. <Keyword> must also have the property CommandWord, which is the word that the user can enter in the MicroStation Typing field. <Keyword> has a property CommandClass which represents the command category corresponding to the key-in command.

The currently supported command categories are Placement, Viewing, Fence, Parameters, Locks, MacroCommand, Manipulation and so on. The command category can also be Inherit, which represents the command category to which the last command word belongs. <Keyword> can also contain <Options> items. This item is a further description of <Keyword>. Its properties are Required, Default, TryParse, Hidden, and so on. Required="true" indicates that the command word is not the last word and must have a lower child node; Default="true" indicates that the command word is the default. When the command word is omitted, the command word is taken, only at the same level can have a command word Default. TryParse="true" indicates that the command word can be followed by any character entered by the user. These strings that are not in the command table are passed to the unparsed parameter of the command handler. For example, the Active Color command can be followed by Red, Green, Blue, etc, or a number, such as Active Color 245. Hidden="true" indicates that the command is hidden, and the user cannot see the command in the command browser of MicroStation, but the command is still valid. These hidden commands are often used by programs or temporarily do not want to be made public to users.

The <KeyinHandlers> section has only <KeyinHandler> elements. The Keyin attribute indicates a complete key-in command string, and the Function attribute of <KeyinHandler> is the processing function name corresponding to the key-in command. The function name consists of a namespace name, a class name, and a function name (or a method name). In other words, when the user enters a string in Keyin in MicroStation, the function specified by Function attribute is called.

Let's take a step-by-step approach to transform csAddins to support typing commands.

1. In the Solution Explorer, find the commands.xml.

2.  Copy and paste the contents of the following command list into your commands.xml file.

 

<?xml version="1.0" encoding="utf-8" ?>
<KeyinTree xmlns="http://www.bentley.com/schemas/1.0/MicroStation/AddIn/KeyinTree.xsd">
  <RootKeyinTable ID="root">
    <Keyword SubtableRef="CreateElement"
            CommandClass="MacroCommand" CommandWord="csAddins" >
      <Options Required="true"/>
    </Keyword>
  </RootKeyinTable>
  
  <SubKeyinTables>
    <KeyinTable ID="CreateElement">
      <Keyword SubtableRef="Commands" CommandWord="CreateElement">
        <Options Required="true"/>
      </Keyword>
    </KeyinTable>
    <KeyinTable ID="Commands">
      <Keyword CommandWord="LineAndLineString1"> </Keyword>
      <Keyword CommandWord="LineAndLineString2"> </Keyword>
      <Keyword CommandWord="LineAndLineString3"> </Keyword>
      <Keyword CommandWord="ShapeAndComplexShape"> </Keyword>
      <Keyword CommandWord="TextString"> </Keyword>
      <Keyword CommandWord="Cell"> </Keyword>
      <Keyword CommandWord="Dimension"> </Keyword>
      <Keyword CommandWord="BsplineCurve"> </Keyword>
      <Keyword CommandWord="Cone"> </Keyword>
    </KeyinTable>
  </SubKeyinTables>
  
  <KeyinHandlers>
    <KeyinHandler Keyin="csAddins CreateElement LineAndLineString1"
        Function="csAddins.CreateElement.LineAndLineString1"/>
    <KeyinHandler Keyin="csAddins CreateElement LineAndLineString2"
        Function="csAddins.CreateElement.LineAndLineString2"/>
      <KeyinHandler Keyin="csAddins CreateElement LineAndLineString3"
          Function="csAddins.CreateElement.LineAndLineString3"/>
      <KeyinHandler Keyin="csAddins CreateElement ShapeAndComplexShape"
          Function="csAddins.CreateElement.ShapeAndComplexShape"/>
      <KeyinHandler Keyin="csAddins CreateElement TextString"
          Function="csAddins.CreateElement.TextString"/>
      <KeyinHandler Keyin="csAddins CreateElement Cell"
          Function="csAddins.CreateElement.Cell"/>
      <KeyinHandler Keyin="csAddins CreateElement Dimension"
          Function="csAddins.CreateElement.Dimension"/>
      <KeyinHandler Keyin="csAddins CreateElement BsplineCurve"
          Function="csAddins.CreateElement.BsplineCurve"/>
  </KeyinHandlers>
</KeyinTree>

3. Right-click commands.xml in the solution browser and select the Properties menu to open the properties window, and set the Build Action to Embeded Resource. In this way, the command.xml file will be embedded in csAddins.dll. 

4. Make two changes to csAddins.cs: a) Add the AddIn attribute definition before the class MyAddin line and specify MdlTaskID b) Comment or delete all the contents of the Run function, leaving only the return 0 line. The modified class definition is as follows:

 

[AddIn(MdlTaskID = "csAddins")]
    internal sealed class MyAddin : AddIn
    {
        public static MyAddin Addin = null;

        private MyAddin(System.IntPtr mdlDesc) : base(mdlDesc)
        {
            Addin = this;
        }

        protected override int Run(string[] commandLine)
        {
            return 0;
        }
    }

5. Modify the description of each function in CreateElement.cs to have a string type parameter. Such as:

 

public static void LineAndLineString1(string unparsed)
{
    ……
}
public static void ShapeAndComplexShape(string unparsed)
{
    ……
}

6. Generate the project in VS, and then switch to MicroStation to load the csAddins assembly. As we have deleted all the execution statements in the Run function in MyAddins.cs, no graphics were drawn after the assembly was loaded.

7. Open the Key-in input dialog box and enter csAddins, and you will see the command input tree as shown in the figure below, which corresponds exactly to what we have in commands.xml. At this time, input one of the commands and press Enter to draw the corresponding part of the graph.

 

Prev:[[Run and debug Add-ins]]

Next:[[Adding Windows Forms to Add-ins]]