Dialog Box Manager Basic Concepts

MicroStation windows

A window is a rectangular area of the screen that has a distinctive border or window frame. Windows are the visible areas of the screen where an application interfaces with the user.

Most windows have a title bar across the top. On the left side of the title bar is the optional window menu button. When a user presses this button, the pull-down window menu displays. The window menu button and window menu are also known as the system menu button and the system menu. The contents of the window menu are fixed and cannot be changed by an MDL programmer. On the right side of the title bar are the optional window control buttons. These provide a short-cut for invoking actions contained in the window menu without having to pull it down.

A user can change the size of a window with window resize borders.

The part of a window that is within the border or frame is known as the content area or client area.

There are two types of windows that can be used with MicroStation: view windows and dialog box windows. Several different operations can be performed on MicroStation windows, whether views or dialog boxes. See "Graphic Functions" in the MicroStation MDL Function Reference Manual for more information on window related functions.

MicroStation view windows

MicroStation view windows allow the user to display and change design files. A pointer to a view window can be obtained by calling mdlWindow_viewWindowGet.

MicroStation dialog box windows and dialog items

MicroStation dialog box windows are windows that can contain dialog items. A dialog item is a user interface control that allows the user to change application settings or invoke application commands by directly modifying on-screen graphical entities. Typically, dialog items look and act like their real world counterparts, so users can intuit how to operate them. A toggle button, for example, looks and acts like the push-in toggle switches on stereo equipment. Remember that since a dialog box is a type of MicroStation window, any operation that can be performed on a window using the mdlWindow_... functions can also be performed on a dialog box.

View windows now have dialog box items on the right and bottom borders.


A resource is application data that has a programmer defined format (a resource type), is stored in a file (a resource file), and is accessed by specifying an identifying long integer (a resource ID).

The resource manager is essentially a database manager used for manipulating application data. Programmers can define their own data structures and store them in a resource file. These resources can then be accessed by specifying the resource type and resource ID of the data they wish to use. The dialog box manager makes extensive use of resources and the resource manager to partition off the "user interface look" part of an application from its underlying implementation. In fact, the resource compiler, resource librarian, and resource manager were all created to handle issues brought up during the design stage of the dialog box manager.

By specifying all aspects of the look of an application in resources within a resource file, specific details of the user interface can be changed without rewriting application code. For example, customization for foreign languages involves only the shipment of a different resource file with new text strings; the base application does not have to be modified in any way.

The use of resources also speeds the design of application user interfaces. Changing dialog boxes typically involves only the recompiling of the involved resources, not a recompile and link of the entire application. This allows prototyping to proceed at a rapid pace. Much of the look and feel of an application can be developed before any of the actual implementation begins.

Also, since resources normally reside on disk, they reduce the run-time memory requirements of an application.

To gain complete portability, MicroStation uses its own resource file format that is essentially the C syntax for initializing data structures. Once the resource file that specifies a dialog box is written for one platform, it can be recompiled without change for use on a different platform.

Each occurrence of a particular resource type used by an MDL application should have its own unique resource ID. For example, in a given application, there can only be one resource whose resource type is RTYPE_DialogBox (defined to be dBox) and whose resource ID is 1.

The dialog box manager searches MicroStation's resource files whenever a related resource cannot be found in an application's open resource files. An MDL application can therefore use any of MicroStation's dialog box manager related resources (such as the dialog items present in MicroStation's dialog boxes). To allow this capability without creating resource ID conflicts with other developers, all of MicroStation's built-in resources have negative resource ID numbers. These resource IDs are defined in the header file dlogids.h. Other developers should use only positive resource ID numbers.

Resource ID numbers should be defined in their own .h file. This file will then be included in both an application's resource files, and in its MDL program files that need to refer to specific item IDs.

See "Resources" and "Resource Management Functions" in the MicroStation MDL Function Reference Manual for more information about the MicroStation resource manager.

Dialog item resource specifications and item list specifications

The dialog box manager design allows dialog items to be reusable. To accomplish that goal, a dialog box item is composed of two separate pieces: a dialog item resource specification and a dialog item list specification.

A dialog item resource specification contains the complete behavioral description of an item and is uniquely identified by the combination of its resource type and resource ID. Other item information includes:

The item's location within a particular dialog box is not specified. Therefore, the same item can be used and placed in different dialog boxes by referencing its resource type and resource ID. It will look the same and affect application variables identically in each instance.

There is one item list per dialog, and each item within a dialog box has an entry in that list - a dialog item list specification. A dialog item list specification not only specifies the resource type and resource ID of the item to include in the dialog box, but also its position and size. Most other user interface toolkits pack positioning information with other item information in their item lists, thus preventing the item's reuse in a different dialog box. See DialogItemRscStructure for more information on dialog item lists.

Sometimes most of an item's resource specification is usable in another situation, except for a small portion, such as the item's label or the string that specifies which application variable to control. To handle those situations, the dialog box manager allows for overriding of certain item resource specification fields with information specified in the item list. Currently it is possible to override an item's label or access string with item list specifications. For example, the standard MicroStation toggle button item that controls the TCB grid lock variable could be included in a dialog box and labeled "Lock cursor to grid" instead of "Grid Lock."

The file dlogids.h contains the resource IDs of all of the dialog items that are used in MicroStation. Most of these items can be used in a dialog box simply by including the proper resource type and the listed resource ID in the dialog's item list. The programmer does not have to specify the details of the item's resource specification. MicroStation's predefined resource for that item will automatically be used.

Dialog item state: internal value versus external state

The state of a dialog box item is composed of two parts: the item's internal value and the item's external state.

An item's internal value is the simple C variable, hidden within the item's private data structures, which is referenced whenever the item needs to be displayed. Currently all items, except the text item, keep their values in signed long integers. The text item keeps its internal value as a NULL terminated string. For example, a toggle button is implemented with a hidden variable that can be either 0 or 1, indicating whether the toggle button is currently depressed or not. MDL dialog box manager functions exist to get or set an item's internal value.

An item's external state is the value of the application data that the item controls. For example, suppose a toggle button controls the TCB variable for grid lock, tcb->control.grid_lock. In this case, the item's external state matches the value of tcb->control.grid_lock. The application data that determines an item's external state is not necessarily a simple C variable. With hook functions, which are discussed later, it is possible to consider multiple pieces of data as the item's state. There are MDL dialog box functions to get or set an item's external state.

Since items are used to graphically depict the state of application data in an intuitive way, an item's internal (and therefore displayed) value usually matches its external state. When an item is initially created, the item's external state is retrieved and the internal state is set accordingly. The item's initial appearance thus matches the state of the application data being controlled. Whenever the user interacts with an item, changing its appearance and therefore its internal value, the item's external state is also updated to reflect the change.

An item's internal value and external state thus represent two different parts of an item's state. The internal value represents the state of the item's appearance on the screen. The external state represents what the application thinks the item's state should be. In ModelessAndModalDialogBoxes and ItemSynchronization , it is important to understand this distinction.

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