Managing Resources

MicroStation provides a complete set of functions which can be used to manage and operate on resources. Resources can be directly accessed using the Resource Manager or accessed indirectly using the various interface functions provided by the Dialog Manager, Command Parser and Message Subsystem. These interfaces are discussed below.

Message Subsystem

The message subsystem provides mechanisms for retrieving text strings from your resources and displaying that text in the MicroStation Command Window or dumping the text to either a file or a buffer. These are the mdlOutput_rsc... functions which accept a resource file handle, resource ID, and string (message) list index value of the string to be displayed as input. These functions then retrieve the string from the appropriate resource and resource file and display it in the specified field of the Command Window. No other functions are provided for retrieving and displaying strings from a message list. Only by using the Resource and Dialog Managers directly can you perform any other string/display processing to MicroStation windows.

Command Parser

In addition to performing the actual translation of key-ins into commands, the Command Parser provides various functions for loading and handling the command table resources which provide the foundation of MicroStation.

Many people still have a hard time thinking of the command tables of MicroStation as being simple tables of a parse tree which are statically loaded into MicroStation. But, that is exactly what they are. If the command tables were actually dynamic or compiled directly into the application (including MicroStation), then the Command Parser would be unable to offer the flexibility and extensibility it currently provides.

Command tables are defined in resource files as a series of parse trees which are compiled by the resource compiler. A sample command table is provided below:

#include <rscdefs.h>
#include <cmdclass.h>
-------------------------------------------------------------------+
| |
| Local Defines |
| |
+-------------------------------------------------------------------
#define CT_NONE 0
#define CT_MAIN 1
#define CT_LOAD 2
#define CT_OPEN 3
// Application Command Tables
Table CT_MAIN =
{
{1, CT_LOAD, INPUT, HID, "LOAD"},
};
Table CT_PALLOAD =
{
{1, CT_OPEN, INPUT, NONE, "OPEN"},
{2, CT_NONE, INPUT, NONE, "ADDMENU"},
{3, CT_NONE, INPUT, CMDSTR(1), "KEYIN"},
};
Table CT_OPEN =
{
{1, CT_NONE, INPUT, NONE, "PALETTE"},
{2, CT_NONE, INPUT, NONE, "AUTO"},
};

When the command table resource is compiled and a header file generated which contains the command numbers for each command, the application can hook functions to handle each command and the command table resource can be loaded into MicroStation so that the user can access those commands when the application is loaded.

The following sections provide an overview of the general command table resource management functions available.

mdlParse_loadCommandTable

This function will load the application's command table into memory and "merges" it into MicroStation's parse tree for processing commands keyed-in from the Command Window. This function starts loading command table resources from the specified resource file starting at resource ID 1 and continues loading all tables which are part of the parse tree. This function should be called once from the main entry point of an application. This function returns a pointer to the parse table descriptor created after loading the command table successfully. The pointer can be used to later unload the parse table if needed.

mdlParse_unloadTable

This function unloads the specified command table from MicroStation and frees the command table resource from memory. Most applications do not need to worry about this call since this operation is performed by MicroStation when an application is unloaded from memory.

mdlParse_loadKeywordTable

This function is useful for loading an alternate command table resource into memory for use only by the application through using the mdlParse_keyWord function. This function does not provide a table descriptor upon return, and therefore does not allow the unloading of the table from memory until the application exits (i.e., is unloaded).

Dialog Box Manager

The Dialog Box Manager is by far the most common resource interface for the applications programmer. This interface provides the only way for providing a MicroStation compatible user interface to an application or to display dialog boxes on the screen. This interface performs all resource file management for the user as far as dialog boxes and items are concerned. When a single dialog box is opened using mdlDialog_open (or one of the other mdlDialog_open_... functions), the Dialog Manager goes out to the specified resource file, loads the dialog box resource indicated, and then loads each associated dialog item resource into memory as well. It also manages the display of the resources on the screen and the dynamic modification of the resources in memory via the mdlDialog_... functions provided for this purpose.

Functions are provided to allow the label, location, size and attributes of an in-memory resource to be changed dynamically for an occurrence of the dialog box or item. In some cases, this modification is not to the actual copy of the resource itself, but instead to a decoded internal representation of that resource.

The Dialog Manager even controls the freeing of all loaded resources intrinsically as part of the management of the GUI display environment.


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