Answers to MicroStation VBA Overview Questions

1. (What is MicroStation VBA?)
   MicroStation V8 includes and supports Visual Basic for Applications, one of today's most popular languages. MicroStation VBA is a complete Application Programming Interface that allows you to write custom applications that interface with MicroStation V8.
   
   
2. (What can I do with MicroStation VBA?)
   The goal of MicroStation VBA is to allow you to develop your own custom applications to automate many activities in MicroStation. Using VBA, you can develop standard desktop applications that can interact with MicroStation, increasing user productivity. VBA includes a wide array of tools that provide users with more and easier customization that ever before.
    
3. (What Bentley products support MicroStation VBA?)
   Currently, Bentley MicroStation, MicroStation PowerDraft, Bentley Navigator, and Bentley Redline support creating, recording and running MicroStation VBA macros. Support for MicroStation VBA is limited in Bentley Redline to the abilities of that product. Other Bentley software products provide APIs that are accessible from VBA. More information is available on the Bentley web site.
    
4. (Do I have to use the MicroStation VBA editor for my VBA applications to run in MicroStation V8?)
   No, you can write VBA code in whatever text editor you choose; however, to compile the code to work in MicroStation V8 you must paste it into a code window in the VBA editor in MicroStation V8.
    
5. (Are there any configuration variables in MicroStation V8 that must be set before I can use MicroStation VBA?)
   No. There are configuration variables that modify the behavior of MicroStation VBA, but they do not have to be adjusted before using VBA in MicroStation. See MicroStation VBA Environment Variables.
    
6. (What key-ins are used with MicroStation VBA and what do they do?)
   A list of the key-in commands that can be used with various parts of MicroStation VBA can be found in this help file. See MicroStation VBA Key-ins. 

MicroStation VBA Programming FAQ

1. Typically, what skills are needed to start programming with VBA in MicroStation V8? Answer
2. Can I add non-modal dialog boxes to my MicroStation VBA macro? Answer
3. How do I compile a MicroStation VBA macro? Answer
4. Can I protect my MicroStation VBA project so that others cannot see the source code in it, but can still run it? Answer
5. How can I get the contents of the current selection set in MicroStation VBA? Answer
6. How can I pass arguments to a VBA macro that is activated with a key-in command? Answer 

Answers to MicroStation VBA Programming Questions

1. (Typically, what skills are needed to start programming with VBA in MicroStation V8?)
   The MicroStation VBA language is most consistent with the Visual Basic for Applications programming language standards and styles. Programming skills acquired in learning the Visual Basic for Applications language with the Microsoft Office suite of applications will provide a good background for programming with VBA in MicroStation V8.
    
2. (Can I add non-modal dialog boxes to my MicroStation VBA macro?)
   Yes. To make a user form non-modal, set the ShowModal property of the form to False. This can be done in the Properties window for the user form. Additionally, a dialog can be displayed in a non-modal form using the optional boolean parameter to the Show method that sets the ShowModal property. To display a form named UserForm1 as non-modal, the Show method would be written:

   UserForm1.Show vbModeless

3. (How do I compile a MicroStation VBA macro?)
   In the VBA editor window, select the Run menu, then choose Run Sub/User Form. The macro is compiled immediately before it is executed. A shortcut to this menu item is to press the <F5> function key, which has the same effect. 
4. (Can I protect my MicroStation VBA project so that others cannot see the source code in it, but can still run it?)
   Yes. In the Visual Basic editor window select the Tools menu, then select the menu item that shows [project name] Properties, where [project name] is the name of the current project. In this dialog, select the Protection tab. Here, a password can be added so that editing or viewing the source code in the project requires the user to enter the password.
   
   
5. (How can I get the contents of the current selection set in MicroStation VBA?)
   First dimension a variable of type ElementEnumerator, then set this variable to the return value of GetSelectedElements from the ActiveModelReference, like this:

   Dim oEnumerator as ElementEnumerator
Set oEnumerator = ActiveModelReference.GetSelectedElements
See the Selection Set example.

