The Dialog Box Manager (DBM) allows the creation of customizable dialog boxes for Mastercam. Under this scheme, a programmer or user can write an ASCII text script and a C module to design a dialog box for the Microsoft® Windows® 95 and Windows NT® operating environments and get user input through various standard Windows user interface elements. The Dialog Box Manager's use of text scripts allows on-site customization and language translation. Dialog scripts are stored in ASCII text files. The Dialog Box Manager reads a specified script in a specified file at run-time and creates a dialog box. This allows for a trial and error approach to dialog box design, without having to recompile or even restart the application. However, it also creates the possibility of erroneous dialog scripts being created and the generation of confusing results. The user should limit modifications to strings in double quotes.
Note: Due to the conceivable complexity of a dialog box, the Dialog Box Manager (DBM) imposes some reasonable limitations on the type of activity allowed in the dialog box created through it. The programmer is free, however, to bypass the DBM and handle dialog boxes completely on his/her own.
The Dialog Box Manager supports most of the MS-Windows stock (built-in) controls. It enhances their functionality by providing features such as data type and range restricted EDIT controls, STATIC controls with icons, BUTTON controls with bitmaps, and 3D look for all controls. In addition, the DBM provides a few unique features (listed below), which are extremely useful in designing a sophisticated user interface without having to write a lot of code.
Control callback functions which can be reassigned at run-time
Control associated data variables which can be reassigned at run-time
Inter-control messaging for user-interface element synchronization
Multiple control pages with fast scrolling
With these features, the DBM allows any C programmer to build a fairly sophisticated GUI very quickly. It is not meant to replace the knowledge of MS-Windows programming completely. We recommend the Microsoft Win32 Programmer's Reference (Volume 1).
The Dialog Box Manager provides an API consisting of a small number of C language functions. The programmer is responsible for providing accurate information to the Dialog Box Manager through the text script. The Dialog Box Manager will not verify the input data, such as the location and size of controls.
Each dialog script file consists of several lines of ASCII text, which describe the dialog and its controls. A script file may contain more than one dialog script. Each script is identified by a numeric field that must be unique within a script file. A dialog script has only two mandatory script statements:
DIALOG n .
This statement marks the beginning of a dialog script and specifies the layout of the dialog window.
ENDDIALOG
This statement marks the end of a dialog script.
The following example shows the appearance of a script f 818b17i ile in a single page format.
DIALOG 1 'Mastercam sample dialog', WS_VISIBLE, 20, 10, 131, 29
// Exit controls
BUTTON 'Cancel', , DBM_CANCEL | WS_GROUP | WS_TABSTOP, 86, 1, 20, 3
BUTTON 'Done', , DBM_OK | WS_TABSTOP, 108, 1, 20, 3
STATIC '1', , DBM_STATICHDIP, 0, 5, 131, 1
// Other controls
BUTTON 'Delete old stuff', 1, BS_AUTOCHECKBOX | WS_GROUP | WS_TABSTOP, 2, 7, 30, 3, , delete_old, sample5
BUTTON 'Keep new stuff', 2, BS_AUTOCHECKBOX | WS_TABSTOP, 2, 11, 30, 3, , keep_new, sample5
ENDDIALOG
The following example shows the appearance of a script f 818b17i ile in multiple page format.
DIALOG 1 'Mastercam sample dialog', WS_VISIBLE, 20, 10, 131, 29, 2, 5
// Common (static area) controls
STATIC 'Current page:', , SS_CENTER | DBM_STATICUP, 2, 1.5, 30, 2
BUTTON '1', , BS_AUTORADIOBUTTON | DBM_NEWPAGE | WS_GROUP | WS_TABSTOP, 34, 1.5, 8, 2
BUTTON '2', , BS_AUTORADIOBUTTON | DBM_NEWPAGE | WS_TABSTOP, 44, 1.5, 8, 2
BUTTON 'Cancel', , DBM_CANCEL | WS_GROUP | WS_TABSTOP, 86, 1, 20, 3
BUTTON 'Done', , DBM_OK | WS_TABSTOP, 108, 1, 20, 3
STATIC '1', , DBM_STATICHDIP, 0, 5, 131, 1
// Page one controls
NEWPAGE
BUTTON 'Delete old stuff', 1, BS_AUTOCHECKBOX | WS_GROUP | WS_TABSTOP, 2, 2, 30, 3, delete_old, , sample2
BUTTON 'Keep new stuff', 2, BS_AUTOCHECKBOX | WS_TABSTOP, 2, 6, 30, 3, keep_new, , sample2
// Page two controls
NEWPAGE
BUTTON 'Fillet intersections', 3, BS_AUTOCHECKBOX | WS_GROUP | WS_TABSTOP, 2, 2, 30, 3, , fillet_int, sample 2
BUTTON 'Trim entities', 4, BS_AUTOCHECKBOX | WS_TABSTOP, 2, 6, 30, 3, , trim_ents, sample 2
ENDDIALOG
The following information will help you work with script files.
Blank lines are not allowed within a dialog (between DIALOG and ENDDIALOG).
Static area controls should be listed before the first NEWPAGE command.
NEWPAGE commands should not be used within a single page dialog.
Edit controls must contain an exported data variable.
Combo box and list box data variables must be initialized before 'dbm_run_dialog' is called.
Scroll bar data variables must be initialized before 'dbm_run_dialog' is called.
All dialogs within a script file must have unique dialog 'id' numbers.
All controls within a dialog must have unique control 'id' numbers.
All controls are initialized and drawn sequentially.
All pages are initialized at run-time.
A dialog statement has the following components in the order presented below. Each of these parts is described in further detail beginning with 'Dialog Identification Number [number]' on page and ending with 'Dialog Pages [pages, static ht]' on page
DIALOG number, 'title', flags, left, top, width, height, pages, static ht
If dialog does not require 'title,' leave space between double quotes (' ').
If dialog does not require 'flags,' leave space between comma (, ,).
If dialog contains less than two pages, omit 'pages, static ht.'
This parameter identifies the dialog box to the dialog manager and the programmer. To execute a dialog box, the programmer must specify the script file name and the dialog's identification number. This allows a script file to contain multiple dialogs. Each dialog within a script file must be assigned a unique 'id' number. Dialogs that are defined in separate files may have the same 'id' number.
dbm_run_dialog (script name, number, mode, page, parent, handle, modname);
dbm_run_dialog ('sample.scr', 1, MODAL, 1, dbm_get_mainwnd_id(), NULL, NULL);
This parameter defines the dialog's caption. It must be enclosed in double quotes (i.e., 'Hello'). If no caption is required, a space must be inserted between the double quotes (i.e., ' '). The WS_CAPTION flag may be added to the 'flags' section of a dialog statement to activate the dialog's caption.
These optional flags allow the programmer or user to customize the dialog's window. The Dialog Box Manager uses the standard dialog box format (visible popup dialog with border and caption) by default.
The following flags are supported, but have no noticeable effect:
WS_BORDER Creates a dialog box with a thin-line border
WS_CAPTION Creates a dialog box with a title bar (includes WS_BORDER style)
WS_DISABLED Creates a disabled dialog box (not recommended)
WS_DLGFRAME Creates a dialog box with a double border (no title)
WS_EX_DLGMODALFRAME Creates a dialog box with a title bar and double border
WS_OVERLAPPED Creates a dialog box with a title bar and border
WS_POPUP Creates a dialog box with a title bar and border (title bar is optional)
WS_VISIBLE Default state
The following flags should not be used:
WS_HSCROLL Dialog horizontal scrolling is not supported by DBM.
WS_MINIMIZE Dialog sizing is not supported by DBM.
WS_MINIMIZEBOX Dialog sizing is not supported by DBM.
WS_MAXIMIZE Dialog sizing is not supported by DBM.
WS_MAXIMIZEBOX Dialog sizing is not supported by DBM.
WS_OVERLAPPEDWINDOW Dialog sizing is not supported by DBM.
WS_POPUPWINDOW Dialog sizing is not supported by DBM.
WS_SYSMENU Flag not supported by DBM.
WS_THICKFRAME Dialog sizing is not supported by DBM.
WS_VSCROLL Dialog vertical scrolling is not supported by DBM.
Dialogs are positioned relative to the upper-left corner of the dialog's parent window. Most dialogs use the main application window as their parent. The dialog manager also allows dialogs to be 'nested.' Nested dialogs are positioned relative to the upper-left corner of another dialog.
The 'left' and 'top' parameters define the position of the upper-left corner of the dialog relative to its parent in half character units. The 'width' and 'height' parameters define the size of the dialog in half character units. Fractional half character units are supported (ex: 2.5, 10.1, 30.25, 40.95).
Programmer must specify dialog's 'parent' in the 'dbm_run_dialog' function:
dbm_run_dialog (script name, number, mode, page, parent, handle, modname);
Dialog is relative to main application window (not nested):
dbm_run_dialog ('sample.scr', 1, MODAL, 1, dbm_get_mainwnd_id(), NULL, NULL);
Dialog is relative to another dialog (nested):
dbm_run_dialog ('sample.scr', 1, MODAL, 1, cbdat.pid, NULL, NULL);
Note: If 'cbdat.pid' equals 'dbm_get_mainwnd_id()' the dialog is relative to main application window.
A dialog box may contain up to four pages. Paging allows a user to flip between different sets of controls on a dialog box without having to scroll. All pages within a dialog have the same overall dimensions as defined by the 'width' and 'height' parameters in the 'DIALOG' statement. The 'pages' parameter defines the number of pages in the dialog. The 'static ht' parameter defines the height of a common area, which is displayed on all pages. It is generally used to display 'Cancel,' 'Done,' and paging buttons.
Multiple page dialogs must contain a consistent number of paging controls. For example, if you define a dialog with two pages, your script must contain two DBM_NEWPAGE flags and two NEWPAGE commands, as shown in the following example:
DIALOG 1 'Mastercam sample dialog', WS_VISIBLE, 20, 10, 131, 29, 2, 5
// Common (static area) controls
STATIC 'Current page:', , SS_CENTER | DBM_STATICUP, 2, 1.5, 30, 2.5
BUTTON '1', , BS_AUTORADIOBUTTON | DBM_NEWPAGE | WS_GROUP | WS_TABSTOP, 34, 1.5, 8, 2
BUTTON '2', , BS_AUTORADIOBUTTON | DBM_NEWPAGE | WS_TABSTOP, 44, 1.5, 8, 2
BUTTON 'Cancel', , DBM_CANCEL | WS_GROUP | WS_TABSTOP, 86, 1, 20, 3
BUTTON 'Done', , DBM_OK | WS_TABSTOP, 108, 1, 20, 3
STATIC '1', , DBM_STATICHDIP, 0, 5, 131, 1
// Page one controls
NEWPAGE
// Page two controls
NEWPAGE
ENDDIALOG
The 'pages' and 'static ht' parameters must be omitted if the dialog contains less than two pages.
Single page dialogs must not contain 'DBM_NEWPAGE' flags or 'NEWPAGE' commands.
Single page dialogs can not contain a 'static' area.
The NEWPAGE command is used to mark the start of each page in a dialog. The number of NEWPAGE commands within each dialog must match the number of pages specified in the dialog statement.
The basic NEWPAGE command has no parameters. However, the DBM does support an expanded NEWPAGE command with the following format:
NEWPAGE script file name, dialog number
The Dialog Box Manager opens 'script file name' and reads 'dialog number.'
The specified 'script file name' must be different from the name of the current script file.
The specified dialog must be a SINGLE PAGE DIALOG.
DIALOG 1 'Mastercam sample dialog', WS_VISIBLE, 20, 10, 131, 29, 2, 5
dbm_run_dialog ('test.scr', 1, TXT_HDR, MODAL, 1, dbm_get_mainwnd_id(), NULL, NULL);
Dialog number one is read from the 'test.scr.'
The dialog's controls are initialized (including control callbacks, if necessary).
The dialog's position is calculated (relative to the main application window, in this case).
Dialog is displayed.
A control statement has the following components in the order presented below. Each part is described in further detail beginning with 'Control Type [CONTROL]' on page and ending with 'Control Module Name [module]' on page
CONTROL 'title', number, flags, left, top, width, height, variable, callback, module
If the control does not require 'title,' leave space between double quotes (' ').
If the control does not require 'number,' leave space between commas (, ,).
If the control does not require 'flags,' leave space between commas (, ,).
If the control does not require 'variable,' leave space between commas (, ,).
If the control does not require 'callback,' omit ', callback, module.'
If the control does not require 'module,' omit ', module.'
The Dialog Box Manager supports the standard MS Windows controls. Illustrations of the supported controls are shown below. These controls are described under 'Control Data Variable [variable]' on page
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This parameter is an optional character string enclosed in double quotes. The DBM interprets this string in different ways depending on the control type (several special cases are described below). Generally, it is used to display a text string in the control window. If control does not require 'title,' leave space between double quotes (' ').
The title string specified for a numeric edit control defines the control's range. The DBM supports the following symbols: '<', '<=', '>', '>=', '= =', '!=', '<>'. Range checking can be defined using one expression ('>= 0') or two ('>= 0, <= 10'). Real numbers ('>= 0.0, != 100.25') are also supported but should be limited to those edit controls that contain the DBM_REAL flag. If range check is not required, leave a space between the double quotes. The Dialog Box Manager's API supplies the function, 'dbm_set_control_range,' which sets the control's range checking to the value of a variable at run-time.
Note: Range checking for strings is not supported.
The DBM supports the use of bitmap buttons. To define a bitmap button, you specify the name of the bitmap resource in the title field and add the DBM_BITMAP flag to the 'flags' field. In addition, the DBM expects to find another bitmap resource with an ID one greater than that specified in the title. The first bitmap is used for the normal state of the button, and the second is used for a highlighted state. Both ID's, however, may refer to the same bitmap. These settings instruct the DBM to display the bitmap resource in the button control window. If the bitmap does not fit within the control window, the DBM will automatically stretch the image horizontally and vertically to fit.
To set up a bitmap button
Define the bitmap(s) using a graphics program and save to a binary file ('2001.bmp').
Define the BUTTON control in a script file.
Assign the bitmap in a resource file.
Note: The DBM_BITMAP flag is valid with BUTTON controls only.
The DBM supports the use of icons as static controls. To define a static control using an icon, you must specify the name of the resource identifier in the title field and add the DBM_ICON flag to the 'flags' field. This instructs the DBM to display the icon resource in the static control window. The icon is displayed in the upper-left corner of the control window; the icon is not 'fit' to the window.
To setup a static icon
Define the icon using a Window's toolbox program and save to a binary file ('2003.ico').
Define the STATIC control in a script file.
Assign the bitmap in a resource file.
Note: The DBM_ICON flag is valid with STATIC controls only.
This parameter is an optional 'id' number assigned to each control. It is important to understand the use of this parameter. Control 'id' numbers are the basis of the inter-control message passing logic. They identify each control in the dialog. Each control identification number in the dialog must be unique. Duplicate control numbers may exist within a script file, but not within a dialog.
The following example shows how control 'id' numbers are used:
DIALOG 1 'Mastercam sample dialog', WS_VISIBLE, 40, 20, 58, 16
// Exit controls
BUTTON 'Done', , DBM_OK, 35, 1, 20, 3
STATIC '1', , DBM_STATICHDIP, 0, 5, 58, 1
// Other controls
BUTTON 'Use previous tool diameter', 1, BS_AUTOCHECKBOX, 2, 6, 52, 3, use_prev, fncb_abc, sample4
STATIC 'Tool diameter', 2, DBM_STATICUP | SS_CENTER, 2, 10, 30, 2
EDIT '>= 0.0', 3, DBM_REAL, 34, 10, 20, 2, tool_dia, , sample4
ENDDIALOG
void APPEXPORT fncb_abc (
cbdat ctrl_callback_data)
|
In the example above, the 'fncb_abc' callback function is executed each time the user selects the 'Use previous tool diameter' check box. The DBM passes the callback function a structure (ctrl_callback_data), which contains a handle to the current dialog box (cbdat.pid), the current control's 'id' number (cbdat.cid), a DBM message (cbdat.msg), and a pointer to the control's data variable. |
|
The callback function uses the control 'id' number (cbdat.cid) to identify which control is calling it. In this case, the programmer has instructed the callback function to send a message to controls '2' and '3.' If 'use_prev' is true, the controls are disabled. Otherwise, the controls are enabled, allowing the user to change the tool diameter.
The following flags are supported in BUTTON control statements:
BS_AUTOCHECKBOX Creates a check box (small square with text to right), x toggles when user selects
the box
BS_AUTORADIOBUTTON Creates a radio button (small circle with text to the right), member of a group
BS_CHECKBOX Same as AUTOCHECKBOX (owner-drawn)
BS_DEFPUSHBUTTON Creates a rectangular push button with double width border
BS_RADIOBUTTON Same as AUTORADIOBUTTON (owner-drawn)
BS_GROUPBOX Creates a rectangle in which other controls can be grouped
BS_LEFTTEXT Places text to right side of control (check box and radio button)
BS_PUSHBUTTON Default style (flag has no effect)
DBM_BITMAP Designs a push button control using a BITMAP file
DBM_CANCEL Closes the dialog box (succf=false)
DBM_HIDDEN Makes control initially invisible
DBM_NEWPAGE New page control type
DBM_OK Closes the dialog box (succf=true)
WS_CAPTION Creates a control with a title bar
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_TABSTOP Indicates controls that can receive the keyboard focus with TAB
The following flags are supported in COMBOBOX control statements:
CBS_AUTOHSCROLL Automatically scrolls text horizontally in edit control
CBS_DROPDOWN Drop-down combo box
CBS_DROPDOWNLIST Drop-down list box
CBS_SIMPLE Default style (flag has no effect)
DBM_CNIMMEDIATE Executes callback function every time the user selects an item or presses a
valid key
DBM_HIDDEN Makes control initially invisible
DBM_LISTDIR List directory
WS_CAPTION Creates a control with a double width border (WS_BORDER not supported)
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_TABSTOP Indicates controls that can receive the keyboard focus with TAB
WS_VSCROLL Adds vertical scroll bar if items exceed window
The following flags are supported in LISTBOX control statements:
DBM_HIDDEN Makes control initially invisible
DBM_LISTDIR List directory
LBS_EXTENDSEL Allows multiple items to be selected using special key combinations
LBS_MULTICOLUMN Creates list box with mulitple columns
LBS_MULTIPLESEL Allows multiple items to be selected with the mouse and the SHIFT key
LBS_NOTIFY Executes callback function every time an item is selected
(DBM_CNIMMEDIATE not supported)
LBS_SORT Sorts list items alphabetically
WS_BORDER Creates a control with a thin-line border
WS_CAPTION Creates a control with a title bar
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_HSCROLL Adds horizontal scroll bar if items exceed window (LBS_MULTICOLUMN
only)
WS_TABSTOP Indicates controls that can receive the keyboard focus with TAB
WS_VSCROLL Adds vertical scroll bar if items exceed window
The following flags are supported in EDIT control statements:
DBM_ANGLE Gets an angle (displays degrees; variable is radians)
DBM_BYTE Gets a byte
DBM_CHAR Gets a character
DBM_CNIMMEDIATE Executes callback function every time the user presses a valid key
DBM_HIDDEN Makes control initially invisible
DBM_INT Gets an integer
DBM_LONG Gets a long integer
DBM_REAL Gets a real number
DBM_SHORT Gets a short integer
DBM_CALC Allows the user to enter calculator-type expressions in addition to normal
numerical values (e.g., user may enter '9.0/3' instead of 3.0); used for EDIT
controls in combination with DBM_INT, DBM_SHORT, DBM_LONG and
DBM_REAL
ES_AUTOHSCROLL Automatically scrolls text horizontally
ES_AUTOVSCROLL Automatically scrolls text vertically
ES_CENTER Aligns text to center of control window (ES_MULTILINE only)
ES_LEFT Aligns text to left side of control window (default) (ES_MULTILINE only)
ES_LOWERCASE Displays string in lower case characters
ES_MULTILINE Indicates a multi-line edit control
ES_PASSWORD Displays asterisks instead of characters
ES_READONLY Makes the edit control read-only
ES_RIGHT Aligns text to right side of control window (ES_MULTILINE only)
ES_UPPERCASE Displays string in upper case characters
ES_WANTRETURN Inserts a carriage return when the user presses ENTER in the edit control
WS_BORDER Creates a control with a thin-line border
WS_CAPTION Creates a control with a title bar
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_TABSTOP Indicates controls that can receive the keyboard focus with TAB
The following flags are supported in STATIC control statements:
DBM_ICON Designs a static control using an ICON file
DBM_HIDDEN Makes control initially invisible
DBM_STATICDOWN Indicates a sunken 3D appearance
DBM_STATICHDIP Indicates an engraved horizontal line
DBM_STATICUP Indicates a raised 3D appearance
DBM_STATICVDIP Indicates an engraved vertical line
SS_BLACKFRAME Creates a control with a thin-line border with no text (for border and text, use
WS_BORDER)
SS_CENTER Specifies a rectangle and centers text in the rectangle
SS_GRAYFRAME Default style (flag has no effect)
SS_GRAYRECT Default style (flag has no effect)
SS_LEFT Default style (flag has no effect)
SS_RIGHT Aligns text to right side of control window
WS_BORDER Creates a control with a thin-line border
WS_CAPTION Creates a control with a title bar
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_TABSTOP Controls that can receive the keyboard focus with TAB
The following flags are supported in SCROLLBAR control statements:
DBM_CNIMMEDIATE Executes callback function every time
DBM_HIDDEN Makes control initially invisible
SBS_BOTTOMALIGN Positions a horizontal scroll bar at the bottom of the control area (SBS_HORZ
only)
SBS_HORZ Creates a horizontal scroll bar
SBS_LEFTALIGN Positions a vertical scroll bar at the left side of the control area (SBS_VERT
only)
SBS_RIGHTALIGN Positions a vertical scroll bar at the right side of the control area (SBS_VERT
only)
SBS_TOPALIGN Positions a horizontal scroll bar at the top of the control area (SBS_HORZ only)
SBS_VERT Creates a vertical scroll bar
WS_BORDER Creates a control with a thin-line border
WS_CAPTION Creates a control with a title bar
WS_DISABLED Creates a control that is initially disabled
WS_GROUP Indicates the first control within a group of controls
WS_TABSTOP Controls that can receive the keyboard focus with TAB
These parameters are basically identical to those in the DIALOG statement. However, their value is relative to the top of the dialog box scrolling area. This allows a script writer to place the controls on an individual page without having to worry about the location of controls on other pages.
The location parameters ('left, top') define the position of the upper-left corner of the control relative to the upper-left corner of the dialog window in half character units.
The location parameters ('left, top') define the position of the upper-left corner of the control relative to the lower-left corner of the dialog static area in half character units.
These parameters define the size of the control in half character units.
The 'height' parameter defines the length of the drop-down list. This value may be adjusted by the Windows operating system to avoid displaying partial lines of text. When a combo box is not expanded, the control's height is 2.5 half character units. This value is fixed and can not be modified by the user.
This optional parameter is the name of an exported variable associated with the control. This variable's initial value controls the state or displayed value of the control. As the user interacts with the control, the variable's value is updated accordingly.
|
M |
CAUTION: The Dialog Box Manager has no knowledge of the actual size of the control variable. It understands only what is implied by the control type flags. It will access the data space even if it results in an access violation. This, you will find, will be the most common cause of application crashes when a dialog is executed. In particular, pay close attention to the type of variable assigned to edit controls; variable type and the control flag, such as DBM_REAL, must match. In addition, check the size of buffers allocated for the pointer fields for 'dbm_listbox_data' variables. Make certain there is enough space allocated to accommodate the longest possible string that will be loaded into it. |
Non-applicable (do not assign variables to these controls).
Check boxes Exported boolean variable or no variable (, ,)
Radio buttons Exported boolean variable or no variable (, ,)
Push buttons No variable - do not assign variables to push buttons (, ,)
Group boxes No variable - do not assign variables to group boxes (, ,)
To setup the data variable (i.e., bvar)
Add variable to SCR file: BUTTON 'title', 1, BS_AUTOCHECKBOX, 2, 12, 30, 3, bvar
Define and initialize variable in C file: boolean APPEXPORT bvar = FALSE
Add variable to H file (optional): extern boolean APPEXPORT bvar
Run dialog and verify data.
Exported string (default style: no flag), char (DBM_CHAR), byte (DBM_BYTE), int (DBM_INT), short (DBM_SHORT), long (DBM_LONG) or real (DBM_REAL) variable.
|
A |
IMPORTANT: EDIT controls must contain an exported variable of the appropriate type. |
To setup the data variable (i.e., svar)
Add variable to SCR file: EDIT '>= 0', 1, DBM_SHORT, 2, 12, 30, 3, svar
Define and initialize variable in C file: short APPEXPORT svar = 100
Add variable to H file (optional): extern short APPEXPORT svar
Run dialog and verify data.
Exported 'dbm_listbox_data' variable. These controls (along with SCROLLBAR controls) require a unique data variable format. This format is defined by the 'dbm_listbox_data' data structure:
typedef struct dbm_listbox_data;
|
A |
IMPORTANT: LISTBOX and COMBOBOX controls must contain an 'initialized' list box variable. |
To setup the data variable (i.e., lbvar)
Add variable to SCR file: LISTBOX ' ', 1, WS_BORDER | WS_VSCROLL, 2, 12, 30, 10, lbvar
Define variable in C file: dbm_listbox_data APPEXPORT lbvar
Add variable to H file (optional): extern dbm_listbox_data APPEXPORT lbvar
Allocate and initialize the variable at application startup or just before dialog is executed.
Note: The listbox data structure must be allocated and initialized before 'dbm_run_dialog' is called. A code sample, which demonstrates how to allocate, initialize and deallocate a 'dbm_listbox_data' structure, is listed on the next several pages.
Run dialog and verify data.
Free memory allocated for the variable at application end or just after dialog is closed.
The following function, 'init_listbox_data', allocates memory for a list box data variable. It initializes the list box variable's selection array relative to 'sel_vals[]'. The text associated with each item in the list box is initialized from the text file using 'get_msg.'
boolean init_listbox_data (
dbm_listbox_data *lbd, /* I: list box data structure */
int icount, /* I: count of items in list box */
int num_sels, /* I: number of default selected fields in list box */
int sel_vals[], /* I: array of (num_sels) of selected items */
ulong max_strsize, /* I: maximum character length of element string in
list */
ushort msg_n) /* I: prompt number in products text file */
lbd->icount = icount;
lbd->num_sels = num_sels;
for (i = 0; i < num_sels; i++)
lbd->sel_iarr[i] = sel_vals[i];
for (i = 0; i < icount; i++)
get_msg (tmpstr, msg_n + i);
if (lstrlen (tmpstr) > max_strsize)
else
lstrcpy ((char *)lbd->items[i], tmpstr);
}
return (TRUE);
}
The following function, 'free_listbox_data', frees memory allocated for a list box data variable.
void free_listbox_data (
dbm_listbox_data *lbd)
Exported 'dbm_listbox_data' variable. These controls (along with LISTBOX and COMBOBOX controls) require a unique data variable format. This format is defined by the 'dbm_scrollbar_data' data structure:
typedef struct
dbm_scrollbar_data;
|
A |
IMPORTANT: SCROLLBAR controls must contain an 'initialized' scroll bar variable. |
To setup the data variable (i.e., sbvar)
Add variable to SCR file: SCROLLBAR ' ', 1, SBS_HORZ, 2, 12, 30, 5, sbvar
Define and initialize variable in C file: dbm_scrollbar_data APPEXPORT sbvar =
Add variable to H file (optional): extern dbm_scrollbar_data APPEXPORT sbvar
Run dialog and verify data.
This optional parameter is the name of an exported callback function associated with the control. This function is called by the DBM when any one of the conditions listed below is true:
Note: Callback functions may reside in the application or in a C-Hook (DLL).
The control is initialized (DBM_CTRLINIT message sent).
The control loses focus (DBM_CTRLUNFOCUS message sent).
Note: A control loses focus when the user moves to another control without selecting an item (LISTBOX and COMBOBOX controls) or without pressing [Enter] (EDIT controls).
The control's input is complete (DBM_CTRLINPUT message sent).
Note: You can instruct the DBM to send an input message to the callback function every time an item is selected in a list box or every time a key is pressed in an edit control by adding the DBM_CNIMMEDIATE flag to the control's 'flags' field.
The control is terminated (DBM_CTRLTERM message sent).
To setup the control callback function (i.e.,
fncb_abc)
Add callback to SCR file: BUTTON 'Do something', 1, , 2, 12, 30, 3, , fncb_abc
Define callback in C file: void APPEXPORT fncb_abc (cbdat ctrl_callback_data)
Note: See 'Recommended Format' on page for more information.
Add callback to H file (optional): extern dbm_scrollbar_data APPEXPORT sbvar
Run dialog and verify.
void APPEXPORT fncb_abc (
cbdat ctrl_callback_data)
It is recommended that the callback function call message handling functions. These functions break up the callback processing based on the type of message sent by the Dialog Box Manager. The callback function can process all DBM messages, but this may require a large amount of code.
The 'fncb_abc_init' function (listed below) is called each time the 'fncb_abc' callback receives a DBM_CTRLINIT message from the DBM.
static void fncb_abc_init (
*cbdat ctrl_callback_data)
This parameter is the DLL module name for the pairs (variable, callback) that belong to a DLL. If they are part of the application, this field is not specified. One restriction applies: it is assumed that both the variable and the function belong to the same module, as specified by this field.
These messages are sent to the callback functions as part of the 'ctrl_callback_data' structure:
typedef struct ctrl_callback_data;
Sent to a callback function at dialog initialization before it is displayed.
Sent to a callback function when user presses [Enter] in EDIT control or selects a BUTTON.
Sent to a callback function at dialog termination before it is destroyed.
Sent to a callback function when user leaves EDIT control without pressing [Enter].
These messages are sent to the Dialog Box Manager using the 'dbm_send_control_msg()' function:
short dbm_send_control_msg (
unsigned long dlgid, /* I: owner dialog ID */
short ctrl_num, /* I: control number */
unsigned int msg); /* I: message code */
Sent by a callback function to a control to make it update its display state from its data variable.
Sent by a callback function to a control to make it update its data variable from its display state.
Sets the highlight state of a BUTTON control to TRUE. It has no effect on any other type of controls.
Sets the highlight state of a BUTTON control to FALSE. It has no effect on any other type of controls.
This section provides a detailed technical description of the DBM API along with all related data.
These flags are used as one of the arguments to the dbm_run_dialog() API function:
#define DBM_MODAL Used to create a MODAL dialog box.
#define DBM_MODELESS Used to create a MODELESS dialog box.
The following error codes are returned by the Dialog Box Manager API functions:
#define DBM_NOERR All OK
#define DBM_MEMERR Memory error
#define DBM_BADCONTROL Invalid control statement in the script
#define DBM_BADDIALOG Invalid or missing dialog statement in the script
#define DBM_BADDATABUFF Invalid control data buffer pointer
#define DBM_CANNOTRUN Windows says cannot run dialog
#define DBM_BADENDOFSCRIPT Missing ENDDIALOG statement in the script
#define DBM_FUNCNOTFOUND Control callback function for a control not found
#define DBM_MODULENOTFOUND Control callback function module not found
#define DBM_VARNOTFOUND Control variable not found
#define DBM_FATALERR Internal fatal error
#define DBM_NOMOREDLL Cannot load any more DLLs
#define DBM_INVALIDDLGID Invalid dialog ID
#define DBM_BADSCRFILENAME Invalid script file name
#define DBM_INITFAILURE Initialization failed
#define DBM_SCRFILENOTFOUND Script file not found
#define DBM_DLGSCRNOTFOUND Dialog script not found
#define DBM_TOOMANYMODELESS Too many modeless dialogs
#define DBM_INVALIDINPUT Invalid input
#define DBM_INVALIDCTRLNUM Invalid control number
#define DBM_DUPCTRLNUMS Duplicate control ID numbers in the script
#define DBM_CTRLNUMNOTFOUND Invalid control ID number
#define DBM_BADCTRLMSG Invalid control message
#define DBM_BUFFTOOSMALL Control title buffer too small
#define DBM_NOMOREDIALOGS No more dialogs
It is a good idea to make a genuine effort to export the minimum possible number of globals. There are many cases where all that is needed is a well designed control callback function to take care of a whole dialog box. Since a callback function can be shared by more than one control and the controls can be identified by their optional ID in the script file, it is possible for a single callback function, tied to all the controls, to do all the necessary processing. The Mastercam Mill communications dialog box uses this method to keep the number of exported globals down to four (two variables and two functions) to handle two dialogs, one nested inside the other. The virtue of having other programmers review your design cannot be emphasized enough. There are many ways to do something with the DBM, and some approaches are definitely better than others. As your experience with the DBM increases, you might find yourself going back to your old interface designs and redoing them more efficiently.
The functions listed below process check boxes, radio buttons and edit controls relative to local or global variables. The programmer must export one variable of each type of data he or she wishes to process using these functions. For example:
Add the variable name to each 'byte' control in the script file. This step sets up the link between the data variable and the 'process' function.
EDIT ' ', 1, DBM_BYTE, 2, 12, 30, 3, xbyte, , sample
Next, write and export a callback function. In this example, 'process_editcontrol_byte' is used to process the global variable 'text_color' through control number one (cbdat.cid = 1).
void APPEXPORT fncb_colors (
callback_data cbdat)
Next, add the callback name to the script file.
EDIT ' ', 1, DBM_BYTE, 2, 12, 30, 3, xbyte, fncb_colors, sample
Run the dialog and verify the data.
Note: Check boxes and radio buttons are set up in the same manner but do not require an exported variable.
// Sample dialog script
// SCRVERSION 7.0
DIALOG 1 'SAMPLE DIALOG - Select CANCEL/DONE to exit', WS_VISIBLE, 20, 10, 151, 43
// Sample BUTTON controls
STATIC 'PUSHBUTTON', , , 5, 2, 40, 2.4
BUTTON 'Pop-up window ', 1, WS_GROUP | WS_TABSTOP, 5, 4.5, 40, 3, , fncb_sample, sample
STATIC 'AUTOCHECKBOX', , , 5, 10, 40, 2.4
BUTTON 'Toggle setting', 2, BS_AUTOCHECKBOX | WS_TABSTOP, 5, 12.5, 40, 3, sample_checkbox, , sample
STATIC 'GROUPBOX with AUTORADIOBUTTONS', , , 5, 18, 40, 8
BUTTON 'Groupbox', , BS_GROUPBOX, 5, 22.5, 40, 15
BUTTON 'Button 'a'', 3, BS_AUTORADIOBUTTON | WS_GROUP, 7, 26, 36, 3, sample_radio_a, fncb_sample, sample
BUTTON 'Button 'b'', 4, BS_AUTORADIOBUTTON, 7, 30, 36, 3, sample_radio_b, fncb_sample, sample
BUTTON 'Button 'c'', 5, BS_AUTORADIOBUTTON, 7, 34, 36, 3, sample_radio_c, fncb_sample, sample
// Sample EDIT controls
STATIC 'EDIT String', , , 55, 2, 40, 2.4
EDIT ' ', 6, WS_GROUP | WS_TABSTOP, 55, 4.5, 40, 3, sample_string, , sample
STATIC 'EDIT Real (>= 0.0)', , , 55, 10, 40, 2.4
EDIT '= 0.0', 7, DBM_REAL | WS_TABSTOP, 55, 12.5, 40, 3, sample_real, , sample
// Sample LISTBOX controls
STATIC 'LISTBOX', , , 105, 2, 40, 2.4
LISTBOX ' ', 8, LBS_MULTIPLESEL | WS_BORDER | WS_VSCROLL, 105, 4.5, 40, 11, sample_lbdata, , sample
// Sample COMBOBOX controls
STATIC 'COMBOBOX with EDIT control', , , 55, 18, 30, 4
COMBOBOX 'string', 9, CBS_DROPDOWN | WS_VSCROLL | WS_TABSTOP, 55, 22.5, 40, 11, sample_cbdata2, , sample
STATIC 'COMBOBOX with DROWNDOWNLIST', , , 105, 18, 30, 4
COMBOBOX ' ', 10, CBS_DROPDOWNLIST | WS_VSCROLL | WS_TABSTOP, 105, 22.5, 40, 11, sample_cbdata1, , sample
// Sample SCROLLBAR controls
STATIC 'SCROLLBAR', , , 55, 28, 40, 2.4
SCROLLBAR ' ', 11, SBS_HORZ | WS_TABSTOP, 55, 30.5, 40, 3, sample_sbdata, fncb_sample, sample
STATIC '*****', 12, SS_CENTER | DBM_STATICDOWN, 65, 34.5, 20, 3
// Exit controls
STATIC 'EXIT BUTTONS', , , 105, 28, 40, 2.4
BUTTON 'Cancel', , DBM_CANCEL | BS_DEFPUSHBUTTON | WS_TABSTOP, 105, 30.5, 40, 3
BUTTON 'Done', , DBM_OK | WS_TABSTOP, 105, 34.5, 40, 3
ENDDIALOG
// Pop-up window dialog script
DIALOG 2 'POPUP WINDOW', WS_VISIBLE, 5, 8, 80, 14
STATIC 'Select 'Done' to continue', , SS_CENTER | DBM_STATICDOWN, 5, 2, 68, 2
BUTTON 'Done', , DBM_OK, 30, 6, 20, 3
ENDDIALOG
/* Sample dialog C-Hook
*
* Copyright (c) 1994-98 CNC Software, Inc.
*
*/
#include <stdlib.h>
#include <stdio.h>
#include 'm_vars.h'
#include 'm_dbm.h'
#include 'm_init.h'
#define SB_STATIC 12
#define BASE_LBDATA 10 // starting message number for listbox strings
boolean APPEXPORT sample_checkbox = TRUE;
boolean APPEXPORT sample_radio_a = TRUE;
boolean APPEXPORT sample_radio_b = FALSE;
boolean APPEXPORT sample_radio_c = FALSE;
char APPEXPORT sample_string[80] = 'string';
real APPEXPORT sample_real = 0.1;
dbm_listbox_data APPEXPORT sample_lbdata;
dbm_scrollbar_data APPEXPORT sample_sbdata = ;
dbm_listbox_data APPEXPORT sample_cbdata1;
dbm_listbox_data APPEXPORT sample_cbdata2;
char modname[FILENAME_MAX]='sample.dll';
char scrname[FILENAME_MAX]='sample.scr';
char TXT_HDR[] = 'sample';
/* __________ update_sbdata_static __________
*
* Purpose: Update display of text in static control for scroll bar.
* (DBM_CTRLINIT)
*/
static void update_sbdata_static (
ctrl_callback_data *cbdat)
/* __________ fncb_sample_init __________ SAMPLE FUNCTION (not used)
*
* Purpose: Process control initialization messages.
* (DBM_CTRLINIT)
*/
static void fncb_sample_init (
ctrl_callback_data *cbdat)
}
/* __________ fncb_sample_input __________
*
* Purpose: Process control input messages.
* (DBM_CTRLINPUT)
*/
static void fncb_sample_input (
ctrl_callback_data *cbdat)
}
/* __________ fncb_sample_unfocus __________ SAMPLE FUNCTION (not used)
*
* Purpose: Process control unfocus messages.
* (DBM_CTRLUNFOCUS)
*/
static void fncb_sample_unfocus (
ctrl_callback_data *cbdat)
}
/* __________ fncb_sample_term __________ SAMPLE FUNCTION (not used)
*
* Purpose: Process control termination messages.
* (DBM_CTRLTERM)
*/
static void fncb_sample_term (
ctrl_callback_data *cbdat)
}
/* __________ fncb_sample __________
*
* Purpose: Process all callback messages.
*/
void APPEXPORT fncb_sample (
ctrl_callback_data cbdat) /* I: callback data */
}
/* __________ initialize_listboxes __________
*
* Purpose: allocate and initailize list boxes.
*/
static void initialize_listboxes (
boolean *succf)
;
*succf = init_listbox_data (&sample_lbdata, 7, 2, sel_iarr, 20,
TXT_HDR, BASE_LBDATA);
if (!*succf)
return;
*succf = init_listbox_data (&sample_cbdata1, 7, 1, sel_iarr, 20,
TXT_HDR, BASE_LBDATA);
if (!*succf)
*succf = init_listbox_data (&sample_cbdata2, 7, 1, sel_iarr, 20,
TXT_HDR, BASE_LBDATA);
if (!*succf)
}
/* __________ run_sample_dialog __________
*
* Purpose: display sample dialog.
*/
void run_sample_dialog (void)
/* __________ main_program __________ */
void CH_ENTRY m_main (long *ptrs)
sample.obj
m_init.obj
m_ptrs.obj
/DLL
/OUT:sample.dll
[sample]
1. 'SAMPLE.DLL'
10. 'Item #0'
11. 'Item #1'
12. 'Item #2'
13. 'Item #3'
14. 'Item #4'
15. 'Item #5'
16. 'Item #6'
17. 'Item #7'
18. 'Item #8'
19. 'Item #9'
|
