Search
   >> 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)
  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", 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
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
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")
BEGIN ...
END

DIALOG options, tabtitle("Options")
BEGIN ...
END
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   

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