6. (How can I pass arguments to a VBA macro that is activated with a key-in command?)
   Microsoft's VBA implementation does not support passing command line arguments to a basic macro. However, Bentley has added a means to accomplish this through the use of a global variable named KeyinArguments. This string variable will contain any additional arguments that were provided to the vba run <macro>keyin. For example, this sub-procedure:

   Public Sub getArgs()
   MsgBox KeyinArguments
End Sub

   called with this key-in string:

   VBA RUN getArgs VBA is fun!

   will display a dialog box with the string “VBA is fun!”.

Running a macro

Once a macro is selected from the list in the Macros dialog box, running it can be initiated by clicking the Run button in the Macros dialog.

Search path for VBA projects

The MicroStation configuration variable MS_VBASEARCHDIRECTORIES determines the directories in which MicroStation will search for projects when they are loaded by name. This variable also sets the location from which VBA projects can be autoloaded at startup time. See Autoloading a project for more information on choosing a project to load automatically.

Names of standard projects

The MicroStation configuration variables MS_VBAAUTOLOADPROJECTS and MS_VBAREQUIREDPROJECTS determine which projects are automatically loaded at startup time. MicroStation loads the projects listed in MS_VBAREQUIREDPROJECTS prior to loading the projects listed in MS_VBAAUTOLOADPROJECTS.

MS_VBAAUTOLOADPROJECTS is not usually set in the Configuration dialog box, but it contains a list of the project names that are chosen in the Project Manager dialog. See Autoloading a project for more information on choosing a project to load automatically.

One benefit of adding a project to the MS_VBAAUTOLOADPROJECTS variable through the Configuration dialog box, is that a project outside of the paths specified by MS_VBASEARCHDIRECTORIES can be set to autoload by entering the full file path specification including drive and directory paths.

The MicroStation configuration variable MS_VBAREQUIREDPROJECTS also names projects that are autoloaded. The VBA Project Manager nevers adds projects to or removes projects from the list that MS_VBAREQUIREDPROJECTS specifies.

The VBA Project Manager displays a check in the Auto-Load column for every project listed by MS_VBAAUTOLOADPROJECTS or MS_VBAREQUIREDPROJECTS. However, the user cannot turn off Auto-Load for projects listed by MS_VBAREQUIREDPROJECTS.

MicroStation has some configuration variables that let a user specify a list of applications to be loaded in response to some event. When MicroStation processes one of these lists, it checks each entry to see if it ends with ".MVBA". If the entry does end with ".MVBA", then MicroStation interprets it as the name of a VBA application. Otherwise, MicroStation interprets it as the name of an MDL application. As an example, the Standards Checker's initialization logic asks MicroStation to load all of the applications that the configurarion variable MS_STANDARDSCHECKER_APPS specifies. Therefore, setting MS_STANDARDSCHECKER_APPS to "SCByLevel.mvba;SCCompleteRefCheck.mvba;SCSimpleRefCheck.mvba" causes the StandardsChecker's initialization logic to load these VBA projects.

Automatically saving projects

The MicroStation configuration variable MS_VBASAVEONRUN determines whether modified VBA projects are automatically saved when a VBA program is executed. The default value for this variable is 1, indicating projects will automatically be saved. To prevent MicroStation from saving modified projects automatically, set this variable to 0. If this variable is 0, MicroStation does not automatically save the project. When unloading a project MicroStation tests to see if a project has changes that have not been saved. If it does and this variable is 1 then MicroStation saves the project. If it has unsaved changes and this variable is 0, then MicroStation asks the user if he wants to save the changes. This logic applies when the user makes an explicit request to unload a project. It also applies at shutdown, since MicroStation unloads every project at shutdown.

Opening project from memory or disk

The MicroStation configuration variable MS_VBA_OPEN_IN_MEMORY controls whether MicroStation keeps a project's data available by keeping the project's disk file open, or by copying the project into memory. If a lot of users are accessing they same project, they may encounter an error that happens because there is a limit on the number of processes that can simultaneously have a file open. To avoid this restriction, set MS_VBA_OPEN_IN_MEMORY to tell MicroStation to open the project from an in-memory image instead of keeping the project file open.

