Add entries (choices) to a previously created Menu widget.
Arguments:
WidgetName - a standard path-like name used to name the widget being changed. It must have been previously created with TkMenu.
Type - one of a number of selectable types of menu entries to be added. Must be one of cascade, checkbutton, command, radiobutton, or separator, or a unique abbreviation of one. (See "Types" below)
Options - one or many descriptors for the options that are available for this widget.
Options:
activebackground - Specifies a background color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the activeBackground option for the overall menu is used. This option is not available for separator or tear-off entries.
activeforeground - Specifies a foreground color to use for displaying this entry when it is active. If this option is specified as an empty string (the default), then the activeForeground option for the overall menu is used. This option is not available for separator or tear-off entries.
accelerator - Specifies a string to display at the right side of the menu entry. Normally describes an accelerator keystroke sequence that may be typed to invoke the same function as the menu entry. This option is not available for separator or tear-off entries.
background - Specifies a background color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the background option for the overall menu is used. This option is not available for separator or tear-off entries.
bitmap - Specifies a bitmap to display in the menu instead of a textual label, in any of the forms accepted by TkGetBitmap. This option overrides the label option but may be reset to an empty string to enable a textual label to be displayed. If a image option has been specified, it overrides bitmap. This option is not available for separator or tear-off entries.
columnbreak - When this option is zero, the appears below the previous entry. When this option is one, the menu appears at the top of a new column in the menu.
command - Specifies a string to return from TkWait whenever the menu entry is selected. This is usually the name of a routine that will be interpreted as a call in the program's main message loop. Not available for separator or tear-off entries.
font - Specifies the font to use when drawing the label or accelerator string in this entry. If this option is specified as an empty string (the default) then the font option for the overall menu is used. This option is not available for separator or tear-off entries.
foreground - Specifies a foreground color to use for displaying this entry when it is in the normal state (neither active nor disabled). If this option is specified as an empty string (the default), then the foreground option for the overall menu is used. This option is not available for separator or tear-off entries.
hidemargin - Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. 1 indicates that the margin for the entry is hidden; 0 means that the margin is used.
image - Specifies an image to display in the menu instead of a text string or bitmap The image must have been created by some previous invocation of TkImage. This option overrides the label and bitmap options but may be reset to an empty string to enable a textual or bitmap label to be displayed. This option is not available for separator or tear-off entries.
indicatoron - Available only for checkbutton and radiobutton entries. Value is a boolean that determines whether or not the indicator should be displayed.
label - Specifies a string to display as an identifying label in the menu entry. Not available for separator or tear-off entries.
menu - Available only for cascade entries. Specifies the path name of the submenu associated with this entry. The submenu must be a child of the menu.
offvalue - Available only for checkbutton entries. Specifies the value to store in the entry's associated TK variable (see TkVar) when the entry is deselected.
onvalue - Available only for checkbutton entries. Specifies the value to store in the entry's associated TK variable (see TkVar) when the entry is selected.
selectcolor - Available only for checkbutton and radiobutton entries. Specifies the color to display in the indicator when the entry is selected. If the value is an empty string (the default) then the selectcolor option for the menu determines the indicator color.
selectimage - Available only for checkbutton and radiobutton entries. Specifies an image to display in the entry (in place of the image option) when it is selected. Value is the name of an image, which must have been created by some previous invocation of TkImage. This option is ignored unless the image option has been specified.
state - Specifies one of three states for the entry: normal, active, or disabled. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the activeForeground option for the menu along with the activebackground option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the disabledForeground option for the menu and the background option from the entry. This option is not available for separator entries.
underline - Specifies the integer index of a character to underline in the entry. This option is also queried by the default bindings and used to implement keyboard traversal. 0 corresponds to the first character of the text displayed in the entry, 1 to the next character, and so on. If a bitmap or image is displayed in the entry then this option is ignored. This option is not available for separator or tear-off entries.
value - Available only for radiobutton entries. Specifies the value to store in the entry's associated TK variable when the entry is selected. If an empty string is specified, then the label option for the entry as the value to store in the variable.
variable - Available only for checkbutton and radiobutton entries. Specifies the name of a global TK variable to set when the entry is selected. For checkbutton entries the TK variable is also set when the entry is deselected. For radiobutton entries, changing the variable causes the currently-selected entry to deselect itself.
DESCRIPTION
Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the label, bitmap, and image options for the entry. If the accelerator option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an indicator. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string.
In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is invoked. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries.
Entries may be disabled, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again.
Types:
command - The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, a command name is returned by TkWait. The command is specified with the command option.
separator - A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display appearance.
checkbutton - A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. When the entry is selected, a particular value is stored in a particular TK variable (as determined by the onvalue and variable options for the entry); when the entry is deselected another value (determined by the offvalue option) is stored in the TK variable. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a command option is specified for a checkbutton entry, then its value is returned by TkWait each time the entry is invoked; this happens after toggling the entry's selected state.
radiobutton - A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups of which only one entry may be selected at a time. Whenever a particular entry becomes selected it stores a particular value into a particular TK variable (as determined by the value and variable options for the entry). This action causes any previously-selected entry in the same group to deselect itself. Once an entry has become selected, any change to the entry's associated variable will cause the entry to deselect itself. Grouping of radiobutton entries is determined by their associated variables: if two entries have the same associated TK variable then they are in the same group. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the selectcolor option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If a command option is specified for a radiobutton entry, then its value is returned by TkWait each time the entry is invoked; this happens after selecting the entry.
cascade - A cascade entry is one with an associated menu (determined by the menu option). Cascade entries allow the construction of cascading menus. The associated menu must be a child of the menu containing the cascade entry (this is needed in order for menu traversal to work correctly).