AECOsim Building Designer and Structural Modeler have powerful capabilities for creating custom annotation labels for structural drawings using Visual Basic for Applications (VBA). VBA allows users to easily create macros that use the full power of the built-in MicroStation VBA language to create drawing labels for linear members. These labels typically are member properties formatted in a special way to meet the requirements of a project.
This article outlines the basic procedure for creating a custom VBA label using a simple example.
Update: Please note in OpenBuildings Designer Update 8 we have identified a defect (ref 672643) that prevents this VBA from running due to a problem with a missing DLL Reference:
AECOsim Building Designer delivers a MicroStation VBA named “STRCustomDrawingLabels.vba” in the vba directory of the workspace. In the Dataset_US dataset the macro is in this directory:
…WorkSpace\BuildingDatasets\Dataset_US\vba
STRCustomDrawingLabels contains many examples of VBA macros that illustrate a range of techniques. The file contains both examples of drawing label rules as well as other general supporting “helper” methods. It is well worth reviewing if you developing your own custom drawing labels. Some of these macros are used in the standard Bentley Structural drawing rules to format reactions, shear studs and camber properties.
Here are several of the delivered macros:
VBA Macro (STRCustomDrawingLabels.mvba) Description STRAbbreviateSectionName Section name truncated STRSectionNameWithStackedFractions Section name with stacked fractions STRCommonString Section name, camber and shear studs. STRTaperedSectionNames Tapered section name SectionWithStudCount Section name with shear studs SectionWithEvenStudCount Section name; studs rounded to even value EndShear End reaction; rounded with minimum value EndShearNoZeros End reaction; zero value suppressed CamberWithLabel Member camber; c = ¾” CamberWithAngleBrackets Member camber (<1”>)
The simple example that we will develop will annotate the XY position of all columns that have a section of “W10X33”. The example will show how to :
Here is the output of our macro showing the label “XY = (15, 0)” for one column. The macro creates a label only for columns with a particular section (W10X33); other columns are not annotated.
The Structural drawing rules allow custom labels to be created that are based directly on the properties of the member or labels that are created and formatted through the use of VBA. Any label can take advantage of the extensive settings that allow the font, symbology (level, color, weight) and position (offsets relative to member) to be defined.
We will be adding a label to the existing drawing rule “Columns – Main FP Abbr Rotated” that is used to annotate columns in plan drawings. The standard rule shows the geometric cross section of the column along with a callout at 45 degrees that shows the abbreviated section name.
In the Labels tab of the Edit Drawing Resymbolization Rule dialog box, select Custom Labels in the list on the left and then add a name for the new label (“XYPosition”).
The Add Attribute button in the lower right opens the “Define Custom Label Variable” dialog box that allows an existing property to be selected as the basis for the rule. The list of available properties is large; it includes both the standard structural properties such as Section, Grade, Material and Class as well as DataGroup properties. Since we will be basing our annotation on the column section, select “Section name” in the list. To activate a VBA macro to be used for our label formatting, choose the “Custom” option in the Format option button. It will display three fields: VBA Project, Module and Function. These values are used to name the specific VBA macro that will be used to receive the property we selected (“Section name”) for each column and then return the formatted label. The VBA Project field is the name of the VBA file. For the standard drawing rules, the name of the VBA project is “STRCustomDrawingLabels.mvba”. In our case we are going to create a new VBA project so we’ll name it “ProjectCustomLabels” which will correspond to a new ProjectCustomLabels.mvba file in our project workspace.
The Module specifies the program module within the VBA project that contains the designated label macro. Name the Module “Main” and finally name the Function “ColumnPosition”. The Function field specifies the actual VBA function (macro) that will be called.
Pressing the OK button will create this specification that describes our label: %SECTNAME:[ProjectCustomLabels]Main.ColumnPosition%
For every column processed by our drawing rule, the section name (SECTNAME) will be passed to the VBA macro “ColumnPosition” in the module “Main” contained in the VBA project “ProjectCustomLabels”. The text label returned by the macro will be added to the column annotation using the designated font, symbology and position.
Open the VBA Project Manager using the Utilities->Macro->VBA Project Manager pull-down menu. Select the New Project option on the toolbar to create a new project and name it “ProjectCustomLabels”.
By default, the newly created MVBA file will go into the directory specified by the configuration variable MS_VBANEWPROJECTDIRECTORY. You can locate your project file in any directory but the directory must be included in the search path that MicroStation uses for VBA applications. This is controlled by the configuration variable MS_VBASEARCHDIRECTORIES.
Now open the Visual Basic editor using the Visual Basic Editor option on the toolbar.
Expand “ProjectCustomLabels” in the list of open VBA applications and then double-click on Module1. A blank module will open in the editing window. Rename the default module name from “Module1” to “Main” in the Properties window so it matches the Module name we specified in our custom drawing label.
Since we will be using some of the Structural-specific VBA library methods we need to specify that the Structural library will be used by our project in addition to the standard MicroStation libraries. Open the References dialog box (Tools->References) and then check the box for “Bentley MicroStation Structural DGN 1.0 Library”.
We are ready to enter our VBA code. The final code is shown below. Let’s step through the macro using the line numbers on the left as a reference.
While the directive “Option Explicit” is not required in a VBA program file, it is highly recommended. It tells the VBA compiler to perform additional error checking such as requiring all variables to be explicitly declared with a Dim statement. It’s good practice to always use this feature and it is guaranteed to reduce the amount of time required to develop your application because many classes of simple errors are caught when the program is compiled (rather than when it is run).
This is the declaration of our function (macro). Our function is named ColumnPosition to match the name given in the Function field of the custom drawing label. The function receives two arguments that are passed from AECOsim Building Designer: “handle” and “value”.
The first argument, "handle", can be used to get the STFLinearMemberList that is currently being processed by the drawing code.
The second argument “value” is the name of the property that we specified in our custom drawing label. In our case, it will be the section name because we specified “Section name” when we set up our drawing rule. Even if the property is a number it will always be passed to your macro as a string. The VBA library has support for converting strings to integers or floating point values.
The final part of the function declaration ends with “As String” to specify that the function will return a string value to the caller. This is done simply by assigning the name of the function (“ColumnPosition”) to any string value before returning.
In our drawing rule we are going to skip the annotation for any column that does not have a section of “W10X33”. So, here we test the section name (the “value” argument) and then return immediately if the section name does not match. Before returning the function value is set to a blank string (“”) since we are not creating a label.
Before we can read the XY coordinates of our column, we need to convert the “handle” argument to an STFLinearMember so we can use the Structural VBA library.
The initReadOnlyFromHandle method is hidden as its only use is in VBA functions for custom labels. It converts the “handle” argument to a read-only STFLinearMember. No changes are possible to this element.
The member.GetPQPoints method returns the coordinates (X, Y, Z) of each end of the column.
The final label is created by appending the text string “XY = “ with the X and Y coordinates of the start of the column. Our column is vertical so either the start or end XY coordinates could be used since they are identical. Each coordinate value is rounded from a floating point value to the nearest (master unit) integer using Round. Finally, the coordinate is converted to a string using CStr() so it can be appended to the “XY =” label.
The final label is returned by assigning the function name (ColumnPosition) to the value. AECOsim Building Designer will then use the value to annotate the column using the font, symbology and position specified for the custom label in the drawing rule.
Using VBA to create custom Structural drawing labels provides a very powerful tool to enhance your drawings and meet project standards. The standard drawing rules provided by AECOsim Building Designer are quite extensive but there are cases when a VBA custom label is the perfect solution.
Bentley offers many training and learning resources for going further with VBA such as this book:
http://www.bentley.com/en-US/Training/Products/Resources/Books/Learning+MicroStation+VBA.htm