|Title||Dialog programming (part 4)—Using options|
James Hassell, StataCorp
Jean Marie Linhart, StataCorp
|Date||August 2003; minor revisions July 2011|
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 12 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.