What do I need to know about writing and sharing dialog-box programs?

Writing dialog-box programs

Dialog-box basics

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 12             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 -------------------------

Documentation for shared dialog boxes

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:

Recommendation 1

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 9.0 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, 
*! >  steicht@rjrt.com
*!    for galbr version 2.0,      Mar 2000, Aurelio Tobias, 
*! >  atobias@isciii.es

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 12  

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 -------------------------

Recommendation 2

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).

Style guidelines for dialog-box programs

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" of the online help for dialogs 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.

Formatting guidelines

• Use comments to describe what a code section will do.
• Use line-continuation dividers /// or comment pairs /* .... */ to place limited amounts of information on a single line. Generally speaking, it seems best to place each option of a control on its own line.
• Use indentation to assist the reader in following the structure of the code. Place only keywords of the 7 main parts of a dialog-box program (see section 1.1 above for these parts) on the left margin; indent a few spaces for BEGIN ... END sections; indent controls within those sections a few more spaces; and indent options for controls yet a few more spaces .
• Divide related groups of controls from each other by blank lines and/or comments. For example, an EDIT control is often preceded by a TEXT static control that describes the EDIT control box. Keep these together and separate from other controls.
• Use CAPITAL (uppercase) letters for the part keywords, BEGIN ... END commands, and control keywords; use lowercase for names of controls, options, member functions, iactions, gactions, and command-construction commands; use mixed case, as needed, for text strings within quotes. Note the proper use of case is not an option, since keywords, etc., will not be correctly identified by the dialog processor when the wrong case is used.
• Align names of options within a group of controls and also the corresponding x, y, xsize, and ysize numbers. While this may seem tedious, it greatly assists you in finding things as your dialog code becomes complex or when you return to it some days later.

Name guidelines

• Include as part of each control name an informative prefix indicating what type of control the name is for. One scheme for informative prefixes is:

Prefix	For control	Prefix	For control
fi_ bu_ ck_ cb_ ed_ lb_ rb_	FILE BUTTON CHECKBOX COMBOBOX EDIT LISTBOX RADIO	sp_ vl_ vn_ fr_ gb_ tx_	SPINNER VARLIST VARNAME FRAME GROUPBOX TEXT

• Include as part of each related control a common suffix describing what the controls pertain to.

As an example of the above two guidelines, say you wish to allow the optional entry of an "id" variable. If so, you will likely have a CHECKBOX control and a VARNAME control. Name the first ck_id and the second vn_id. This makes it clear that the two controls are related to each other, that each is for a certain type of control, and that they pertain to the "id" variable. Such a structure makes it much easier when you later construct the command string to be generated by the dialog .

• Use sufficient letters in the common suffixes (as in guideline 2 above) to fully identify what the controls do. Saving the time needed to type a few characters by excessive abbreviation will cost you much more time later when you construct your command string, attempt to debug your code, or return to your code a few days later.
• Use concise but informative names for each dialog section within your program and assign the tabtitle() the same name. For example

DIALOG main, tabtitle("Main")
BEGIN ...
END

DIALOG options, tabtitle("Options")
BEGIN ...
END

• Use informative names for PROGRAMs and SCRIPTs. Do not skimp on how many characters you use! For example

PROGRAM binary_on
BEGIN ...
END

SCRIPT binary_off
BEGIN ...
END

If there are multiple DIALOG sections in your dialog, then the informative name should also include the DIALOG section name. For example, if PROGRAM binary_on is used in DIALOG options, it would be more informative to name it options_bin ary_on.

The next section, Sharing dialogs (part 3)—Stata menus, contains information about inserting dialogs into Stata's menu system.

Prev    1    2     3    4    Next