What can you tell me about using the .idlg files that are written by StataCorp and used in their dialogs?

.idlg files, which are included in some .dlg files (also known as dialogs), are mainly used when several dialog boxes need to use a common set of controls, often a whole tab. We put this common block of code in a .idlg file and use the INCLUDE statement to include it in several .dlg files so that we only need to make changes to it once rather than in each of those .dlg files. For example, tabs such as by/if/in and Weights are implemented in .idlg files because the dialog boxes for most Stata commands use them.

You may be tempted to use the .idlg files shipped with Stata to save time by using code already written rather than making your own version. We do not want to discourage this, but be aware that these files could change substantially in the future.

We will do our best not to make changes that might break commonly used .idlg files. After all, there are over 800 StataCorp-implemented dialog boxes, and we do not wish to have to rewrite each one. That said, do not expect that once you include an .idlg file for a particular purpose (such as the by/if/in tab) that the .idlg file or tab will not be changed by StataCorp in the future.

The safest option is to use one of these .idlg files is to copy it (along with all the accessories needed to use it) under a slightly different name.

That disclaimer aside, in many cases the essential function of these .idlgs will probably not change, so you can include them. Each of them has special requirements, however, which will be mentioned below.

The three most commonly used .idlg files are those for the by/if/in tab, the Weights tab, and the standard header, which sets the size of the dialog box and defines the OK, CANCEL, and SUBMIT buttons.

by/if/in

There is not a single .idlg file for by/if/in because some commands do not accept an in range, other commands do not accept by, and still others accept only an if. Thus there are four .idlgs from which you can choose

        byifin.idlg
        byif.idlg
        ifin.idlg
        if.idlg

Each of these files defines the layout of the controls for the by/if/in tab and a set of PROGRAMs and SCRIPTs that control the behavior of the tab. For example, in the byifin.idlg, if the by qualifier is chosen, the in qualifier is not allowed. When you click the checkbox for by, it runs a program sub_byon, which, among other things, checks to see if you have also checked the in qualifier; if you have, it sends out a warning message. There are also PROGRAMs that enable and disable the entire tab, but use these with caution—see the warning below.

Some defined positioning elements must always be included for these tabs to work. You must include one of the following .idlgs before including any of the above .idlgs:

        _std_small.idlg  (if your dialog box is small like db count)
        _std_medium.idlg (if your dialog box is medium like db collapse)
        _std_large.idlg  (if your dialog box is large like db regress)

Note: We created the _std_*.idlg files to define the standard widths and heights of dialog boxes and their controls. You will need to include one of these in order to use our include tabs; however, unless you want to risk having your controls in your box moved around if we change the dialog box, we recommend that you define your own positions, widths, and heights for your own controls and possibly for the dialogs themselves. You could also make your own copies of these files and the files they include for your own use.

In general, you should not redefine the variables in these _std_*.idlg files, as you might suddenly find controls misaligned or looking strange on Stata's include tabs.

You must also include appropriate "programming" .idlgs to support the by/if/in (or variation) tab. These .idlgs contain the code that helps the dialog system build the by, if, and in portions of the Stata command to be submitted when the user clicks OK or Submit. Include one or more of the following files as appropriate:

        _by_pr.idlg    programming for by
        _ifin_pr.idlg  programming for if and in
        _if_pr.idlg    programming for if

These all go in the PROGRAM command block. In general, INCLUDE _by_pr is the first thing in the block. INCLUDE ifin_pr or INCLUDE _if_pr goes after the command name and the varlist and weights, if these are allowed. You can find an example in the faq.dlg dialog box.

Weights

There are several variations on the Weights tab, one for each combination of weights that are commonly allowed by various commands. If you look within the STATA directory reported by sysdir for

        base/w/weights*.idlg

you will see files with names such as weights_fpai.idlg and weights_ai.idlg. The letters after weights_ denote which weight types will be shown on the Weights tab if that particular .idlg is included. For example, weights_fpai.idlg will show all four weight types on the tab: fweights, pweights, aweights, and iweights. weights_ai.idlg will show only aweights and iweights.

As with the by/if/in .idlgs, one of _std_small, _std_medium, or _std_large must be included before a weights*.idlg file can be included.

The programming for all the different weights tabs is in _weights_pr.idlg.

The statement INCLUDE _weights_pr goes within the PROGRAM command block, usually right after the command name and after the varlist, if there is one.

As in the by/if/in section, you can see an example in the faq.dlg dialog box.

Standard header

Not all .idlgs constitute their own tabs. The OK, CANCEL, and SUBMIT buttons and the overall dialog size are defined in header.idlg. You can define these buttons on your own, but the way they are defined is so standard across almost every dialog box that it is probably easiest to just use this .idlg.

header.idlg requires that _dlgwd (the dialog width) and _dlght (the dialog height) be defined. If you have included _std_small, _std_medium, or _std_large, the dialogs will be set to StataCorp's idea of what the size of a small, medium, or large dialog should be. You can define _dlgwd and _dlght to be whatever you like for your own dialogs. INCLUDE header usually goes at the top of a .dlg file immediately after the VERSION 9.0 line and after one such as INCLUDE _std_large.

For an example, see faq.dlg.

Specialized .idlgs

Several other .idlg files may be of use if you are writing particular types of commands. These are documented in individual FAQs. Choose from the list below:

• Buttons for predefinitions
• Graphics tabs