home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.n / menubar.n < prev    next >
Encoding:
Text File  |  1995-07-21  |  10.6 KB  |  334 lines
  1. '\"
  2. '\" Copyright (c) 1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/menubar.n,v 1.4 93/09/04 17:03:40 ouster Exp $ SPRITE (Berkeley)
  22. '/" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .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
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS tk_menuBar tk
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. tk_menuBar, tk_bindForTraversal \- Support for menu bars
  210. .SH SYNOPSIS
  211. \fBtk_menuBar \fIframe \fR?\fImenu menu ...\fR?
  212. .sp
  213. \fBtk_bindForTraversal \fIarg arg ... \fR
  214. .BE
  215.  
  216. .SH DESCRIPTION
  217. .PP
  218. These two commands are Tcl procedures in the Tk script library.
  219. They provide support for menu bars.
  220. A menu bar is a frame that contains a collection of menu buttons that
  221. work together, so that the user can scan from one menu to another with
  222. the mouse: if the mouse button is pressed over one menubutton (causing it
  223. to post its menu) and the mouse is moved over another menubutton
  224. in the same menu bar without releasing the mouse button, then the
  225. menu of the first menubutton is unposted and the menu of the
  226. new menubutton is posted instead.
  227. Menus in a menu bar can also be accessed using keyboard traversal (i.e.
  228. by typing keystrokes instead of using the mouse).
  229. In order for an application to use these procedures, it must do three
  230. things, which are described in the paragraphs below.
  231. .PP
  232. First, each application must call \fBtk_menuBar\fR to provide information
  233. about the menubar.
  234. The \fIframe\fR argument gives the path name of the frame that contains
  235. all of the menu buttons, and the \fImenu\fR arguments give path names
  236. for all of the menu buttons associated with the menu bar.
  237. Normally \fIframe\fR is the parent of each of the \fImenu\fR's.
  238. This need not be the case, but \fIframe\fR must be an ancestor of
  239. each of the \fImenu\fR's in order for grabs to work correctly when
  240. the mouse is used to pull down menus.
  241. The order of the \fImenu\fR arguments determines the traversal order
  242. for the menu buttons.
  243. If \fBtk_menuBar\fR is called without any \fImenu\fR arguments, it
  244. returns a list containing the current menu buttons for \fIframe\fR,
  245. or an empty string if \fIframe\fR isn't currently set up as a menu bar.
  246. If \fBtk_menuBar\fR is called with a single \fImenu\fR argument
  247. consisting of an empty string, any menubar information for \fIframe\fR
  248. is removed;  from now on the menu buttons will function independently
  249. without keyboard traversal.
  250. Only one menu bar may be defined at a time within each top-level window.
  251. .PP
  252. The second thing an application must do is to identify the traversal
  253. characters for menu buttons and menu entries.
  254. This is done by underlining those characters using the
  255. \fB\-underline\fR options for the widgets.
  256. The menu traversal system uses this information to traverse the
  257. menus under keyboard control (see below).
  258. .PP
  259. The third thing that an application must do
  260. is to make sure that the input focus is always in a window that
  261. has been configured to support menu traversal.
  262. If the input focus is \fBnone\fR then input characters will
  263. be discarded and no menu traversal will be possible.
  264. .VS
  265. If you have no other place to set the focus, set it to the menubar
  266. widget:  \fBtk_menuBar\fR creates bindings for its \fIframe\fR argument to
  267. support menu traversal.
  268. .PP
  269. The Tk startup scripts configure all the Tk widget classes with
  270. bindings to support menu traversal, so menu traversal will be possible
  271. regardless of which widget has the focus.
  272. .VE
  273. If your application defines new classes of widgets that support the
  274. input focus, then you should call \fBtk_bindForTraversal\fR for
  275. each of these classes.
  276. \fBTk_bindForTraversal\fR takes any number of arguments, each of
  277. which is a widget path name or widget class name.
  278. It sets up bindings for all the named widgets and
  279. classes so that the menu traversal system will be invoked when
  280. appropriate keystrokes are typed in those widgets or classes.
  281.  
  282. .SH "MENU TRAVERSAL BINDINGS"
  283. .PP
  284. Once an application has made the three arrangements described
  285. above, menu traversal will be available.
  286. At any given time, the only menus available for traversal
  287. are those associated with the top-level window containing the
  288. input focus.
  289. Menu traversal is initiated by one of the following actions:
  290. .IP [1]
  291. If <F10> is typed, then the first menu button in the list for the
  292. top-level window is posted and the first entry within that
  293. menu is selected.
  294. .IP [2]
  295. If <Alt-\fIkey\fR> is pressed, then the menu button that has \fIkey\fR
  296. as its underlined character is posted
  297. and the first entry within that menu is selected.
  298. The comparison between \fIkey\fR and the underlined characters
  299. ignores case differences.
  300. If no menu button matches \fIkey\fR then the keystroke has no
  301. effect.
  302. .IP [3]
  303. Clicking mouse button 1 on a menu button posts that menu and selects
  304. its first entry.
  305. .PP
  306. Once a menu has been posted, the input focus is switched to that
  307. menu and the following actions are possible:
  308. .IP [1]
  309. Typing <ESC> or clicking mouse button 1 outside the menu button or
  310. its menu will abort the menu traversal.
  311. .IP [2]
  312. If <Alt-\fIkey\fR> is pressed, then the entry in the posted menu
  313. whose underlined character is \fIkey\fR is invoked.
  314. This causes the menu to be unposted, the entry's action to be
  315. taken, and the menu traversal to end.
  316. The comparison between \fIkey\fR and underlined characters ignores
  317. case differences.
  318. If no menu entry matches \fIkey\fR then the keystroke is ignored.
  319. .IP [3]
  320. The arrow keys may be used to move among entries and menus.
  321. The left and right arrow keys move circularly among the available
  322. menus and the up and down arrow keys move circularly among the
  323. entries in the current menu.
  324. .IP [4]
  325. If <Return> is pressed, the selected entry in the posted menu is
  326. invoked, which causes the menu to be unposted, the entry's action
  327. to be taken, and the menu traversal to end.
  328. .PP
  329. When a menu traversal completes, the input focus reverts to the
  330. window that contained it when the traversal started.
  331.  
  332. .SH KEYWORDS
  333. keyboard traversal, menu, menu bar, post
  334.