'\"
'\" Copyright 1992 Regents of the University of California
'\" Permission to use, copy, modify, and distribute this
'\" documentation for any purpose and without fee is hereby
'\" granted, provided that this notice appears in all copies.
'\" The University of California makes no representations about
'\" the suitability of this material for any purpose.  It is
'\" provided "as is" without express or implied warranty.
'\" 
'\" $Header: /rel/cvsfiles/unsupported/latest/tk/doc/menubar.n,v 1.1 1993/01/24 04:59:50 zoo Exp $ SPRITE (Berkeley)
'/" 
.\" The definitions below are for supplemental macros used in Sprite
.\" manual entries.
.\"
.\" .HS name section [date [version]]
.\"	Replacement for .TH in other man pages.  See below for valid
.\"	section names.
.\"
.\" .AP type name in/out [indent]
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS [type [name]]
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .VS
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
'\"	# Heading for Sprite man pages
.de HS
.if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
.if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
.if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
.if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
.if t .wh -1.3i ^B
.nr ^l \\n(.l
.ad b
..
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp .5
..
.HS tk_menuBar cmds
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tk_menuBar, tk_bindForTraversal \- Support for menu bars
.SH SYNOPSIS
\fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR?
.sp
\fBtk_bindForTraversal \fIarg arg ... \fR
.BE

.SH DESCRIPTION
.PP
These two commands are Tcl procedures in the Tk script library.
They provide support for menu bars.
A menu bar is a frame that contains a collection of menu buttons that
work together, so that the user can scan from one menu to another with
the mouse: if the mouse button is pressed over one menubutton (causing it
to post its menu) and the mouse is moved over another menubutton
in the same menu bar without releasing the mouse button, then the
menu of the first menubutton is unposted and the menu of the
new menubutton is posted instead.
Menus in a menu bar can also be accessed using keyboard traversal (i.e.
by typing keystrokes instead of using the mouse).
In order for an application to use these procedures, it must do three
things, which are described in the paragraphs below.
.PP
First, each application must call \fBtk_menuBar\fR to provide information
about the menubar.
The \fIframe\fR argument gives the path name of the frame that contains
all of the menu buttons, and the \fImenu\fR arguments give path names
for all of the menu buttons associated with the menu bar.
Normally \fIframe\fR is the parent of each of the \fImenu\fR's.
This need not be the case, but \fIframe\fR must be an ancestor of
each of the \fImenu\fR's in order for grabs to work correctly when
the mouse is used to pull down menus.
The order of the \fImenu\fR arguments determines the traversal order
for the menu buttons.
If \fBtk_menuBar\fR is called without any \fImenu\fR arguments, it
returns a list containing the current menu buttons for \fIframe\fR,
or an empty string if \fIframe\fR isn't currently set up as a menu bar.
If \fBtk_menuBar\fR is called with a single \fImenu\fR argument
consisting of an empty string, any menubar information for \fIframe\fR
is removed;  from now on the menu buttons will function independently
without keyboard traversal.
Only one menu bar may be defined at a time within each top-level window.
.PP
The second thing an application must do is to identify the traversal
characters for menu buttons and menu entries.
This is done by underlining those characters using the
\fB\-underline\fR options for the widgets.
The menu traversal system uses this information to traverse the
menus under keyboard control (see below).
.PP
The third thing that an application must do
is to make sure that the input focus is always in a window that
has been configured to support menu traversal.
If the input focus is \fBnone\fR then input characters will
be discarded and no menu traversal will be possible.
By default, the Tk startup scripts configure all the Tk widget classes to
support menu traversal (they call the \fBtk_bindForTraversal\fR
procedure described below).
.PP
If your application defines new classes of widgets that support the
input focus, then you should call \fBtk_bindForTraversal\fR for
each of these classes.
\fBTk_bindForTraversal\fR takes any number of arguments, each of
which is a widget path name or widget class name.
It sets up bindings for all the named widgets and
classes so that the menu traversal system will be invoked when
appropriate keystrokes are typed in those widgets or classes.
.PP
Typically, applications will also call \fBtk_bindForTraversal\fR
on their main window (``.'') and set the input focus to that window
whenever it doesn't make sense for it to be anywhere else.
This guarantees that menu traversal will be possible even when
there is no other input focus.

.SH "MENU TRAVERSAL BINDINGS"
.PP
Once an application has made the three arrangements described
above, menu traversal will be available.
At any given time, the only menus available for traversal
are those associated with the top-level window containing the
input focus.
Menu traversal is initiated by one of the following actions:
.IP [1]
If <F10> is typed, then the first menu button in the list for the
top-level window is posted and the first entry within that
menu is selected.
.IP [2]
If <Alt-\fIkey\fR> is pressed, then the menu button that has \fIkey\fR
as its underlined character is posted
and the first entry within that menu is selected.
The comparison between \fIkey\fR and the underlined characters
ignores case differences.
If no menu button matches \fIkey\fR then the keystroke has no
effect.
.IP [3]
Clicking mouse button 1 on a menu button posts that menu and selects
its first entry.
.PP
Once a menu has been posted, the input focus is switched to that
menu and the following actions are possible:
.IP [1]
Typing <ESC> or clicking mouse button 1 outside the menu button or
its menu will abort the menu traversal.
.IP [2]
If <Alt-\fIkey\fR> is pressed, then the entry in the posted menu
whose underlined character is \fIkey\fR is invoked.
This causes the menu to be unposted, the entry's action to be
taken, and the menu traversal to end.
The comparison between \fIkey\fR and underlined characters ignores
case differences.
If no menu entry matches \fIkey\fR then the keystroke is ignored.
.IP [3]
The arrow keys may be used to move among entries and menus.
The left and right arrow keys move circularly among the available
menus and the up and down arrow keys move circularly among the
entries in the current menu.
.IP [4]
If <Return> is pressed, the selected entry in the posted menu is
invoked, which causes the menu to be unposted, the entry's action
to be taken, and the menu traversal to end.
.PP
When a menu traversal completes, the input focus reverts to the
window that contained it when the traversal started.

.SH KEYWORDS
keyboard traversal, menu, menu bar, post
