Here are answers to questions about MicroStation^® dialog boxes that are posted from time to time on the Bentley Discussion Groups. The questions are posted by MDL developers.

Q MicroStation's Dialog Manager provides an elegant mechanism to exchange data between application variables and dialog items.

• What is the Dialog Manager?
• What is an Access String?
• How do I exchange data between an application variable and a dialog item?

A The Dialog Manager is the engine that manages MicroStation user interface components, including dialog boxes and toolboxes. It makes life simple for MDL developers who want to display data stored in an application variable, and let a user view and update that information.

Note for Windows Win32 Programmers

If you've come from a Win32 developer background, you're probably familiar with the tedious business of writing code to copy data from a variable into a dialog item, then retrieving the value with more code when the user changes something. MicroStation's Dialog Manager handles data exchange automatically. Furthermore, it makes it easy to create multiple modeless dialogs that work with little effort on your part.

Dialog Manager

MicroStation support both modal and modeless dialog boxes. A modal dialog box usually has OK and Cancel buttons, and everything stops while the dialog is open. When the user presses OK or Cancel the dialog vanishes and normal life can continue. A modeless dialog does not interfere with MicroStation's operation: the user can modify items in the dialog and continue working. Many dialogs in MicroStation are modeless, the most obvious being the Tool Settings box that appears whenever a command starts.

The Dialog Manager works silently and tirelessly to handle user interface objects. It also implements the mechanism that exchanges data between your Application Variable and a dialog item. Your code interacts directly with the Dialog Manager just once, during application startup: you publish the your application variable. When you publish a variable, the Dialog Manager knows its data type, address, and name. The same variable appears in your dialog item as an access string.

The Dialog Manager includes a C expression handler. This engine provides a run-time facility to evaluate symbols. A symbol can be as simple as a variable name (an access string), or any expression that conforms to C language syntax.

There's more! The Dialog Manager can perform run-time value checking as a user edits a dialog item. You can specify, for example, minimum and maximum values for numeric variables.

Suppose you want to store a number in a variable. You must declare the variable with global scope, then publish it, usually in your main() function …

//  Declare a public variable to store a numeric value
Public char g_lngNumber;
...
int main (...)
{
  char*    setP;   // A pointer to a "C expression symbol set"

  //  Publish the variable to notify the Dialog Manager
  setP = mdlCExpression_initializeSet (VISIBILITY_DIALOG_BOX, 0, FALSE);
  mdlDialog_publishBasicVariable (setP, &longType, "g_lngNumber", &g_lngNumber);
}

Application Variables

The Dialog Manager understands simple and complex variables. A simple variable can be any of the C language native data types: int, long, double, etc. A complex variable may be a struct, array, or pointer.

One of the mdlDialog_publishXxx family of functions is used to describe your variable to the Dialog Manager.

When you open a modal dialog, the Dialog Manager transers data from your application variables to the dialog as it opens. When you click the OK button, the Dialog Manager copies data from the dialog items to your application variables.

When you open a modeless dialog, the Dialog Manager copies data from your application variables to the dialog when it first opens. The Dialog Manager may also update a dialog item when its application variable changes: this happens automatically when an item is a member of a synonym list, and you can cause it to happen programmatically. Whenever a user changes the value of a dialog item, the Dialog Manager copies data from the item into your application variable.

Access Strings

In the definition of a dialog item, use your variable as the access string. For example, you may have a text item that will display the value of a long variable. Here's an item resource definition …

DItem_TextRsc  TEXTID_Number =
{
  NOCMD,
  LCMD,
  NOSYNONYM,
  NOHELP,
  LHELP,
  NOHOOK,
  0,
  20,
  "%ld",             // Formatting
  "%ld",             // Formatting
  "",                // Numeric minimum value
  "",                // Numeric maximum value
  NOMASK,
  TEXT_NOCONCAT,
  "Number:",         // Label
  "g_lngNumber"      // Access String
};

Because you've published your application variable, the Dialog Manager can connect the access string in the item definition with the variable. In fact, the Dialog Manager evaluates the access string using its internal C expression handler. Since the variable name is a valid C expression the Dialog Manager can pass its value to your variable.

Return to MDL articles index.