Introduction

The MicroStation Development Library (MDL) and MicroStationAPI provide APIs for developers wanting to create custom applications for MicroStation^® from Bentley Systems. We create a MicroStation application as a DLL, written using C++ and built with the Microsoft C++ compiler and linker provided with Visual Studio.

When editing your source code, you can choose whether to use Microsoft Visual Studio, Microsoft Visual Studio Code, or one of your favourite text editors.

When building your app, you can use Visual Studio or the Bentley Systems make (bmake) tools.

Message Center

Questions similar to this appear on the Be Communities. These problems appeared in the MicroStation Programming Forum.

Q   MDL developers often want to trace the variables in an application during development …

• How do I show the state of my MicroStation C++ application?
• How do I capture the value of a variable?
• I can see the text from mdlOutput_status (msg) but I can't copy it.
• Can I ask my application's user to provide more information as my program executes?
• Can I show a dockable information window?
• How do I open the Message Center programmatically?

A  MicroStation's NotificationManager (also known as the Message Center) provides a way for you to communicate with your user. You can create terse and verbose messages with various priorities: simple messages, warning, or alerts. Your user can copy messages (which they could never do with the old DMSGS message window). You can write messages that are only seen when the user has enabled Debug in the Message Center.

MicroStation V8 and earlier provide a programmer's DMSGS message window to which you send text using mdlDialog_dmsgsPrint (msg). In normal MicroStation operation the user doesn't see the DMSGS window.   MicroStation CONNECT continues to support the DMSGS window.

MicroStation Message Center for Developers

MicroStation CONNECT sends many messages to the  Message Center.  Status and message information are sent there. As a developer, you should investigate the Message Center: it has a number of useful features …

• The Message Center is resizeable
• The Message Center is dockable
• The horizontal splitter in the Message Center can be moved
• When you select a message in the Message Center its content is copied to the lower panel
• You can select & copy text in the lower panel
• If you right-click the Message Center, you pop a settings dialog
• You can specify the number of lines captured by the Message Center
• You can specify whether the Message Center displays debug messages
• You can save the content of the Message Center to a text file

Sending a Message

You send a message to the Message Center using the mdlOutput_messageCenter () function. The function takes four arguments  …

1. DgnPlatform::OutputMessagePriority: Error, Warning, Info or Debug
2. Unicode Brief message
3. Unicode Long message
4. DgnPlatform::OutputMessageAlert: Dialog, Balloon or None

The message priority enums are defined in header file <DgnPlatform/DgnPlatform.h>.  The two messages are typically Bentley::WString classes or WChar [] buffers.   The final argument is a bool flag that tells MicroStation to pop a modal dialog with your message.

Here's an example using the BeFileName class to parse file name components …

#include <Bentley/BeFileName.h>
#include <DgnPlatform/DgnPlatform.h>

void messageCenter_showFile (WCharCP fileSpec, bool debug, bool alert)
{
    ///	Determine where to send the message
    const DgnPlatform::OutputMessagePriority  priority = debug
      ? DgnPlatform::OutputMessagePriority::Debug
      : DgnPlatform::OutputMessagePriority::Info;
    /// Send to Message Center: pop dialog if 'alert' is true 
    const DgnPlatform::OutputMessageAlert pop	= alert
      ? DgnPlatform::OutputMessageAlert::Dialog:
      : DgnPlatform::OutputMessageAlert::None;

    WString    dev;
    WString    dir;
    WString    name;
    WString    ext;
    BeFileName::ParseName (&dev, &dir, &name, &ext, fileSpec);
    /// Format brief and long messages 
    WString    terse;
    WString::Sprintf (terse, L"File '%s'", name.c_str ());
    WString    verbose;
    WString::Sprintf (verbose, L"File path '%s', fileSpec);
    mdlOutput_messageCenter (priority, terse, verbose, pop);
}

The difference between the brief and long messages is that the brief message is always displayed in the Message Center, but the long message is shown in the lower panel only when the user selects the brief message in the top panel.

MicroStation messages are sent with one of the first three priorities: error, warning, or information. Each has a distinctive icon.  The final priority is debug, available exclusively to you as a developer.  Debug messages are shown only when the Debug option is checked in the Message Center's option dialog.

Message Center Properties

When the user right-clicks the Message Center the properties modal dialog opens. She can specify …

1. Whether or not to see debug messages
2. How many lines of text the Message Center should buffer
3. A save file for the Message Center text content

The Message Center's line buffer size (Number of Messages setting) is a little idiosyncratic.  When you change Number of Messages, the buffer size changes immediately.  However, when you exit and restart MicroStation, the buffer always starts with 50 lines, irrespective of how many lines you specified. The trick is to modify this number before attempting to capture a large amount of text.

Open the Message Center Programmatically

The Message Center is a MicroStation dialog box. Whether using the MicroStationAPI, you can open it with this one-liner …

mdlDialog_open (nullptr, DIALOGID_MessageCenter);

If writing VBA, then you must declare that MDL function before calling it …

Declare PtrSafe Function mdlDialog_open Lib "stdmdlbltin.dll" ( _
    ByVal rFileH As Long , _
    ByVal resourceId As Long ) As Long
Const DIALOGID_MessageCenter As Long = -401  '  From <dlogids.h>
…
mdlDialog_open 0, DIALOGID_MessageCenter

Saving Messages

Another option you have when you right-click the Message Center is to Save Messages.

When you choose this option, you see a File Save dialog, which lets you copy the entire message buffer to a text file.

Debug Messages

Your code can place messages in the Message Center using the DgnPlatform::OutputMessagePriority::Debug priority. Your users won't see Debug messages unless they have enabled the Message Center's debug option. Therefore you can use Debug messages to get more information from your users. Suppose, let's say, your code is using a material table file but the user is seeing incorrect results. You can provide additional debug messages in your code that confirm the location of the file being used. Ask the user to right-click the Message Center and enable the Display Debug Messages option to see diagnostic information, such as the genuine location of the file being used.

Bentley::DgnPlatform::NotificationManager

The MicroStationAPI (a C++ interface) provides the NotificationManager class. This class has several methods, including OutputMessage (NotifyMessageDetails const &message).

#include <DgnPlatform/NotificationManager.h>

The NotifyMessageDetails class provides methods to set your message contents and priority.

The NotificationManager class provides methods to send output to the Message Center.

The NotificationManager is an object-oriented alternative to the declarative programming used to write to the Message Center. However, because it's a class you can inherit from it to add features. For example, you might write a LoggingNotificationManager that logs messages to a file in addition to displaying them in the Message Center.

Return to the MicroStationAPI articles index.

Questions

Post questions about C++ and the MicroStationAPI to the MicroStation Programming Forum.