The allowable values for MS_VBA_OPEN_IN_MEMORY are "all", "readonly", and "none". If the value is "readonly", then MicroStation tests to see if the project file is read-only. If it is, then MicroStation copies the image into memory and opens it from the in-memory image. Otherwise, it opens the project from the file and keeps the file open. If the value is "all", then everytime MicroStation opens a project it copies that project into memory and opens it from the in-memory image. A value of "all" also forces MicroStation to make all projects read-only. If the value of MS_VBA_OPEN_IN_MEMORY is "none" or if MS_VBA_OPEN_IN_MEMORY is not defined, then MicroStation opens all projects from disk.

To be able to save the changes to a project, it is necessary to have MicroStation load it from disk. A user who edits projects should not have MS_VBA_OPEN_IN_MEMORY defined, or should have it defined as "none" or "readonly".

To be able to have a lot of users open a project at once, it is necessary to have MicroStation copy it into memory so MicroStation does not need to keep the project file open. The users who open this project should have MS_VBA_OPEN_IN_MEMORY set to "readonly" if they edit some projects and open some shared, readonly projects; or they should have MS_VBA_OPEN_IN_MEMORY set to "all" if they open projects shared by a lot of users but never edit projects.

The value of "a lot of users" is determined by the number of processes that can have a file open at once. The limit comes from the Windows enviroment. 20 is a common limit.

MS_VBA_OPEN_IN_MEMORY normally is not defined because the default behavior is acceptable for most users.

Editing a recorded VBA macro

When a macro is recorded in VBA in MicroStation, the first data point entered is in absolute coordinates, and all following data points are relative to this location. A recorded macro that places a few line segments using the Place SmartLine tool might look like this:

Sub Macro1()
   Dim startPoint As Point3d
   Dim point As Point3d, point2 As Point3d
 
'Start a command
   CadInputQueue.SendCommand "PLACE SMARTLINE "
 
   'Coordinates are in master units
   startPoint.X = 7.316122
   startPoint.Y = -4.865692
   startPoint.Z = 0#
 
   'Send a data point to the current command
   point.X = startPoint.X
   point.Y = startPoint.Y
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a data point to the current command
   point.X = startPoint.X + 2.48087
   point.Y = startPoint.Y + 3.0765
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a data point to the current command
   point.X = startPoint.X + 7.6503
   point.Y = startPoint.Y + 1.9341
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a reset to the current command
   CadInputQueue.SendReset
 
   CommandState.StartDefaultCommand
End Sub

When this macro is played back it will redraw the same elements in exactly the same location every time. This macro would be much more useful if the location were determined by user input rather than hard coded with specific coordinates. To do this, the macro must be edited slightly to get the first location from the first data point entered by the user. The changes to make this happen are shown in bold type in the code below.

Sub Macro1()
   Dim startPoint As Point3d
   Dim point As Point3d, point2 As Point3d
    Dim userPnt As CadInputMessage
 
'Start a command
   CadInputQueue.SendCommand "PLACE SMARTLINE "

   Set userPnt = CadInputQueue.GetInput(msdCadInputTypeDataPoint)  
 
   'Coordinates are in master units
   startPoint.X = userPnt.point.X
   startPoint.Y = userPnt.point.Y
   startPoint.Z = userPnt.point.Z
 
   'Send a data point to the current command
   point.X = startPoint.X
   point.Y = startPoint.Y
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a data point to the current command
   point.X = startPoint.X + 2.48087
   point.Y = startPoint.Y + 3.0765
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a data point to the current command
   point.X = startPoint.X + 7.6503
   point.Y = startPoint.Y + 1.9341
   point.Z = startPoint.Z
   CadInputQueue.SendDataPoint point, 1
 
   'Send a reset to the current command
   CadInputQueue.SendReset
 
   CommandState.StartDefaultCommand
