1 item has been added to your cart.

How do I add options to Stata dialogs?

This FAQ is intended to be a supplement for the documentation rather than a substitute. We strongly recommend reading the online help on dialog programming, which contains information that will not be covered here.

The discussion in the previous sections of this FAQ revolved around a reconstruction of Stata's generate dialog box. Our recreation was called mygenerate. That dialog and the generate command were suitable for illustrating many of the basic dialog programming concepts. However, the generate command did not use any options, so it will not be used as an example in this section.

To show how Stata options are programmed in the dialog language, we will use the describe command because, like generate, it is a command with which nearly every Stata user is already familiar.

        describe [varlist] [, short detail fullnames numbers ]

The syntax diagram above shows that describe accepts a varlist as an argument and has four additional Stata options. Notice that Stata options are always preceded by a comma. This is an important point because the Stata dialog language has a special way of handling the comma and the subsequent options.

Click here to download this version of mydescribe.dlg

Once you have downloaded it, save mydescribe.dlg in your Stata adopath, most preferably your PERSONAL directory. If you are unfamiliar with the PERSONAL directory, please see the following FAQ: Where is my personal ado directory.

Once you have saved it correctly, mydescribe can be called from the Stata command line by typing db mydescribe.

------------------------- mydescribe.dlg -------------------------
VERSION 16.0

POSITION . . 410 225

DIALOG main, label("describe - Describe contents of data") tabtitle("Main")
BEGIN
  TEXT     tx_var       10    10    390     .,                 ///
           label("Variables: (leave empty for all variables)")
  VARLIST  vl_var       @     +25   @       .,                 ///
           label("Variables")

  GROUPBOX gb_opts      @     +35   @       135,               ///
           label("Options")
  CHECKBOX ck_short     +10   +25   -20     .,                 ///
           option(short)                                       ///
           label("Display only general information")
  CHECKBOX ck_detail    @     +25   @       .,                 ///
           option(detail)                                      ///
           label("Display additional details")
  CHECKBOX ck_fullnames @     +25   @       .,                 ///
           option(fullnames)                                   ///
           label("Do not abbreviate variable names")           ///
           onclickon(main.ck_numbers.disable)                  ///
           onclickoff(main.ck_numbers.enable)

  CHECKBOX ck_numbers   @     +25   @       .,                 ///
           option(numbers)                                     ///
           label("Present variable number along with name")    ///
           onclickon(main.ck_fullnames.disable)                ///
           onclickoff(main.ck_fullnames.enable)
END

OK ok1,      label("OK")
CANCEL can1, label("Cancel")
SUBMIT sub1, label("Submit")
HELP hlp1,   view("help describe")
RESET res1
COPY copy1

PROGRAM command
BEGIN
        put "describe "
        varlist [main.vl_var]
        beginoptions
                option main.ck_short
                option main.ck_detail
                option main.ck_fullnames
                option main.ck_numbers
        endoptions
END
------------------------- mydescribe.dlg -------------------------

The following screen image was produced by the code above:

Notice each of the four CHECKBOX controls represents one of the options available to describe. Also notice each of these checkboxes has a directive called option. The term directive is not 100% accurate, as these are really checkbox options named option. Because an option named option is confusing, we will refer to it as a checkbox directive named option. The option directive is used to specify the Stata command option that will be added to the return string.

The fullnames and numbers options associated with the describe command are mutually exclusive: only one can be specified at a time. The dialog box should enforce the mutual exclusion rather than issuing an invalid Stata command. To enforce the mutual exclusion, i-actions have been associated with these two CHECKBOX controls. The i-actions work to disable the other CHECKBOX control when one of the mutually exclusive pair is selected (checked). An alternative way of specifying mutually exclusive options is to use a set of RADIO controls. Generally, if more than two items are mutually exclusive, RADIO controls are a better choice.

      beginoptions
        	option main.ck_short
        	option main.ck_detail
        	option main.ck_fullnames
                option main.ck_numbers
      endoptions

The excerpt above is from the PROGRAM command section of mydescribe.dlg. The block enclosed by beginoptions and endoptions handles adding the options defined in the DIALOG section to the return string. It also adds the comma that Stata command syntax expects to separate the arguments from the option list. The beginoptions and endoptions block does something else, too. It determines if the control associated with each option is enabled and selected. If both of the criteria are true, the option is added to the return string. If either is not true, the option is ignored.

One aspect of options is not well illustrated by this example. Suppose that one of the options takes an argument. Consider the following graphics command:

       . scatter weight mpg, title(My Title)

Instead of a CHECKBOX control, an EDIT control would be used. The option directive would contain "title".

        Example:

        EDIT     ed_title    10   10   -20    .,                ///
                label("Title") option(title)

We not only want to add “title” to the return string, we also need to add the contents of the EDIT control. This can be accomplished by using optionarg instead of option. optionarg simply means to add the option and its argument.

        Example:

                beginoptions
                        optionarg main.ed_title
                endoptions

By using option and optionarg, most Stata command syntax that contains options can be easily handled.