|Title||Sharing dialogs (part 2)—Dialog-box programs|
|Author||T. J. Steichen|
A dialog-box program, contained in a .dlg file, is fully described in [P] dialogs. Refer to this manual entry for details about how to implement the parts of a dialog-box program. You also might want to visit other FAQs on basic dialog programming. See Dialog programing (part 1)—Getting started.
Dialog-box programs consist of seven parts, although some of them are optional:
------------------------- dialog_box_name.dlg ------------------------- VERSION 15 Part 1: version number POSITION ... Part 2: set size of dialog box DEFINE ... Part 3, optional: common definitions LIST ... DIALOG ... Part 4: dialog definitions (repeat as necessary) BEGIN FILE ... ... which contain input controls BUTTON ... CHECKBOX ... COMBOBOX ... EDIT ... LISTBOX ... RADIO ... SPINNER ... VARLIST ... VARNAME ... FRAME ... ... and static controls GROUPBOX ... TEXT ... END SCRIPT ... Part 5, optional: i-action definitions BEGIN ... usually done as scripts ... (repeat as necessary) END PROGRAM ... ... but sometimes as programs BEGIN (repeat as necessary) ... END OK ... Part 6: u-action & helper button definitions CANCEL ... SUBMIT ... HELP ... RESET ... COPY ... PROGRAM command Part 7: u-action definition BEGIN ... END ------------------------- dialog_box_name.dlg -------------------------
A dialog box and its underlying dialog-box program should provide clear identifying information about the dialog, its author, and the .ado program it is associated with. As in .ado programs, it is possible that there will be multiple versions of a particular dialog box and its .dlg program file. This could arise when new features are made available in the Stata dialog language that stimulate changes to the dialog code, when the command structure of the associated .ado has been changed, when bugs in the operation of the dialog are discovered and corrected, or even when the author of the dialog wishes to make aesthetic changes in the appearance of the dialog box. To provide this information, we propose the following recommendations:
The .dlg file should include in the comments information identifying the author of the dialog and the version number of the dialog. The header should also identify the name and version number of the .ado it is for and, optionally, list the syntax implemented by the dialog.
Below is an example .dlg file. All the lines before the VERSION 15 line are comments used to document the dialog box program file; recommendation 1 is embodied in the first few lines of comments.
The first comment indicates that this is version 1.0.0 of a dialog written by T. J. Steichen; an optional email address is provided.
The second comment indicates that program galbr (version 2.0 from March, 2000, written by Aurelio Tobias) is the .ado whose syntax is implemented by this dialog.
Note the whole comment section is enclosed within comment start/end indicators; /* .... */. Nonetheless, lines starting with *! will be picked up and reported by Stata's which command. Therefore, these identifying comments should start with the special *! indicator.
The remaining comments provide optional information, including the identifying label text from the galbr help file, a statement of the syntax implemented, and some instructions for installing a menu item for this dialog (more on that below).
------------------------- galbr_tjs.dlg ------------------------- /* *! galbr dialog version 1.0.0, 13 May 2003, T. J. Steichen, *! > email@example.com *! for galbr version 2.0, Mar 2000, Aurelio Tobias, *! > firstname.lastname@example.org Galbraith Plot for Heterogeneity -------------------------------- galbr theta setheta [if exp] [in range] [ , id(strvar) graph_options ] To install in User Statistics menu via Stata commands: . window menu append item "stUserStatistics" ... "Galbraith Plot for Heterogeneity (&galbr)" "db galbr" . window menu refresh To permanently install, place the commands in your -profile.do- file. */ VERSION 15 INCLUDE _std_small INCLUDE header HELP hlp1, view("help galbr") RESET res1, label("Reset") DIALOG main, label("galbr 2.0 - Galbraith Plot for Heterogeneity") /* */ tabtitle("Main") BEGIN TEXT tx_se 10 10 330 ., /// label("Vars for theta, se(theta), in that order") VARLIST vl_se @ _ss @ ., /// label("Vars for theta, se(theta)") CHECKBOX ck_id 10 70 100 ., /// label("ID Variable:") /// onclickon(main.vn_id.enable) /// onclickoff(main.vn_id.disable) VARNAME vn_id 110 70 230 ., /// label("ID Variable") /// option("id") GROUPBOX gb_gopts7 10 155 330 _ht1h, /// label("Allowed Graph7 Options:") EDIT ed_gopts7 15 175 320 ., /// label("Graph7 Options") END INCLUDE ifin PROGRAM command BEGIN put "galbr " varlist main.vl_se INCLUDE _ifin_pr beginoptions optionarg main.vn_id put main.ed_gopts7 endoptions END ------------------------- galbr_tjs.dlg -------------------------
The label() of the main dialog box should display the name and version number of the ado file associated with the dialog box along with text indicating the purpose of the program.
Because comments in the dialog-box program file are not visible to the user when the dialog box is invoked, additional identifying information should be provided in the label of the main dialog box (the contents of this label are displayed across the top of the dialog-box window when the dialog is visible). This information should clearly identify the name and version number of the .ado file associated with the dialog box. In the example dialog above, the following line provides that information:
DIALOG main, label("galbr 2.0 - Galbraith Plot for Heterogeneity") tabtitle("Main")
This line clearly indicates that version 2.0 of program galbr will be run by this dialog box, and it gives a short description of what this program does (it provides the Galbraith heterogeneity plot).
Guidelines on style are just that: guidelines. Nonetheless, they are intended to help make it easier for you to debug your dialog-box programs and to make it easier for third party users to read and understand your code. StataCorp supplies a set of such guidelines in "Appendix C, Interface guidelines for dialog boxes", accessible by typing help dialogs in Stata, that relate mostly to the operation and visible appearance of dialog boxes. The guidelines below relate more to formatting of dialog-box program code and naming of controls within that code.
Prefix For control Prefix For control fi_
DIALOG main, tabtitle("Main") BEGIN ... END DIALOG options, tabtitle("Options") BEGIN ... END
PROGRAM binary_on BEGIN ... END SCRIPT binary_off BEGIN ... END
The next section, Sharing dialogs (part 3)—Stata menus, contains information about inserting dialogs into Stata's menu system.