Welcome to the world of MicroStation Python! Enhancing your application's functionality with keyin command support allows users to execute custom commands. In this wiki, we will guide you through the process of adding keyin command support to MicroStation using Python.

Add Keyin Command Support

Let us dive into creating and registering keyins within MicroStation. Refer to the Python Manager wiki to create and load a python project. Name your project as "MyReport.py" and save it to your preferred directory. Open the project in the editor for writing your Python script.

Building the XML Command Table

First, we need to create an XML command table named MyReport.commands.xml. This XML file will define the commands that we want to add to MicroStation. The format of the XML file is well-documented in the link Adding Commands to Add-ins.

The XML file defines three commands: ReportLevels, ReportTextStyles and ReportFonts each associated with a keyin string. Below is a fully completed example of the XML command table.

<?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="MyDgnReport" CommandClass="MacroCommand" 
                 CommandWord="MYREPORT">
            <Options Required="true" />
        </Keyword>
    </RootKeyinTable>

    <SubKeyinTables>
        <KeyinTable ID="MyDgnReport">
            <Keyword CommandWord="LEVELS" />
            <Keyword CommandWord="TEXTSTYLES" />
	    <Keyword CommandWord="FONTS" />
        </KeyinTable>
    </SubKeyinTables>

    <KeyinHandlers>
        <KeyinHandler Keyin="MYREPORT LEVELS"           Function="ReportLevels" />
        <KeyinHandler Keyin="MYREPORT TEXTSTYLES"	Function="ReportTextStyles" />
		<KeyinHandler Keyin="MYREPORT FONTS"	Function="ReportFonts" />
    </KeyinHandlers>
</KeyinTree>

Loading the Command Table in Python

Next, we will load the command table into our Python program. MicroStation provides a PythonKeyinManager class with an API LoadCommandTableFromXml to register the command table.

Import Modules

The script begins by importing several modules offering functions and classes to interact with MicroStation.

from MSPyBentley import *
from MSPyBentleyGeom import *
from MSPyECObjects import *
from MSPyDgnPlatform import *
from MSPyMstnPlatform import *
from MSPyDgnView import *
import os
import ctypes

Message Box Function

The MsgBox function is a utility to display message boxes. It uses the ctypes library to call the Windows API for message boxes.

def MsgBox (title, text, style):
    return ctypes.windll.user32.MessageBoxW (0, text, title, style)

Report Functions

The ReportLevels, ReportTextStyles and ReportFonts functions are placeholders (stubs) that currently display a message box indicating that the function is a work in progress (WIP).

def ReportFonts ():
    print ("Report Fonts stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Fonts...', 0)


def ReportTextStyles ():
    print ("Report Text Styles stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Text Styles...', 0)


def ReportLevels ():
    print ("Report Levels stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Levels...', 0)

Putting it all Together: The main Function

The main function constructs the path to the XML command table and uses the PythonKeyinManager to load the command table into MicroStation. The WString function is used to convert the file paths to the appropriate string format required by the API.

Here is the complete script.

from MSPyBentley import *
from MSPyBentleyGeom import *
from MSPyECObjects import *
from MSPyDgnPlatform import *
from MSPyMstnPlatform import *
from MSPyDgnView import *
import os
import ctypes


# Message box function
def MsgBox (title, text, style):
    ##  Styles:
    ##  0 : OK
    ##  1 : OK | Cancel
    ##  2 : Abort | Retry | Ignore
    ##  3 : Yes | No | Cancel
    ##  4 : Yes | No
    ##  5 : Retry | Cancel 
    ##  6 : Cancel | Try Again | Continue

    ## To also change icon, add these values to previous number
    # 16 Stop-sign icon
    # 32 Question-mark icon
    # 48 Exclamation-point icon
    # 64 Information-sign icon consisting of an 'i' in a circle    
    return ctypes.windll.user32.MessageBoxW (0, text, title, style)


# Report fonts function
def ReportFonts ():
    print ("Report Fonts stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Fonts...', 0)


# Report text styles function
def ReportTextStyles ():
    print ("Report Text Styles stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Text Styles...', 0)


# Report levels function
def ReportLevels ():
    print ("Report Levels stub...")
    MsgBox ('MyReport', 'WIP: This function will report existing Levels...', 0)


# Main function
def main():
    keyinXml = os.path.dirname(__file__) + '/MyReport.commands.xml'
    PythonKeyinManager.GetManager ().LoadCommandTableFromXml 
                                     (WString (__file__), WString (keyinXml))		


# main
if __name__ == "__main__":
    main()

Run/Execute project

Select project "MyReport.py" from the Python Manager dialog and Run/Execute the python script.

In the MicroStation Key-in window, type MyReport Levels and the following Message box will be displayed.

Extend the above code to add the reporting functionalities. Refer to the delivered examples and documentation.

Happy coding!

MicroStation Python: Add Keyins to your Program