End Sub

Running this modified code will draw the same elements as the recorded macro, only it will wait for a data point from the user, and the elements are drawn at that location. Other attributes of the elements could also be specified within the macro, such as color, level, line weight, and line style.

Prompting the user

When a macro is played back, the user might not recognize exactly what is happening, so it's always a good idea to add a prompt message at the beginning of a macro. We could have the prompt appear in any of several places, but let's keep it simple.

Add the following lines before the With statement in this macro:

ShowCommand "myKeyinMacro"
ShowPrompt "Running custom setup macro"

Let's also add a prompt to tell the user when it's safe to start doing things. Add the following line after the End With statement:

ShowPrompt "Setup complete. Ready for user input."

The complete key-in macro example

This example macro can now be saved and played back. The complete macro looks like this:

Option Explicit
Sub myStartUpCommand()
   ShowCommand "myKeyinMacro"
   ShowPrompt "Running custom setup macro"
   With CadInputQueue
      .SendKeyin "active color green"
      .SendKeyin "active level 10"
      .SendKeyin "history initialize"
      .SendKeyin "popset on"
      .SendKeyin "accudraw shortcuts default"
   End With

ShowPrompt "Setup complete. Ready for user input."
End Sub

Of course, you can add other key-in commands to this macro, and customize it with other features that you use when you set up your DGN file. Similar macros might be used at other times as well, perhaps before plotting you would run a similar macro to turn off construction elements, and hide certain levels.

Global methods and properties

In the Visual Basic Editor, you can view the set of object classes, methods, and properties through the Object Browser. This is an excellent place to start learning about MicroStation's objects that are available to Visual Basic programs. Select the Object Browser from the View menu.

The Object Browser displays available features by library. The MicroStationDGN library contains the objects specific to MicroStation, so change the combo-box in the Object Browser from <All Libraries> to MicroStationDGN.

In the list on the left, select <globals> from the list of Classes. The list on the right shows the members of the MicroStationDGN.Application object. This is the “default” object that is implied when one of the methods or properties in the list on the right is used in a Visual Basic instruction. For example to change the active color to yellow, we can use the instruction:

ActiveSettings.Color = 4

The ActiveSettings property belongs to the MicroStationDGN.Application object, but we don't need to specify this object because it is implied. This instruction actually uses another object as well, that is a Settings object. The ActiveSettings property gives us access to the Settings object that holds the active settings in MicroStation. The Color property belongs to the Settings object.

The CadInputQueue object

The methods of the CadInputQueue object allow your VBA programs to send input to MicroStation, and to collect input from the user. Using the CadInputQueue object, your program can respond to key-ins, data points, and resets. Your program can also send these messages to MicroStation, and it can send messages to an MDL application that is running at the same time.

The CommandState object

The CommandState object is used to implement and initiate VBA programs that operate like standard MicroStation element-creation and element-modification commands. These programs must create an object that implements the IPrimitiveCommandEvents interface, or the ILocateCommandEvents interface. Either the CommandState object's StartPrimitive method or StartLocate method is then called to activate the object. For code examples of these, see the Element Creation Command Example and the Analyze Arc Example.

The ActiveWorkspace object

The ActiveWorkspace object is an instance of the Workspace class. This class has methods for reading, creating and deleting MicroStation's configuration variables. To see an example of how the ActiveWorkspace object can be used, see the Configuration Variable Example.

More objects and documentation

There are many more classes listed in the Object Browser, each is documented in the Reference part of the MicroStation VBA documentation. To find the documentation for a specific class, property or method, select the item in the Object Browser window, then press the <F1> key.

WithEvents

The mechanism that allows the class to respond to the two events is the WithEvents declaration. When the Dim statement is used to create the hooks variable as type Application, the WithEvents keyword signifies that hooks will respond to some event. This means that MicroStation will send event messages to the hooks object, but it does not mean that hooks must respond to every event. The hooks object can only respond to the event that we wrote the code for, the OnDesignFileClosed event.

