What do I need to know about writing dialogs to share with others?

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.

Introduction and terminology

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 commands.

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 .dlg.

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 name.

1     2    3    4    Next