Debugging Hook Functions

The Dialog Box Manager Message dialog

The dialog box manager provides the "Dialog Box Manager Messages" dialog box for displaying debugging or other messages. It contains a list box item in which message lines are stored as rows in the list. These messages can be browsed through by scrolling through the list in the usual manner. The "Messages" dialog box is very handy when debugging with only one screen or when running MicroStation in a dual-screen configuration.

Messages are always added to the end of the list and up to 100 text lines can be stored at one time. When the 101st text line is added, the first 50 text lines are deleted and the new text line becomes the 51st row.

Displaying strings

A message can be displayed in the "Messages" dialog box by calling mdlDialog_dmsgsPrint(char *messageString). If the "Messages" dialog box is not visible, this function will also open it. messageString can contain embedded `
' characters that will cause the next list row to be used.

mdlDialog_dmsgsClear(void) clears the "Messages" dialog box. It takes no arguments.

Tracking hook function messages

One of the more difficult parts of learning to use the MicroStation dialog box manager is understanding the type, order, and contents of the many messages that can be sent to hook functions. To ease this task, the dialog box manager, upon request, can send information about every message that is sent to dialog hook functions, item hook functions, or item handlers to the Messages window. To get this information about dialog hook function messages or item hook function messages, a hook must be attached to the appropriate dialog or item.


The following MicroStation key-ins control the display of hook function message information. They each open the Messages window if it has not been already:

Key-in Description
DMSG ITEMDEBUG [on/off] Turns on/off the display of all dialog box item messages that have been sent to item hook functions. If an item does not have an item hook function no debugging messages will be displayed for it.
DMSG HANDLERDEBUG [on/off]Turns on/off the display of all dialog box item messages that have been sent to item handlers. These messages are displayed whether or not items have attached hook functions. Remember, messages that are sent to item
handlers do not necessarily get passed on to item hook functions. It is up to the handler to decide if a message should be sent to any attached hook functions.
This command is less useful than
DMSG DIALOGDEBUG [on/off] Turns on/off the display of all dialog box messages that have been sent to dialog hook functions. If a dialog box does not have a dialog hook function attached to it, no debugging messages will be displayed for it.
DMSG VERBOSEDEBUG [on/off]Turns on/off the display of detailed debugging information for all of the above commands.
DMSG ACTION SHOWMNEMONIC Displays an alphabetized list of a dialog's keyboard mnemonics. Useful for guarding against key conflicts. To obtain info on dialogs other than the Command Window, you must assign this key-in to a function key or access it
via the shortcut <Control><Alt><Shift>-M.
DMSG CLEARDEBUG Clears the "Messages" dialog box.

Closing the "Messages" dialog box will turn off all message debugging. A DMSG xxxDEBUG command must be reentered to continue tracking the dialog box manager messages.

Sometimes it is useful to display dialog box manager message information under program control. The following library functions are available to perform this task:

mdlDialog_dmsgsSet(boolean dialogMessages, boolean itemHookMessages, boolean itemHandlerMessages, boolean verbose) controls which types of messages for which information will be displayed. Set the dialogMessages, itemHookMessages or itemHandlerMessages parameter to TRUE to display information for those types of messages. Set verbose to TRUE to turn on detailed information for any displayed messages.

mdlDialog_dmsgsPrintItemMsg(DialogItemMessage *dimP, boolean filterCommandWindow, boolean fromHookFunction) displays information on the dialog item message dimP in the "Messages" dialog box. It can be used to display information on messages that are being sent to a particular item hook function. The last two parameters should always be set to TRUE.

mdlDialog_dmsgsPrintDialogMsg(DialogMessage *dmP, boolean filterCommandWindow) displays information on the dialog message dmP in the "Messages" dialog box. It can be used to display information on messages that are being sent to a particular dialog hook function. The last parameter should always be TRUE.

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.