>> Home >> Resources & support >> FAQs >> Sharing dialogs (part 2)—Dialog-box programs

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

Title   Sharing dialogs (part 2)—Dialog-box programs
Author T. J. Steichen, RJRT
Date August 2003; minor revisions July 2011

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)
    FILE ...                  ... which contain input controls
    BUTTON ...
    CHECKBOX ...
    COMBOBOX ...
    EDIT ...
    LISTBOX ...
    RADIO ...
    SPINNER ...
    VARLIST ...
    VARNAME ...
    FRAME ...                 ... and static controls
    GROUPBOX ...
    TEXT ...

SCRIPT ...             Part 5, optional: i-action definitions
  BEGIN                       ... usually done as scripts
       ...                        (repeat as necessary)

PROGRAM ...                   ... but sometimes as programs
  BEGIN                           (repeat as necessary)

OK ...                 Part 6: u-action & helper button definitions
CANCEL ...    
SUBMIT ...    
HELP ...    
RESET ...    
COPY ...

PROGRAM command        Part 7: u-action definition
------------------------- 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, 
*! >
*!    for galbr version 2.0,      Mar 2000, Aurelio Tobias, 
*! >

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


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")
  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)                       ///
  VARNAME  vn_id       110   70   230     .,            ///
     label("ID Variable")                               ///

  GROUPBOX gb_gopts7   10 155  330   _ht1h,             ///
     label("Allowed Graph7 Options:")
  EDIT     ed_gopts7   15 175  320       .,             ///
     label("Graph7 Options")


PROGRAM command
 put "galbr "
  varlist main.vl_se
  INCLUDE _ifin_pr
    optionarg main.vn_id
    put main.ed_gopts7
------------------------- 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", 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.

Formatting guidelines

Name guidelines

Prefix For control Prefix For control
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 .
DIALOG main, tabtitle("Main")

DIALOG options, tabtitle("Options")
PROGRAM binary_on

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

The Stata Blog: Not Elsewhere Classified Find us on Facebook Follow us on Twitter LinkedIn Google+ Watch us on YouTube