home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / traversal.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  9.0 KB  |  309 lines
  1. '\"
  2. '\" Copyright 1992 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/traversal.man,v 1.1 92/06/03 16:53:58 ouster Exp $ SPRITE (Berkeley)
  11. '/" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .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
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS tk_menus cmds
  189. .BS
  190. '\" Note:  do not modify the .SH NAME line immediately below!
  191. .SH NAME
  192. tk_menus, tk_bindForTraversal \- Enable keyboard menu traversal
  193. .SH SYNOPSIS
  194. \fBtk_menus \fItoplevel \fR?\fImenu menu ...\fR?
  195. .sp
  196. \fBtk_bindForTraversal \fIarg arg ... \fR
  197. .BE
  198.  
  199. .SH DESCRIPTION
  200. .PP
  201. These two commands are Tcl procedures provided as part of the Tk script
  202. library.
  203. They provide the top-level interface for Tk's support for keyboard
  204. traversal of menus.
  205. These procedures need not be used by applications that prefer not to
  206. have keyboard traversal of menus or wish to implement it in some other
  207. fashion.
  208. In order for an application to use this facility, it must do three
  209. things, which are described in the paragraphs below.
  210. .PP
  211. First, each application must call \fBtk_menus\fR to identify the
  212. menu buttons associated with each top-level window that contains
  213. menus.
  214. The \fItoplevel\fR argument gives the path name of a top-level window
  215. and the \fImenu\fR arguments give path names for all of the menu
  216. buttons in that top-level window.
  217. The order of the \fImenu\fR arguments determines the traversal order
  218. for the menu buttons.
  219. If \fBtk_menus\fR is called without any \fImenu\fR arguments, it
  220. returns the current menu list for \fItoplevel\fR, or an empty string
  221. if there is no menu list.
  222. If \fBtk_menus\fR is called with a single \fImenu\fR argument
  223. consisting of an empty string, menu traversal will be disabled for
  224. \fItoplevel\fR.
  225. .PP
  226. The second thing an application must do to use menu traversal is
  227. to identify the traversal characters for menu buttons and menu entries.
  228. This is done by underlining those characters using the
  229. \fB\-underline\fR options for the widgets.
  230. The menu traversal system uses this information to traverse the
  231. menus under keyboard control (see below).
  232. .PP
  233. The third thing that an application must do to use menu traversal
  234. is to make sure that the input focus is always in a window that
  235. has been configured to support menu traversal.
  236. If the input focus is \fBnone\fR then input characters will
  237. be discarded and no menu traversal will be possible.
  238. By default, the Tk startup scripts configure all the Tk widget classes to
  239. support menu traversal (they call the \fBtk_bindForTraversal\fR
  240. procedure described below).
  241. .PP
  242. If your application defines new classes of widgets that support the
  243. input focus, then you should call \fBtk_bindForTraversal\fR for
  244. each of these classes.
  245. \fBTk_bindForTraversal\fR takes any number of arguments, each of
  246. which is a widget path name or widget class name.
  247. It sets up bindings for all the named widgets and
  248. classes so that the menu traversal system will be invoked when
  249. appropriate keystrokes are typed in those widgets or classes.
  250. .PP
  251. Typically, applications will also call \fBtk_bindForTraversal\fR
  252. on their main window (``.'') and set the input focus to that window
  253. whenever it doesn't make sense for it to be anywhere else.
  254. This guarantees that menu traversal will be possible even when
  255. there is no other input focus.
  256.  
  257. .SH "MENU TRAVERSAL BINDINGS"
  258. .PP
  259. Once an application has made the three arrangements described
  260. above, menu traversal will be available.
  261. At any given time, the only menus available for traversal
  262. are those associated with the top-level window containing the
  263. input focus.
  264. Menu traversal is initiated by one of the following actions:
  265. .IP [1]
  266. If <F10> is typed, then the first menu button in the list for the
  267. top-level window is posted and the first entry within that
  268. menu is selected.
  269. .IP [2]
  270. If <Alt-\fIkey\fR> is pressed, then the menu button that has \fIkey\fR
  271. as its underlined character is posted
  272. and the first entry within that menu is selected.
  273. The comparison between \fIkey\fR and the underlined characters
  274. ignores case differences.
  275. If no menu button matches \fIkey\fR then the keystroke has no
  276. effect.
  277. .IP [3]
  278. Clicking mouse button 1 on a menu button posts that menu and selects
  279. its first entry.
  280. .PP
  281. Once a menu has been posted, the input focus is switched to that
  282. menu and the following actions are possible:
  283. .IP [1]
  284. Typing <ESC> or clicking mouse button 1 outside the menu button or
  285. its menu will abort the menu traversal.
  286. .IP [2]
  287. If <Alt-\fIkey\fR> is pressed, then the entry in the posted menu
  288. whose underlined character is \fIkey\fR is invoked.
  289. This causes the menu to be unposted, the entry's action to be
  290. taken, and the menu traversal to end.
  291. The comparison between \fIkey\fR and underlined characters ignores
  292. case differences.
  293. If no menu entry matches \fIkey\fR then the keystroke is ignored.
  294. .IP [3]
  295. The arrow keys may be used to move among entries and menus.
  296. The left and right arrow keys move circularly among the available
  297. menus and the up and down arrow keys move circularly among the
  298. entries in the current menu.
  299. .IP [4]
  300. If <Return> is pressed, the selected entry in the posted menu is
  301. invoked, which causes the menu to be unposted, the entry's action
  302. to be taken, and the menu traversal to end.
  303. .PP
  304. When a menu traversal completes, the input focus reverts to the
  305. window that contained it when the traversal started.
  306.  
  307. .SH KEYWORDS
  308. keyboard traversal, menus, post
  309.