Implements Statement

Since an interface is really a collection of prototypes for the methods and properties of a class, it is necessary for a class that “implements” the interface to duplicate all of the Public methods declared as part of the interface. A missing member of an interface will cause an error in compilation. The Implements statement, used to declare that a class is making use of an interface, is really a contract that states the class is going to provide code for each of the methods of the interface.

The Implements statement to inform MicroStation that a class is going to provide code for the IPrimitiveCommandEvents interface looks like this:

Implements IPrimitiveCommandEvents

IPrimitiveCommandEvents_DataPoint
IPrimitiveCommandEvents_Dynamics
IPrimitiveCommandEvents_Keyin
IPrimitiveCommandEvents_Reset
IPrimitiveCommandEvents_Start
IPrimitiveCommandEvents_Cleanup

These methods allow your VBA program to respond to each of the events necessary to create and place a design element in the active model. MicroStation calls each of these methods by name when the actions of the user dictate. For an example of implementing this interface, see the Element Creation Command example.

To conclude, the use of an interface tells MicroStation that the class has methods to call in certain circumstances, and that the class behaves in a particular way. The IPrimitiveCommandEvents interface says the class behaves like a MicroStation tool such as Place Arc or Place Circle (both “primitive” command tools because they place primitive elements). When the class implementing this interface is activated, the IPrimitiveCommandEvents_Start method is called first, which usually places a prompt message in the status bar area. Other methods are called at similar times. See the IPrimitiveCommandEvents description for more details.

Bit Fields

The Visual Basic language does not directly support bit fields. If you're translating an MDL structure that includes bit fields, you'll need to combine the bit fields into an appropriately sized integer field, then use Visual Basic's “And” and “Or” operators to parse out the bits.

For example, this MDL Structure:

typedef struct applyViewGroupOptions
{
   UInt16 doNotApply:1;
   UInt16 applyActiveParamsSameModel:1;
   UInt16 optionPadding:14;
   UInt16 optionPadding2:16;
} ApplyViewGroupOptions;

Would have the following equivalent VBA UDT:

Type ApplyViewGroupOptions
   BitFields As Long
End Type

In this example, the field name “BitFields” is arbitrary. The VBA Long type comprises 32 bits, the total number of bits in the MDL structure.

Nested Structures

Nested structures, one structure included or defined within the body of another, are not uncommon in MDL. To defined the equivalent UDT in Visual Basic you must first define the sub-structures separately. For example, the MDL structure TextSizeParam comprises a field whose type is that of another structure, MSTextSize:

typedef struct mstextsize
{
   double width;
   double height;
} MSTextSize;

typedef struct textSizeParam
{
   int mode;
   MSTextSize size;
   double aspectRatio;
} TextSizeParam;

The equivalent VBA UDT for these structures is coded like this:

Type MSTextSize
   width As Double;
   height As Double;
End Type

Type TextSizeParam
   mode As Long
   size As MSTextSize
   aspectRatio As Double
End Type

Note: For some of the commonly used MDL structure types, the VBA UDTs are already defined.

These pre-defined types can be used to define UDTs. For example, this MDL structure:

typedef struct dimCircleGeom
{
   double        radius;
   Dpoint3d      origin;
   RotMatrix     rMatrix;
} DimCircleGeom;

requires both Dpoint3d, and RotMatrix types. Since these are defined in VBA already, we can write this structure as follows:

Type DimCircleGeom
   radius As Double
   origin As Point3d
   rMatrix As Matrix3d
End Type

Arrays

Array equivalents are defined using the Visual Basic syntax for arrays. For the MDL definition field[n] the equivalent VBA definition is field (0 to n-1). If the array size n is defined using a constant in MDL, you'll need to define the equivalent constant in Visual Basic. For example, this MDL structure:

typedef struct dwgHatchDefLine
{
   double     angle;
   DPoint2d   through;
   DPoint2d   offset;
   short      nDashes;
   double     dashes[MAX_DWG_HATCH_LINE_DASHES];
} DwgHatchDefLine;

Would have the following equivalent definition in Visual Basic:

Const MAX_DWG_HATCH_LINE_DASHES = 20 'From mdl.h

