What can you tell me about using the .idlg files that are written by
StataCorp and used in their dialogs?
||Using StataCorp-written .idlg files
Jean Marie Linhart, StataCorp
James Hassell, StataCorp
May 2003; minor revisions October 2005
.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
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
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
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
_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.
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
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
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
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.
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.
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