What do I need
to know about writing dialogs to share with others?
Sharing dialogs (part 1) — Basic terminology and overview
T. J. Steichen, RJRT
This is a four-part FAQ. This first part provides an introduction, some
basic dialog terminology, and a general overview. The second part discusses
guidelines for writing
dialog-box programs. The third section includes a discussion on
guidelines for adding to the
Stata menu system. The fourth and final part outlines
guidelines for sharing
submenus and dialog boxes.
Stata Version 8 introduced a graphical user interface (GUI) that gives the
user a visual, point-and-click, menu-based way to select Stata commands to
be run and provides dialog boxes to specify the details about those
commands. Consistent with the open design of Stata, users can write their
own dialogs and can attach them to a portion of the built-in Stata menu
system. Menu items and dialog boxes prepared in this way are virtually
identical to the menus and dialog boxes supplied with Stata for built-in
What is a dialog box?
A dialog box is a window accessed via the menu system or the db
command that provides an easy, visual, point-and-click way to specify the
details about the Stata command you wish to run. Dialog boxes are another
essential element of the new GUI.
What is a dialog-box program?
A dialog-box program (formally called a dialog resource file and
often casually referred to as a dialog) allows the author to define
the appearance of a dialog box, to specify how the controls of the dialog box
react when the user fills in the fields (such as the hiding or disabling of
specific areas), and to specify the ultimate action that is to be taken
(such as running a Stata command) when the user clicks OK or
Submit. A dialog-box program is stored in a file with extension
What is a menu?
A menu, or more specifically a pull-down menu, is the element of Stata 8's
new graphical user interface (GUI) that allows the user to access a dialog
box to specify and submit details about a Stata command you wish to run. The
only Stata menu that can be modified to hold user-written dialog boxes is
the User menu.
Key steps in writing and sharing dialogs
The first step is to write your dialog box program. For more information on
this topic, visit Sharing
dialogs (part 2) — Dialog-box programs.
The second step is to determine where your program belongs in the Stata menu
system and to specify how it can be added by users. For more information,
visit Sharing dialogs (part 3)
— Stata menus.
The third step is to share your code by inclusion in the Stata Journal or
the SSC or by posting your package on some other website. We have
suggested some ground rules for cooperating with others. For more
information, visit Sharing
dialogs (part 4) — Submenus and dialogs.
Summary of key recommendations
Each of the next sections of this FAQ discusses a key recommendation. A
summary of each recommendation is listed below.
- Recommendation 1
- Dialog files should include, in 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 program it is for and,
optionally, list the syntax imp lemented by the dialog.
- 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.
- Recommendation 3
- The text that appears on a menu item should include both explanatory
information indicating what type of result will be provided if the menu item
is clicked, and the ado file name to fully indicate to the user which program
will be run.
- Recommendation 4
- SSC submissions of dialog box programs or collections of dialogs that are
not a part of a new package or an update of an existing package should be
submitted as a separate package containing the informative word "dialog" as
part of their package name . An included help or text file of menu
construction-related commands should be named consistently with the package