Type DwgHatchDefLine
   angle As Double
   through As Point2d
   offset As Point2d
   nDashes As Integer
   dashes(0 to MAX_DWG_HATCH_LINE_DASHES - 1) As Double
End Type

Pointers

A pointer to anything including a char* and a void*) should be defined as a Long in Visual Basic. For example, this structure in MDL:

typedef struct dimLStringGeom
{
   byte      closed;
   long      numVerts;
   Dpoint3d  *points;
} DimLStringGeom;

Would have the following equivalent definition in Visual Basic:

Type DimLStringGeom
   closed As Byte
   numVerts As Long
   points As Long   'pointer to Point3d
End Type

Use VBA's VarPtr function to assign values to Long fields that represent pointers. You should also use VarPtr to pass the addresses of UDTs to MDL functions.

Note: The VarPtr function is an undocumented feature of Visual Basic. For more information, visit the Microsoft Developer Network library website (http://msdn.microsoft.com/library), and search for the Knowledge Base article Q199824 in “All Knowledge Base.”

Declare statement

There are two forms of the declare statement:

[Public | Private] Declare Sub name Lib "libname" [Alias "aliasname"] [([arglist])]
[Public | Private] Declare Function name Lib "libname" [Alias "aliasname"] [([arglist])] [As type]

The Visual Basic Reference describes the declare statement well, but does not give all of the information needed to decide how to declare the arguments and use return values.

The syntax for an argument is:

[Optional] [ByVal | ByRef] [ParamArray] varname[()] [As type]

This is the same as an argument declaration for a VB procedure. The syntax for declaring the function return type is also the same as the syntax for a standard VBA return type. It is important to understand how the ByVal, ByRef, and the data types correspond to C concepts. The following sections address these topics.

Simple Arguments

First, consider how the base types match. The table below shows C and Visual Basic base type equivalents:

VB’s user-defined types are compatible with C structures, although it may be necessary in some cases to add padding to a UDT to make it line up with the MDL struct. In VB, Long and Double fields always start on a 4-byte boundary. With MicroStation’s C structures, long fields always start on a 4-byte boundary but double fields always start on an 8-byte boundary.

Here is an example of a UDT that requires some padding to make it line up with the MicroStation structure:

' The field pad is needed to force width to line up with the C structure

Type TextSize
     mode As Long
     pad As Long
     width As Double
     height As Double
     aspectRatio As Double
End Type

MicroStation’s object model provides some of the common simple structures from MicroStation. A C DPoint3d is a VB Point3d; a C RotMatrix is a VB Matrix3d; a C Transform is a Transform3d.

Declaring an argument ByRef means that it is a reference to the memory that holds the argument. C provides a similar capability via pointers. A VB declaration ByRef dlbArg as Double is equivalent to the C declaration double *dblArg. ByVal means only the value of the location is passed to the function. Since the called function does not get the address of the argument, it cannot modify the original value.

MDL built-ins do not use structures as arguments. If a MDL built-in requires a structure, it declares an argument that is a pointer to a structure. For a C declaration of a pointer to a structure, the corresponding VBA declaration is a ByRef variable of the corresponding UDT type. For example, given the C declaration: DPoint3d *arg use the VB declaration: ByRef arg as Point3d.

Pointer Arguments

Many MicroStation built-ins take arguments that are pointers. Here are some of the uses of pointer arguments. Some of these are discussed in depth later.

• Dynamically Allocated Types: These are types such as DgnModelRefP and DialogBox*
• Function pointers. MicroStation does not work well with function pointers from VBA.
• Arrays
• Structures. When a MicroStation built-in requires an argument that is a structure, it uses a pointer type. For example, DPoint3d *
• Optional arguments: If an argument is optional, it normally is declared as a pointer. The caller can pass in NULL or pass a pointer to the actual argument value
• Variable argument types: For some MicroStation built-in functions, the data type of one argument depends on the data type of another argument. To allow this, the argument that has different types is declared as void *. For example, if the second argument to mdlParams_setActive is ACTIVEPARAM_COLOR_BY_NAME then the void * represents a char *. If the second argument is ACTIVEPARAM_TEXTWIDTH then void * argument represents a double *.
• ASCII Strings: These are declared as char *.
• Unicode Strings: These are declared as MSWChar *. 

BoolInt mdlModelRef_isTransient
(
DgnModelRefP modelRef
);

Declare Function mdlModelRef_isTransient _
     Lib "stdmdlbltin.dll" _
     (ByVal modelRef As Long) As Long

Function IsTransient(oModelRef As ModelReference) _
    As Boolean
    Dim lDgnModelRefP As Long
    Dim result As Long
    lDgnModelRefP = oModelRef.MdlModelRefP
    result = mdlModelRef_isTransient(lDgnModelRefP)
    IsTransient = CBool(result)
End Function

int mdlRefFile_setClip
(
DgnModelRefP modelRef,
DPoint2d *pts,
int      nverts
);

Declare Function mdlRefFile_setClip _
    Lib "stdmdlbltin.dll" _
    (ByVal modelRef As Long, _
    ByRef pts As Point2d, _
    ByVal nverts As Long) As Long

     mdlRefFile_setClip modelRefP, clipbound(0), 7

Public int mdlAccudraw_optimizeForContext
(
     long flags,        /* => flags from accudraw.h */
     DPoint3d *originP, /* => NULL okay (for all 5) */
     DPoint3d *deltaP,  /* => */
     double *distanceP, /* => */
     double *angleP,    /* => */
     void *orientationP /* => RotMatrix or DPoint3d (unit vector) */
)

Declare Function mdlAccudraw_optimizeForContext _
     Lib "stdmdlbltin.dll" (ByVal flags As Long, _
     ByRef originP As Point3d, _
     ByRef deltaP As Point3d, _
     ByRef distanceP As Double, _
     ByRef angleP As Double, _
     ByRef orientationP As Any) As Long

Declare Function mdlAccudraw_optimizeForContext1 _
     Lib "stdmdlbltin.dll" (ByVal flags As Long, _
     ByRef originP As Any, _
     ByRef deltaP As Any, _
     ByRef distanceP As Double, _
     ByRef angleP As Double, _
     ByRef orientationP As Any) As Long

mdlAccudraw_optimizeForContext flags, ByVal 0, ByVal 0, ByVal 0, ByVal 0, 0

void mdlOutput_statusUW (MSWChar *pMessage);

Declare Sub mdlOutput_statusUW Lib "stdmdlbltin.dll" (ByVal pMessage As Long)

mdlOutput_statusUW StrPtr (“Display in status area”)

int mdlFile_find
(
    char      *outname,
    const char *inname,
    const char *envvar,
    const char *iext
);

Declare Function mdlFile_find _
     Lib "stdmdlbltin.dll" _
     (ByVal outname As String, _
     ByVal inname As String, _
     ByVal envvar As String, _
     ByVal iext As String) As Long

Sub FindFile()
     Dim strFullName As String
     'Allocate the buffer
     strFullName = Space(512)

     'Call the function
     If mdlFile_find(strFullName, "accudraw", "MS_MDL", ".ma") = 0 Then
            'Truncate at C’s end-of-string
            strFullName = Left$(strFullName, _
            InStr(1, strFullName, _
            vbNullChar) - 1)
          Debug.Print "The full path is " & strFullName
     End If
End Sub

StatusInt mdlModelRef_getDisplayName
(
     DgnModelRefP modelRef,
     MSWChar *displayName,
     unsigned int maxChars,
     MSWChar *separator
);

Declare Function mdlModelRef_getDisplayName _
     Lib "stdmdlbltin.dll" _
     (ByVal modelRef As Long, _
     ByVal displayName As Long, _
     ByVal maxChars As Long, _
     ByVal separator As Long) As Long

Function GetDisplayName(modelRef As ModelReference) As String
     Dim length As Long
     Dim dgnModelRefP As Long

     ' A subsequent section will discuss the method MdlModelRefP
     dgnModelRefP = modelRef.MdlModelRefP

     ' Allocate the buffer
     length = 2000
     GetDisplayName = Space(length)

     mdlModelRef_getDisplayName dgnModelRefP, _
          StrPtr(GetDisplayName), length, 0

     ' Truncate at C's end-of-string
     GetDisplayName = Left$(GetDisplayName, InStr(1, _
          GetDisplayName, vbNullChar) - 1)
End Function

Int64 Arguments

Visual Basic does not support 64 bit integers, but a Visual Basic program can use DLong to simulate 64 bit integers. For example, the C declaration of mdlSystem_getFreeDiskSpace is:

int mdlSystem_getFreeDiskSpace
(
     int64 *pTotalBytes,
     int64 *pFreeBytes,
     char *fileSys /* => fileSys letter */
);

The Visual Basic declaration is:

Declare Function mdlSystem_getFreeDiskSpace _
     Lib "stdmdlbltin.dll" _
     (ByRef pTotalBytes As DLong, _
     ByRef pFreeBytes As DLong, _
     ByVal fileSys As String) As Long

Here is an example using it:

Sub PrintFreeDiskSpace()
     Dim freeSpace As DLong
     Dim totalSpace As DLong

     mdlSystem_getFreeDiskSpace totalSpace, freeSpace, "D:"
     Debug.Print "D: Total space " & DLongToString(totalSpace)
     Debug.Print ", Free Space: " & DLongToString(freeSpace)
End Sub

Pointer Return Values

All pointer return values must be handled as Longs.

If the return value is one of the dynamically allocated types, then the Visual Basic program can either leave it as a Long if the program will use it as an argument to another function, or the program can use one of the hidden Mdl… methods to get the corresponding VBA object.

If the pointer is a char *, then the VBA program can convert it. A simple approach is to use the function SysAllocString. Visual Basic itself uses SysAllocString to allocate strings. Here is an example that uses the char * value that mdlSystem_getCurrTaskID returns.

Private Declare Function mdlSystem_getCurrTaskID _
          Lib "stdmdlbltin.dll" () As Long ' Returns a char*
Private Declare Function SysAllocString Lib "oleaut32" _
          (ByVal CharPtr As Long) As String
Sub PrintName()
     Dim lTaskId As Long
     Dim strTaskId As String
     lTaskId = mdlSystem_getCurrTaskID()
     strTaskId = SysAllocString(lTaskId)
     Debug.Print "The current MDL task is: " & strTaskId
End Sub

Global origin

A ModelReference object has a GlobalOrigin property that gives the location of the global origin for the model as a Point3d.

Applying rotation using a Matrix3d

Below is a short example of using a Matrix3d to rotate a text element by 15 degrees about the Z axis at the origin of the element.

Public Sub rotateText ()
   Dim rMatrix As Matrix3d
   Dim tTransform As Transform3d
   Dim dAngle As Double
   Dim zAxis as Point3d
   Dim oEl As TextElement
   Dim oElEnum as ElementEnumerator

   dAngle = 15 * Pi /180   'Change the angle to radians
   zAxis.x = 0   'Set the zAxis to (0,0,1)
   zAxis.y = 0
   zAxis.z = 1

   'Now we can get the Matrix3d for rotation
   rMatrix = Matrix3dFromVectorAndRotationAngle (zAxis, dAngle)

   'Find the text elements in the selection set, skip others
   Set oElEnum = ActiveModelReference.GetSelectedElements
   oElEnum.Reset   'reset oElEnum to the first element
   While oElEnum.MoveNext
      If (oElEnum.Current.Type = msdElementTypeText) Then
         Set oEl = oElEnum.Current
         tTransform = Transform3dFromMatrix3dAndFixedPoint3d (rMatrix, oEl.Origin)
         oEl.Transform tTransform
         ActiveModelReference.ReplaceElement oElEnum.Current, oEl
         oEl.Redraw
      End If
   Wend
   RedrawAllViews

End Sub

Explanation of the example

The example above uses hardcoded values for the rotation angle and axis of rotation for the sake of simplicity. The angle is converted to radians since all rotation calculations in MicroStation occur in radians. The axis of rotation is set to the Z axis (0,0,1). The Matrix3d is then calculated from the rotation angle and the axis of rotation (a vector).

The set of elements in the selection set is then collected in oElEnum. While there are elements in this ElementEnumerator they are tested one at a time, and only the text elements are rotated. The Matrix3d cannot be applied to an element by itself, so a Transform3d is formed from the origin of the text element and the Matrix3d created earlier. The element is then transformed using this Transfom3d, then the original element is replaced with the modified element, and the element is redrawn.

Note: Before you run this example, place a text element into the current design then select it with the Element Selection tool. You can have multiple elements in the selection set, though only text elements will be affected.

The Transform3d data type, usually used for scaling and translation of elements, is discussed in further detail below.

Using Transform3d to apply rotation and scaling

The lines below can be added to the code example above to create an additional Matrix3d used to scale the text element by a factor of 1.5. This transformation is applied at the same time as the rotation.

   Dim sMatrix As Matrix3d
   sMatrix = Matrix3dFromScale (1.5)
   tTransform = Transform3dFromMatrix3dTimesTransform3d (sMatrix, tTransform)

To add the scaling operation to the example above copy these lines and paste them just before the line that reads:

     oEl.Transform tTransform

After creating the sMatrix and setting it to a scale factor of 1.5 this Matrix3d is added to the tTransform Transform3d so that it applies both the rotation and scaling at the same time.

Getting the selection set

The selection set is made of the currently selected elements. These could be chosen with a single data point using the Element Selection tool, or by Power Selector or another means, it really doesn't matter to your VBA program. The selection set is already made up when your program runs. So you must get the selection set and find out whether it has any elements of interest to your program.

The selection set is obtained from the ActiveModelReference by calling the GetSelectedElements method. This creates an ElementEnumerator which allows you to process the elements it holds one at a time. This process sounds complicated, but the code is simple. It looks like this:

Public Sub getSelectionSet ()
   Dim oElEnum As ElementEnumerator
   Dim oEl As Element
   Set oElEnum = ActiveModelReference.GetSelectedElements
   oElEnum.Reset
   While oElEnum.MoveNext
      Set oEl = oElEnum.Current
      'Change the color of the element
      oEl.Color = 3
      oEl.Redraw msdDrawingModeNormal
      oEl.Rewrite
   Wend
End Sub

This example changes the color of each element to red then redraws it on the screen. To make the change permanent, the element must be replaced in the ActiveModelReference after the change is made. The line that does this is:

     oEl.Rewrite

The MoveNext method of the ElementEnumerator returns True if there are more elements in the selection set, and False if there aren't any more. This makes it very convenient to process the elements just once.

Note: When you get the ElementEnumerator from the GetSelectedElements method, always remember to call Reset to make sure that you are processing the ElementEnumerator from the beginning.

Processing elements in a fence

Processing the set of elements in a fence is very similar to using a selection set. The initial setup requires a few more lines since there is not always an active fence and your program must test for it before processing. By contrast, the ActiveModelReference will always return an ElementEnumerator when you call the GetSelectedElements method to handle a selection set, it just will not have any elements if nothing is selected.

The code to see if a fence is active uses the Fence object and looks like this:

Dim oFence As Fence
Set oFence = ActiveDesignFile.Fence
If oFence.IsDefined Then
   'we can process the elements here
End If

To get and process the elements in the fence, we use an ElementEnumerator just like we did for the selection set in the example above. So the code for the same example, only this time getting the elements from the fence, looks like this:

Public Sub getFenceElements()
   Dim oFence As Fence
   Dim oElEnum As ElementEnumerator
   Dim oEl As Element
   Set oFence = ActiveDesignFile.Fence
   If oFence.IsDefined Then
      Set oElEnum = oFence.GetContents
      oElEnum.Reset
      While oElEnum.MoveNext
         Set oEl = oElEnum.Current
         'Change the color of the element
         oEl.Color = 3
         oEl.Redraw msdDrawingModeNormal
         oEl.Rewrite
      Wend
   End If
End Sub

A really flexible program is able to take its input from either a fence or a selection set. This is probably most easily handled by testing for the fence, and if it is not active, getting the selection set. Either way, we get an ElementEnumerator containing the elements. The code to handle both would be written this way:

Public Sub getElementsFromFenceOrSelectionSet()
   Dim oFence As Fence
   Dim oElEnum As ElementEnumerator
   Dim oEl As Element
   Set oFence = ActiveDesignFile.Fence
   If oFence.IsDefined = True Then
      Set oElEnum = oFence.GetContents
   Else
     Set oElEnum = ActiveModelReference.GetSelectedElements
   End If
   oElEnum.Reset
   While oElEnum.MoveNext
      Set oEl = oElEnum.Current
      'Change the color of the element
      oEl.Color = 3
      oEl.Redraw msdDrawingModeNormal
      oEl.Rewrite
   Wend

End Sub

Another example, Selection Set Processing is also provided.

Scanning the design file for elements

The ModelReference class has a Scan function that can be used with or without an ElementScanCriteria object. The difference is that when you use it without the ElementScanCriteria, you get the set of all elements within the model and you have to sort out which ones you want to process. The ElementScanCriteria lets you filter out the elements you do not want to process so the Scan function returns only those elements that meet your criteria. Here again, we use the ElementEnumerator to receive the objects from the Scan function.

This example finds only the elements with color 3. Once found, these elements are changed to color 2, redrawn and rewritten to the design file.

Public Sub changeColor()
   Dim oElScan As ElementScanCriteria
   Dim oElEnum As ElementEnumerator
   Dim oEl As Element
   Set oElScan = New ElementScanCriteria
   oElScan.ExcludeAllColors
   oElScan.IncludeColor 3
   Set oElEnum = ActiveModelReference.Scan (oElScan)
   oElEnum.Reset
   While oElEnum.MoveNext
      Set oEl = oElEnum.Current
      'Change the color of the element
      oEl.Color = 2
      oEl.Redraw msdDrawingModeNormal
      oEl.Rewrite
   Wend

End Sub

The code in this example looks pretty much the same as the previous examples from the point at which the ElementEnumerator is filled with elements to the end of the sub procedure.

Note: The ElementScanCriteria initially will accept all elements, so before calling the IncludeColor (3) method, we must set it to exclude all of the other colors, otherwise it will accept them too. This is the true for all of the different criteria types that the ElementScanCriteria can be set to filter.

Other examples of using the Scan method to retrieve elements are shown in the Change Element Level Examples.

Start method

The Start method is called by MicroStation when the command is first started. This happens when the program is initiated. Usually, the Start sub procedure initializes any objects or variables necessary for the command, and writes the name of the command to the command area of the status bar in MicroStation's main window. The ShowCommand method is used for this purpose. A user prompt is usually displayed in the prompt area of the status bar as well. The ShowPrompt method is used for this purpose.

DataPoint method

The DataPoint method is called by MicroStation when the user enters a data point while your command is active. This method receives the location of the data point and the view in which the data point was entered.

Depending on the nature of your command this method might be called more than one time before the element is drawn and added to the active model, so you may need to save data point locations. The Element Creation Command Example demonstrates a DataPoint method that saves data points in an array of Point3d data so that a line element can be created.

The DataPoint method may call the StartDynamics method of the CommandState object so that you can dynamically draw the element your command is creating. When you start the dynamics MicroStation calls your Dynamics method, which is discussed next.

Note: MicroStation automatically turns off dynamics when a command is started, so it is not necessary to call StopDynamics unless you have a specific reason to do so.

When your DataPoint sub procedure receives the last point necessary to create the element, you should draw the element being created using the msdDrawingModeNormal drawing mode, and you should add the element to the active model. Typically these tasks are done close together at the end of the DataPoint method, but this is not a requirement. Use the Redraw method of the Element class, followed by the AddElement method of the ActiveModelReference to add the element to the active model.

Dynamics method

The Dynamics method is pretty much the same as the DataPoint point method, with two exceptions. First, MicroStation is not providing the location of a data point entered by the user, but the location of the mouse pointer instead. Second, an additional parameter is passed to the Dynamics sub procedure: the drawing mode. Using the pointer location to draw the element (it is supplied in a Point3d data type) means the element is “attached” to the pointer. The Dynamics method is called every time the pointer location changes, so doing lots of calculations in this method may affect the performance of the command.

As you draw the element on the screen during the Dynamics method, use the drawing mode that MicroStation specifies in the DrawMode parameter. The code to do this is:

   oEl.Redraw DrawMode  oEl.Redraw DrawMode

See the Element Creation Command Example for an example of using this.

Reset method

The Reset method is called by MicroStation when the user presses the reset button on the mouse while the command is active. This generally signals the user has completed the command, or wants to interrupt the command, so resetting variables is performed here. Typically, the Reset method also calls the StartPrimitive method of the CommandState object to restart the command again. The code for this uses the Me keyword to refer to the current object:

     CommandState.StartPrimitive Me

Cleanup method

The Cleanup method gives your program a chance to reset any object variables it may have created and do any other necessary tasks before the command exits.

Keyin method

The Keyin method is only called by MicroStation if the user enters a keyin, and the command was initiated with a call to StartPrimitive with WantKeyins set to True. In this case, MicroStation calls the Keyin sub procedure to allow your command to respond to the key-in command. This may happen at any time while your command is active.

Running a Primitive Command tool

Since the IPrimitiveCommandEvents interface is implemented by a class, there must be some additional code written to run it. VBA cannot execute the code within a class by itself, so a standard module (also called a code module) is created with a sub procedure that will create an instance object of the class, and tell MicroStation to run it. This code looks like this:

Sub Procedure runPrimitiveTool ()
   CommandState.StartPrimitive New PlaceLineCommand
End Sub

Start method

The Start method is the same for the Locate command as for the Primitive command type. Here the program should initalize variables if they are needed, and display prompt messages to the user, usually by means of the ShowCommand and ShowPrompt methods.

LocateFilter method

The LocateFilter method is called by MicroStation when the user selects an element while the command is active. The parameters passed to this method include the element chosen by the user, the data point location that was used to select the element and a Boolean variable called Accepted, which determines whether the element is acceptable to your command. If you set Accepted to False, the element is rejected and MicroStation will search for another element using the same datapoint. If you do not set Accepted to False within the LocateFilter method, the element is accepted.

If you reject an element, MicroStation will call LocateFilter again if it finds another element at the same location, and your program must accept or reject that element. This process continues until no more elements are found at the location of the data point. If this happens, MicroStation will call the LocateFailed sub procedure.

Depending on the nature of the command, you may choose to call the StartDynamics method of the CommandState object.

Note: MicroStation automatically turns off dynamics when a command is started, so it is not necessary to call StopDynamics unless you have a specific reason to do so.

Dynamics method

Called when the user moves the pointer on the screen, the Dynamics sub procedure gives your program the opportunity to draw elements dynamically on the screen to show the user what is going on. This is helpful to the user especially if your program is moving or modifying elements using specific locations.

LocateFailed method

When all elements at the entered data point have been rejected either by your LocateFilter method, or by the user, MicroStation calls the LocateFailed method. In this method your program should reset any variables it needs for another use of the command, then call StartLocate on the CommandState object to begin the command again.

Accept method

After the LocateFilter has accepted the element passed to it, the user has the opportunity to accept or reject the element. The Accept method is called if the user enters a data point to accept the selected element. This is where your program will do the necessary work of modifying or processing the selected element according to the purpose of your command.

The Bentley MicroStation DGN 8.0 Object Library

To access the same Automation library that you see in MicroStation's Visual Basic Editor from another application, you need to add a “reference” to the MicroStation library. This requires that you have MicroStation installed on the computer where you are writing your code and also on each computer that will run the VBA program you write.

To create a reference to the DGN 8.0 library:

1. Open the Microsoft Visual Basic environment window in the application you are working in. This can usually be done with the <Alt-F11> keyboard shortcut.
2. Select the Tools menu, and choose References.
   The Reference dialog box appears displaying a list of the libraries that may be available for use with VBA on your computer.
3. In this list, scroll down until you see “Bentley MicroStation DGN 8.0 Object Library”.
4. Click the small check box next to the MicroStation DGN 8.0 Library and then click the OK button in the References dialog.
   The MicroStationDGN library will appear in the Object Browser window.