Where Do I Start?
This is a common question when creating a new application in a new development environment, especially in a graphical user interface (GUI) environment where a program's structure tends to be more complex than in traditional top-down programs.
With many functions to choose from in MDL, the prospect of building an application may seem daunting. A developer needs a "road map" for guidance through the design and implementation of an MDL application.
Before you go into the details of your application's design, you must first have a functional specification that describes what the application is to perform. This description should be from the user's viewpoint. Few or no details specific to the development environment (MDL in our case) should be present. If done well, a functional specification of this sort leads directly to a high level design.
We recommended using the following approach to create a functional specification that translates easily into a high level design.
Define the objects
Define the types of objects that users of the product will manipulate in terminology that is familiar to the users. For example, GIS users work with parcels, so definitions of these are in the functional specification. GIS users are also accustomed to thinking about their work in terms of projects.
List the attributes of the objects
What shapes, sizes, colors, etc., are valid for each type of object? Furthermore, what attributes are mutually exclusive?
Define the object placement and manipulations
Once you have fully defined the objects and their attributes, define the ways in which the objects are placed and manipulated.
Other required functionality
Other items in the functional specification might be the types of database information to maintain, report formats, and any other processing that does not involve object manipulation.
High-level MDL application design
Determine MicroStation elements to use to represent application objects
The objects that are defined in the functional specification must be represented by elements in the design file. For example, GIS represents parcel markers as centroids (small rectangles).
Determine what settings must be collected from the user
The attributes of the objects listed in the functional specification help us determine the form of our data collection and organization. We refer to this information in our MDL application as settings. Once we know the settings to collect and how to organize them, we can design dialog boxes that allow the user to set them.
Design element placement and manipulation tools
The part of the functional specification that defines object placement and manipulation is the basis for a list of the application's commands. Knowing this, we can build the command tables and tool boxes, and start designing the element placement and manipulation routines.
Design tools and settings boxes for other functionality
The other items in the functional specification also require user interface and processing routines.
Project task list
When the high level design is complete, a project task list emerges. Although the actual list is different for each application, we can identify a superset of the items most likely to appear on such a list.
Application initialization logic (main() processing)
This is the logic that sets up the application for all future processing. Among the tasks to accomplish are:
Open resource files for dialog boxes, command tables, and message lists.
Register message list IDs to be used for prompts or errors.
Load command tables.
Set user hooks for system events (For example, UNLOAD or RELOAD.)
Register dialog hook functions with MicroStation's Dialog Box Manager.
Open the application's initial dialog box.
After the initialization is complete, the main function returns and the application waits for one of its dialog box hooks, user hooks, or command functions to be invoked.
Build a cell library:
An application that requires a set of pre-defined graphic symbols to represent the objects of the system should have its own pre-built cell library. The cell library is generated by the developer and then packaged with the application. For information on cells and how to create them, see "Cell Placement and Manipulation" (General procedures for working with cells) and "Menu Reference" (Settings menu) in the MicroStation On-line Reference Guide. An example of cell creation is in "Learning MicroStation" (Lesson 1) in the MicroStation User's Guide. For information about using cells in your MDL applications, see "Element Creation" (mdlCell_create), and "Cells" in the MicroStation MDL Function Reference Manual.
Create command tables:
A command table defines the syntax of an application's commands. Command tables are hierarchical with one main table branching downward into a tree of subcommands. An application's command table is defined in a resource source file that is compiled to produce two output files Ñ one is for the parsing and validation of key-ins, and the other is a list of unsigned integers that uniquely identifies each command. For more information on the creation and use of command tables, refer to Building Application
Build dialog boxes:
Dialog boxes present and collect data. See CreatingDialogBox for a general procedure for building dialog boxes that makes them easier to debug.
Write primitive command logic:
Write all of the application's primitive command routines that handle element placement and manipulation. Each primitive command requires setting up state functions for the handling of events such as data points, resets and to display dynamics - that is display an element as it is dragged across the screen, sometimes referred to as "rubberbanding."
Write logic for immediate and utility commands:
An immediate command is a command that sets the value of an internal settings variable. In MicroStation versions 4.0 and later, dialog boxes are a much more elegant way to set the value of internal variables, and as a result there is less need for immediate commands. However, there are times when it may still be necessary to define immediate commands. For instance, if you foresee the need to set an MDL application variable from a MicroCSL program or user command, an immediate command must be defined because MicroCSL programs and user commands cannot display dialog boxes. A utility command is a command that does not require interactive input from the user and does not merely set application variables.
Build tool boxes:
Tools are graphic icons that start commands. When the user clicks on a tool, the appropriate command is started. An application with MicroStation's "look and feel" has at least one tool box if it provides commands to the user. In the initial stages of development, it is not absolutely necessary to create a tool box since commands can be keyed in. However, testing is much easier when you can click on an icon to start a command instead of keying it in.
The degree of external processing used by an application varies from none to all depending on the purpose, and sometimes the history, of the application. A developer with an existing MicroCSL application may only want to exploit parts of MDL. For example, an MDL "front-end" could be written with a message queue or shared memory interface to the MicroCSL program. On the other hand, a developer may wish to totally re-implement an existing external program in MDL. Somewhere in between the two extremes is a MicroCSL program that has part of its functionality moved into MDL or vice versa. An external program does not have to make MicroCSL calls.
Create on-line help:
Like documentation, on-line help usually begins to take shape later in the development cycle of a product. Implementing on-line help is a matter of creating help resources containing textual information and associating them with certain commands, dialog boxes, or dialog items. Help resources can also be "stand-alone;" that is they can only be referenced by manually traversing the help topics in MicroStation's Help dialog box.