1 item has been added to your cart.
| Title | Sharing dialogs (part 3)—Stata menus | |
| Author | T. J. Steichen |
The two elements of menus in Stata's graphical user interface (GUI) are submenus and menu items. A menu item is a clickable line in a menu that invokes an underlying dialog box or submenu. A submenu is identified by a solid triangular arrow that appears on the far right of the menu item. Submenus are composed of one or more menu items. Users are allowed to add both menu items and submenus to the User menu of Stata. When the menu item invokes a dialog box, the displayed text should clearly identify the name of the .ado that will be run if you select that menu item and should identify the purpose of that program.
Elements of menus are defined by the window menu commands of Stata. The four commands needed to do this are
window menu clear
window menu append submenu ...
window menu append item ...
window menu refresh
window menu clear removes all user-installed menu items and submenus. It is used when you wish to completely or partially restructure your user-defined menus.
window menu append submenu ... appends a submenu to the menu system. Submenus can only be appended to elements of the User menu of Stata. Details on the part of the command implied by the ellipses "..." will be given below in the Submenus section.
window menu append item ... appends a menu item to the menu system. Menu items can only be appended to elements of the User menu of Stata, including user-defined submenus. Details on the part of the command implied by the ellipses "..." will be given below in the Menu items section.
window menu refresh refreshes the menu system and makes visible any menu item or submenus that you have added by the two commands above since the last refresh.
Although these commands can be entered interactively in Stata, they remain in force only while the current Stata session remains active. If you exit Stata and restart it, all submenus and menu items created in the prior session will not reappear. For this reason, the window menu commands are usually placed in the profile.do file, a file of Stata commands that is automatically run at Stata startup if it appears in a directory in the path that Stata searches. Typical directory placement for profile.do is your personal ado directory.
You can determine if you have defined a profile.do file by starting Stata and observing whether a line of the form
running C:\ado\personal\profile.do ...
appears on the screen as part of the initiation sequence. If it does, then add your window menu commands to that file and resave the file. If the line does not appear, then you have not defined a profile. Create a plain text file containing your window menu commands, name it profile.do and save it somewhere in the Stata path.
User-defined submenus can be appended to the User menu of Stata, to any of its predefined submenus (Data, Graphics, Statistics), or to any user-defined submenu previously appended to the menu system.
window menu append submenu ... requires two string parameters to perform the append:
The first string parameter identifies the menu or submenu to which the new submenu is to be attached.
Note that the predefined User menu is known as stUser, while the predefined submenus are known as stUserData, stUserGraphics, and stUserStatistics, respectively.
The second string parameter identifies the name of the new submenu.
Thus a complete command to append an Community-contributed meta-analysis submenu to the predefined User menu would be
window menu append submenu "stUser" "Community-contributed &meta-analysis"
| Note: The ampersand & that appears in a window menu append submenu ... command (or a window menu append item ... command; see below) is a Windows-only feature. It does not appear in the text shown on the menu. Instead, it defines the character immediately after itself as the keyboard shortcut character and causes that character to be underlined when shortcuts are enabled by pressing the Alt key prior to selecting a menu item. If shortcuts are enabled, then pressing "m" on the keyboard would select the menu item in the above example in the same way that clicking it with the mouse would. See section "Keyboard Shortcuts (Windows Only)" in [P] window menu for details. |
User-defined menu items can also be appended to the User menu of Stata, to any of its predefined submenus (Data, Graphics, Statistics), or to any user-defined submenu previously appended to the menu system.
window menu append item ... requires three string parameters to perform the append:
The first string parameter identifies the menu or submenu to which the new menu item is to be attached.
The second string parameter identifies the name of the new menu item.
The third string parameter provides the command to be invoked when the menu item is clicked. This command is of the form db dbfilename, where dbfilename is the name of the dialog-box program to be run.
Thus a complete command to append a galbr menu item to a user-defined Community-contributed meta-analysis submenu would be
window menu append item "Community-contributed meta-analysis" /*
*/ "Galbraith Plot for Heterogeneity (&galbr)" "db galbr"
The text of the second string parameter in this example, "Galbraith Plot for Heterogeneity (galbr)", is what appears on the menu. This text should include both explanatory information indicating what type of result will be provided if the menu it em is clicked, and the ado file name to fully indicate to the user which program will be run.
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.
The next section deals with guidelines for sharing dialog boxes and menus. See Sharing dialogs (part 4)—Submenus and dialogs.
