menubar - Create and manipulate menubar menu widgets

SYNOPSIS

INHERITANCE

STANDARD OPTIONS

activeBackground activeBorderWidth activeForeground anchor foreground

borderWidth cursor disabledForeground font padX

highlightBackground highligthThickness highlightColor justify

padY relief wrapLength background

See the "options" manual entry for details on the standard options.

WIDGET-SPECIFIC OPTIONS

Name:                   helpVariable
Class:                  HelpVariable
Command-Line Switch:	-helpvariable

Specifies the global variable to update whenever the mouse is in motion over a menu entry. This global variable is updated with the current value of the active menu entry's helpStr. Other widgets can "watch" this variable with the trace command, or as is the case with entry or label widgets, they can set their textVariable to the same global variable. This allows for a simple implementation of a help status bar. Whenever the mouse leaves a menu entry, the helpVariable is set to the empty string {}. The mainwindow(1) associates its helpstatus and its menubar in this fashion.

Name:                   menuButtons
Class:                  MenuButtons
Command-Line Switch:	-menubuttons

The menuButton option is a string which specifies the arrangement of menubuttons on the menubar frame. Each menubutton entry is delimited by the newline character.

specifies that three menubuttons will be added to the menubar (file, edit, options). Each entry is translated into an add command call.

The menuButtons option can accept embedded variables, commands, and backslash quoting. Embedded variables and commands must be enclosed in curly braces ({}) to ensure proper parsing of the substituted values.

DESCRIPTION

The menubar command creates a new window (given by the pathName argument) and makes it into a menubar menu widget. Additional options, described above may be specified on the command line or in the option database to configure aspects of the menubar such as its colors and font. The menubar command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

A menubar is a widget that simplifies the task of creating menu hierarchies. It encapsulates a frame widget, as well as menubuttons, menus, and menu entries. The menubar allows menus to be specified and referenced in a more consistent manner than using Tk to build menus directly. Menubar allows a menu tree to be expressed in a hierachical "language". The menubar accepts a menuButtons option that allows a list of menubuttons to be added to the menubar. In turn, each menubutton accepts a menu option that specifies a list of menu entries to be added to the menubutton's menu. Cascade entries also accept the menu option for specifying a list of menu entries to be added to the cascade's menu. Additionally, the menubar allows each component of the menubar system to be referenced by a simple menuPathName syntax. The menubar also extends the set of options for menu entries to include a helpStr option.

MENU PATH NAMES

A menuPathName is a series of component names separated by the `.' character. Each menubar component can be referenced via these menuPathNames. menuPathNames are similar to widget pathNames in Tk. Some correspond directly to a widget pathName (components of type menu or menubutton), others correspond to a menu entry type. Every widget and entry in a menubar can be referenced with the menuPathName naming convention. A menubar can have four types of components:

frame. A menubar holds exactly one frame which manages menubuttons. The frame is always signified by the `.' character as the path name.

menubutton. A menubutton corresponds directly to a Tk menubutton. See menubutton(n).

menu. A menu is attached to a menubutton and corresponds directly to Tk's menu widget. A menu is always signified by the menuPathName ending with the keyword menu. See menu(n).

entry. An entry corresponds directly to Tk's menu widget entries. Menus consist of a column of one line entries. Entries may be of type: command, checkbutton, radiobutton, separator, or cascade. For a complete description of these types see the discussion on ENTRIES in menu(n).

The suffix of a menuPathName may have the form of:

tkWidgetName

Specifies the name of the component, either a frame, menubutton, menu, or an entry. This is the normal naming of widgets. For example, .file references a menubutton named file.

The menuPathName is a series of segment names, each separated by the '.' character. Segment names may be one of the following forms:

number

Specifies the index of the the component. For menubuttons, 0 corresponds to the left-most menubutton of the menu bar frame. As an example, .1 would correspond to the second menubutton on the menu bar frame.

For entries, 0 corresponds to the top-most entry of the menu. For example, .file.0 would correspond to the first entry on the menu attached to the menubutton named file.

end

Specifes the last component. For menubuttons, it specifies the right-most entry of the menu bar frame. For menu entries, it specifies the bottom-most entry of the menu.

last

Same as end.

Finally, menu components always end with the menu keyword. These components are automatically created via the -menu option on menubuttons and cascades or via the add or insert commands.

menu

Specifes the menu pane that is associated with the given menubutton prefix. For example, .file.menu specifies the menu pane attached to the .file menubutton.

For example, the path .file.new specifies the entry named new on the menu associated with the file menubutton located on the menu bar. The path .file.menu specifies the menu pane associated with the menubutton .file. The path .last specifies the last menu on the menu bar. The path .0.last would specify the first menu (file) and the last entry on that menu (quit), yielding .file.quit. As a restriction, the last name segment of menuPathName cannot be one of the keywords last, menu, end, nor may it be a numeric value (integer).

WIDGET-SPECIFIC METHODS

The menubar command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the widget. It has the following general form:

pathName option ?arg arg ...?

In addition, many of the widget commands for menubar take as one argument a path name to a menu component. These path names are called menuPathNames. See the discussion on MENUBAR PATH NAMES above.

The following commands are possible for menubar widgets:

pathName add type menuPathName ?option value option value?

Adds either a menu to the menu bar or a menu entry to a menu pane.

If additional arguments are present, they specify options available to component type entry. See the man pages for menu(1) in the section on ENTRIES. If type is one of cascade, checkbutton, command, radiobutton, or separator it adds a new entry to the bottom of the menu denoted by the prefix of menuPathName. If additonal arguments are present, they specify options available to menu entry widgets. In addition, the helpStr option is added by the menubar widget to all components of type entry.

-helpstr value

Specifes the string to associate with the entry. When the mouse moves over the associated entry, the variable denoted by helpVariable is set. Another widget can bind to the helpVariable and thus display status help.

If the type of the component added is menubutton or cascade, a menubutton or cascade is added to the menubar. If additional arguments are present, they specify options available to menubutton or cascade widgets. In addition, the menu option is added by the menubar widget to all menubutton and cascade widgets.

-menu menuSpec

This is only valid for menuPathNames of type menubutton or cascade. Specifes an option set and/or a set of entries to place on a menu and associate with the menubutton or cascade. The option keyword allows the menu widget to be configured. Each item in the menuSpec is treated as add commands (each with the possibility of having other -menu options). In this way a menu can be recursively built.

The last segment of menuPathName cannot be one of the keywords last, menu, end. Additionally, it may not be a number. However the menuPathName may be referenced in this manner (see discussion of COMPONENT PATH NAMES).

Note that the same curly brace quoting rules apply to -menu option strings as did to -menubuttons option strings. See the earlier discussion on umenubuttons in the "WIDGET-SPECIFIC OPTIONS" section.

pathName cget option

Returns the current value of the configuration option given by option.

pathName configure ?options value option value?