To make the hooks object respond to the OnDesignFileOpened event we would add another sub procedure in the openClose class that looks like this:

Private Sub hooks_OnDesignFileOpened (ByVal dgnFileName As String)
   MsgBox "Opening DGN file " + dgnFileName
End Sub

Reading a value from a configuration variable

Reading a configuration variable from a VBA program is reasonably easy if you know ahead of time which variable you need to get the value of. The value of a configuration variable is returned as a String, so it can be retrieved with the following lines:

Dim configVarValue As String
configVarValue = ActiveWorkspace.ConfigurationVariableValue ("MS_DEF")

Usually, it is a good idea to check whether the configuration variable you want to read is defined. To check this, the example above would look like this:

Dim configVarValue As String
If IsConfigurationVariableDefined ("MS_DEF") Then
   configVarValue = ActiveWorkspace.ConfigurationVariableValue ("MS_DEF")
End If

Note: Configuration variable values can contain other configuration variables. It is generally a good idea to “expand” a configuration variable value if you need to use it to find a file. Expanding means to substitute the values for any other configuration variables in the value you just read. The ConfigurationVariableValue method will do this for you.

For additional information, see the Configuration Variable Example.

Creating a new configuration variable

A new configuration variable is defined and set using the AddConfigurationVariable method of the ActiveWorkspace object. To create a new configuration variable named “AddedByVba” use the following lines:

If (IsConfigurationVariableDefined "AddedByVba" = False) Then    ActiveWorkspace.AddConfigurationVariable "AddedByVba", "VBA DEFINITION"
End If

Before creating the variable, this example checks to see if it already exists, and if not it creates the configuration variable at the User level. All VBA changes to configuration variables are at the User level.

See the Configuration Variable Example.

Deleting a configuration variable

A configuration variable can be deleted by using the RemoveConfigurationVariable method of the ActiveWorkspace object. Here again, it is a good idea to check to see if the configuration variable is defined before trying to delete it. To remove the configuration variable added by the example above, use the following lines:

If IsConfigurationVariableDefined "AddedByVba" Then
   ActiveWorkspace.RemoveConfigurationVariable "AddedByVba"
End If

See the Configuration Variable Example.

MbeSettings to ActiveSettings

Perhaps the most commonly accessed Mbe object in MicroStation BASIC macros is the MbeSettings object. This object allowed access to the current settings of MicroStation, including various locks, grid settings, and text settings. Many of these same settings are accessible in VBA through the ActiveSettings object, but some are not. Text settings are now part of the TextStyle object, and the name of the current font can only be accessed through the font object itself.

MbeElement to Element class and others

If you've ever had to manipulate drawing elements in a MicroStation BASIC macro, then you know about MbeElement. This object is used to handle nearly all of the possible design elements, but it can't be used to create a new design element. In VBA, the rough equivalent to MbeElement is the Element class. This class can handle many different kinds of design elements, but there are now separate classes for each design element type. These can also be used to create design elements instead of sending commands to MicroStation to add elements to the drawing.

Other Mbe objects

All Mbe objects in a MicroStation BASIC macro must be changed to use an equivalent Visual Basic object or class to accomplish the same result. Because of many changes to MicroStation, such as the addition of models and other new features, there is not an easy one to one mapping from MicroStation BASIC to Visual Basic.

Macro entry points

MicroStation BASIC macros always began with a sub procedure called Main, and this was the entry point for every macro. Visual Basic does not require a sub procedure called Main, but it will use it if it is there.

MicroStation BASIC supported Pen Tables for plotting by allowing the programmer to create functions that could be called at certain times during the plotting process. These plot hook functions are still supported in MicroStation BASIC, but are not supported in VBA in MicroStation.

Translation Macros

Previous versions of MicroStation used Basic macros to assist in data translation from other CAD software file formats to MicroStation's data format. Since MicroStation V8 reads the DWG data format directly, it does not need to execute Basic macros to assist in translation. The translation macros from earlier versions of MicroStation will not work in MicroStation V8 nor are they needed.