home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / Xlib / CH12 < prev    next >
Encoding:
Text File  |  1991-07-30  |  76.7 KB  |  2,705 lines

  1. \&
  2. .sp 1
  3. .ce 3
  4. \s+1\fBChapter 12\fP\s-1
  5.  
  6. \s+1\fBInput Device Functions\fP\s-1
  7. .sp 2
  8. .nr H1 12
  9. .nr H2 0
  10. .nr H3 0
  11. .nr H4 0
  12. .nr H5 0
  13. .na
  14. .LP
  15. .XS
  16. Chapter 12: Input Device Functions
  17. .XE
  18. You can use the Xlib input device functions to:
  19. .IP \(bu 5
  20. Grab the pointer and individual buttons on the pointer
  21. .IP \(bu 5
  22. Grab the keyboard and individual keys on the keyboard
  23. .IP \(bu 5
  24. Move the pointer
  25. .IP \(bu 5
  26. Set the input focus
  27. .IP \(bu 5
  28. Manipulate the keyboard and pointer settings
  29. .IP \(bu 5
  30. Manipulate the keyboard encoding
  31. .RE
  32. .NH 2
  33. Pointer Grabbing 
  34. .XS
  35. \*(SN Pointer Grabbing  
  36. .XE
  37. .LP
  38. Xlib provides functions that you can use to control input from the pointer,
  39. which usually is a mouse.
  40. Usually, as soon as keyboard and mouse events occur,
  41. the X server delivers them to the appropriate client,
  42. which is determined by the window and input focus.
  43. The X server provides sufficient control over event delivery to
  44. allow window managers to support mouse ahead and various other
  45. styles of user interface.
  46. Many of these user interfaces depend upon synchronous delivery of events.
  47. The delivery of  pointer and keyboard events can be controlled
  48. independently.
  49. .LP
  50. When mouse buttons or keyboard keys are grabbed, events
  51. will be sent to the grabbing client rather than the normal
  52. client who would have received the event.
  53. If the keyboard or pointer is in asynchronous mode,
  54. further mouse and keyboard events will continue to be processed.
  55. If the keyboard or pointer is in synchronous mode, no
  56. further events are processed until the grabbing client
  57. allows them (see
  58. .PN XAllowEvents ).
  59. The keyboard or pointer is considered frozen during this
  60. interval.
  61. The event that triggered the grab can also be replayed.
  62. .LP
  63. Note that the logical state of a device (as seen by client applications)
  64. may lag the physical state if device event processing is frozen.
  65. .LP
  66. .IN "Active grab" "" "@DEF@"
  67. There are two kinds of grabs:
  68. active and passive.
  69. An active grab occurs when a single client grabs the keyboard and/or pointer
  70. explicitly (see
  71. .PN XGrabPointer
  72. and
  73. .PN XGrabKeyboard ).
  74. .IN "Passive grab"
  75. A passive grab occurs when clients grab a particular keyboard key 
  76. or pointer button in a window,
  77. and the grab will activate when the key or button is actually pressed.
  78. Passive grabs are convenient for implementing reliable pop-up menus.
  79. For example, you can guarantee that the pop-up is mapped 
  80. before the up pointer button event occurs by
  81. grabbing a button requesting synchronous behavior.
  82. The down event will trigger the grab and freeze further
  83. processing of pointer events until you have the chance to
  84. map the pop-up window.
  85. You can then allow further event processing.
  86. The up event will then be correctly processed relative to the
  87. pop-up window.
  88. .LP
  89. For many operations,
  90. there are functions that take a time argument.
  91. The X server includes a timestamp in various events.
  92. One special time, called
  93. .IN "CurrentTime" "" "@DEF@"
  94. .IN "time" "" "@DEF@"
  95. .PN CurrentTime ,
  96. represents the current server time.
  97. The X server maintains the time when the input focus was last changed,
  98. when the keyboard was last grabbed,
  99. when the pointer was last grabbed,
  100. or when a selection was last changed.
  101. Your
  102. application may be slow reacting to an event.
  103. You often need some way to specify that your
  104. request should not occur if another application has in the meanwhile
  105. taken control of the keyboard, pointer, or selection.
  106. By providing the timestamp from the event in the request, 
  107. you can arrange that the operation not take effect
  108. if someone else has performed an operation in the meanwhile.
  109. .LP
  110. A timestamp is a time value, expressed in milliseconds. 
  111. It typically is the time since the last server reset.
  112. Timestamp values wrap around (after about 49.7 days).
  113. The server, given its current time is represented by timestamp T, 
  114. always interprets timestamps from clients by treating half of the timestamp 
  115. space as being later in time than T.
  116. One timestamp value, named
  117. .PN CurrentTime ,
  118. is never generated by the server.
  119. This value is reserved for use in requests to represent the current server time.
  120. .LP
  121. For many functions in this section,
  122. you pass pointer event mask bits.
  123. The valid pointer event mask bits are:
  124. .PN ButtonPressMask ,
  125. .PN ButtonReleaseMask ,
  126. .PN EnterWindowMask ,
  127. .PN LeaveWindowMask ,
  128. .PN PointerMotionMask ,
  129. .PN PointerMotionHintMask ,
  130. .PN Button1MotionMask ,
  131. .PN Button2MotionMask ,
  132. .PN Button3MotionMask ,
  133. .PN Button4MotionMask ,
  134. .PN Button5MotionMask ,
  135. .PN ButtonMotionMask ,
  136. and
  137. .PN KeyMapStateMask .
  138. For other functions in this section,
  139. you pass keymask bits.
  140. The valid keymask bits are:
  141. .PN ShiftMask ,
  142. .PN LockMask ,
  143. .PN ControlMask ,
  144. .PN Mod1Mask ,
  145. .PN Mod2Mask ,
  146. .PN Mod3Mask ,
  147. .PN Mod4Mask ,
  148. and
  149. .PN Mod5Mask .
  150. .LP
  151. .sp
  152. To grab the pointer, use
  153. .PN XGrabPointer .
  154. .IN "Grabbing" "pointer"
  155. .IN "Pointer" "grabbing"
  156. .IN "XGrabPointer" "" "@DEF@"
  157. .\" Start marker code here
  158. .FD 0
  159. .\" $Header: XGrabPointer.f,v 1.1 88/02/26 10:01:06 mento Exp $
  160. int XGrabPointer\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, \fIpointer_mode\fP\^,
  161.                \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^, \fItime\fP\^)
  162. .br
  163.       Display *\fIdisplay\fP\^;
  164. .br
  165.       Window \fIgrab_window\fP\^;
  166. .br
  167.       Bool \fIowner_events\fP\^;
  168. .br
  169.       unsigned int \fIevent_mask\fP\^;    
  170. .br
  171.       int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^; 
  172. .br
  173.       Window \fIconfine_to\fP\^; 
  174. .br
  175.       Cursor \fIcursor\fP\^; 
  176. .br
  177.       Time \fItime\fP\^; 
  178. .FN
  179. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  180. .IP \fIdisplay\fP 1i
  181. Specifies the connection to the X server.
  182. .IP \fIgrab_window\fP 1i
  183. Specifies the grab window.
  184. .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
  185. .IP \fIowner_events\fP 1i
  186. Specifies a Boolean value that indicates whether the pointer 
  187. events are to be reported as usual or reported with respect to the grab window 
  188. if selected by the event mask.
  189. .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
  190. .IP \fIevent_mask\fP 1i
  191. Specifies which pointer events are reported to the client.
  192. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
  193. .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
  194. .IP \fIpointer_mode\fP 1i
  195. Specifies further processing of pointer events.
  196. You can pass 
  197. .PN GrabModeSync 
  198. or
  199. .PN GrabModeAsync .
  200. .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
  201. .IP \fIkeyboard_mode\fP 1i
  202. Specifies further processing of keyboard events.
  203. You can pass 
  204. .PN GrabModeSync 
  205. or
  206. .PN GrabModeAsync .
  207. .\" $Header: confineto.a,v 1.2 88/05/14 07:01:28 mento Exp $
  208. .IP \fIconfine_to\fP 1i
  209. Specifies the window to confine the pointer in or
  210. .PN None .
  211. .\" $Header: cursor_grab.a,v 1.2 88/04/06 14:23:01 mento Exp $
  212. .IP \fIcursor\fP 1i
  213. Specifies the cursor that is to be displayed during the grab or
  214. .PN None . 
  215. .IP \fItime\fP 1i
  216. Specifies the time.
  217. You can pass either a timestamp or
  218. .PN CurrentTime .
  219. .\" End marker code here
  220. .LP
  221. .\" $Header: XGrabPointer.d,v 1.3 88/08/19 20:19:16 mento Exp $
  222. The
  223. .PN XGrabPointer
  224. function actively grabs control of the pointer and returns
  225. .PN GrabSuccess
  226. if the grab was successful.
  227. Further pointer events are reported only to the grabbing client.
  228. .PN XGrabPointer
  229. overrides any active pointer grab by this client.
  230. If owner_events is 
  231. .PN False , 
  232. all generated pointer events
  233. are reported with respect to grab_window and are reported only if
  234. selected by event_mask.
  235. If owner_events is 
  236. .PN True
  237. and if a generated
  238. pointer event would normally be reported to this client, 
  239. it is reported as usual. 
  240. Otherwise, the event is reported with respect to the
  241. grab_window and is reported only if selected by event_mask.
  242. For either value of owner_events, unreported events are discarded.
  243. .LP
  244. If the pointer_mode is 
  245. .PN GrabModeAsync , 
  246. pointer event processing continues as usual.
  247. If the pointer is currently frozen by this client, 
  248. the processing of events for the pointer is resumed.
  249. If the pointer_mode is 
  250. .PN GrabModeSync , 
  251. the state of the pointer, as seen by
  252. client applications,
  253. appears to freeze, and the X server generates no further pointer events
  254. until the grabbing client calls 
  255. .PN XAllowEvents
  256. or until the pointer grab is released.
  257. Actual pointer changes are not lost while the pointer is frozen;
  258. they are simply queued in the server for later processing.
  259. .LP
  260. If the keyboard_mode is 
  261. .PN GrabModeAsync , 
  262. keyboard event processing is unaffected by activation of the grab.
  263. If the keyboard_mode is 
  264. .PN GrabModeSync , 
  265. the state of the keyboard, as seen by
  266. client applications,
  267. appears to freeze, and the X server generates no further keyboard events
  268. until the grabbing client calls 
  269. .PN XAllowEvents
  270. or until the pointer grab is released.
  271. Actual keyboard changes are not lost while the pointer is frozen;
  272. they are simply queued in the server for later processing.
  273. .LP
  274. If a cursor is specified, it is displayed regardless of what
  275. window the pointer is in.  
  276. If 
  277. .PN None
  278. is specified,
  279. the normal cursor for that window is displayed
  280. when the pointer is in grab_window or one of its subwindows;
  281. otherwise, the cursor for grab_window is displayed.
  282. .LP
  283. If a confine_to window is specified,
  284. the pointer is restricted to stay contained in that window.
  285. The confine_to window need have no relationship to the grab_window.
  286. If the pointer is not initially in the confine_to window, 
  287. it is warped automatically to the closest edge 
  288. just before the grab activates and enter/leave events are generated as usual. 
  289. If the confine_to window is subsequently reconfigured, 
  290. the pointer is warped automatically, as necessary, 
  291. to keep it contained in the window.
  292. .LP
  293. The time argument allows you to avoid certain circumstances that come up
  294. if applications take a long time to respond or if there are long network
  295. delays.
  296. Consider a situation where you have two applications, both
  297. of which normally grab the pointer when clicked on.
  298. If both applications specify the timestamp from the event, 
  299. the second application may wake up faster and successfully grab the pointer
  300. before the first application. 
  301. The first application then will get an indication that the other application 
  302. grabbed the pointer before its request was processed.
  303. .LP
  304. .PN XGrabPointer 
  305. generates
  306. .PN EnterNotify 
  307. and
  308. .PN LeaveNotify 
  309. events.
  310. .LP
  311. Either if grab_window or confine_to window is not viewable
  312. or if the confine_to window lies completely outside the boundaries of the root
  313. window,
  314. .PN XGrabPointer
  315. fails and returns
  316. .PN GrabNotViewable .
  317. If the pointer is actively grabbed by some other client,
  318. it fails and returns
  319. .PN AlreadyGrabbed .
  320. If the pointer is frozen by an active grab of another client,
  321. it fails and returns
  322. .PN GrabFrozen .
  323. If the specified time is earlier than the last-pointer-grab time or later 
  324. than the current X server time, it fails and returns
  325. .PN GrabInvalidTime .
  326. Otherwise, the last-pointer-grab time is set to the specified time
  327. .Pn ( CurrentTime 
  328. is replaced by the current X server time).
  329. .LP
  330. .PN XGrabPointer
  331. can generate
  332. .PN BadCursor ,
  333. .PN BadValue ,
  334. and
  335. .PN BadWindow 
  336. errors.
  337. .LP
  338. .sp
  339. To ungrab the pointer, use
  340. .PN XUngrabPointer .
  341. .IN "Ungrabbing" "pointer"
  342. .IN "Pointer" "ungrabbing"
  343. .IN "XUngrabPointer" "" "@DEF@"
  344. .\" Start marker code here
  345. .FD 0
  346. .\" $Header: XUngrabPntr.f,v 1.1 88/02/26 10:04:06 mento Exp $
  347. XUngrabPointer\^(\^\fIdisplay\fP, \fItime\fP\^)
  348. .br
  349.       Display *\fIdisplay\fP\^;
  350. .br
  351.       Time \fItime\fP\^;
  352. .FN
  353. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  354. .IP \fIdisplay\fP 1i
  355. Specifies the connection to the X server.
  356. .IP \fItime\fP 1i
  357. Specifies the time.
  358. You can pass either a timestamp or
  359. .PN CurrentTime .
  360. .\" End marker code here
  361. .LP
  362. .\" $Header: XUngrabPntr.d,v 1.4 88/08/19 20:21:36 mento Exp $
  363. The
  364. .PN XUngrabPointer
  365. function releases the pointer and any queued events
  366. if this client has actively grabbed the pointer from
  367. .PN XGrabPointer ,
  368. .PN XGrabButton ,
  369. or from a normal button press.
  370. .PN XUngrabPointer
  371. does not release the pointer if the specified
  372. time is earlier than the last-pointer-grab time or is later than the
  373. current X server time.
  374. It also generates 
  375. .PN EnterNotify 
  376. and 
  377. .PN LeaveNotify 
  378. events.
  379. The X server performs an 
  380. .PN UngrabPointer 
  381. request automatically if the event window or confine_to window 
  382. for an active pointer grab becomes not viewable
  383. or if window reconfiguration causes the confine_to window to lie completely
  384. outside the boundaries of the root window.
  385. .LP
  386. .sp
  387. To change an active pointer grab, use
  388. .PN XChangeActivePointerGrab .
  389. .IN "Pointer" "grabbing"
  390. .IN "Changing" "pointer grab" 
  391. .IN "XChangeActivePointerGrab" "" "@DEF@"
  392. .\" Start marker code here
  393. .FD 0
  394. .\" $Header: XChActPGrab.f,v 1.1 88/02/26 09:58:29 mento Exp $
  395. XChangeActivePointerGrab\^(\^\fIdisplay\fP, \fIevent_mask\fP\^, \fIcursor\fP\^, \fItime\fP\^)
  396. .br
  397.       Display *\fIdisplay\fP\^;
  398. .br
  399.       unsigned int \fIevent_mask\fP\^;
  400. .br
  401.       Cursor \fIcursor\fP\^;
  402. .br
  403.       Time \fItime\fP\^;
  404. .FN
  405. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  406. .IP \fIdisplay\fP 1i
  407. Specifies the connection to the X server.
  408. .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
  409. .IP \fIevent_mask\fP 1i
  410. Specifies which pointer events are reported to the client.
  411. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
  412. .\" $Header: cursor_def.a,v 1.2 88/05/13 13:12:57 mento Exp $
  413. .IP \fIcursor\fP 1i
  414. Specifies the cursor that is to be displayed or
  415. .PN None .
  416. .IP \fItime\fP 1i
  417. Specifies the time.
  418. You can pass either a timestamp or
  419. .PN CurrentTime .
  420. .\" End marker code here
  421. .LP
  422. .\" $Header: XChActPGrab.d,v 1.2 88/06/11 07:48:55 mento Exp $
  423. The
  424. .PN XChangeActivePointerGrab
  425. function changes the specified dynamic parameters if the pointer is actively
  426. grabbed by the client and if the specified time is no earlier than the
  427. last-pointer-grab time and no later than the current X server time.
  428. This function has no effect on the passive parameters of a
  429. .PN XGrabButton .
  430. The interpretation of event_mask and cursor is the same as described in
  431. .PN XGrabPointer .
  432. .LP
  433. .PN XChangeActivePointerGrab
  434. can generate
  435. .PN BadCursor 
  436. and
  437. .PN BadValue
  438. errors.
  439. .LP
  440. .sp
  441. To grab a pointer button, use
  442. .PN XGrabButton .
  443. .IN "Grabbing" "buttons"
  444. .IN "Button" "grabbing"
  445. .IN "XGrabButton" "" "@DEF@"
  446. .\" Start marker code here
  447. .FD 0
  448. .\" $Header: XGrabButton.f,v 1.2 88/05/14 07:20:38 mento Exp $
  449. XGrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_mask\fP\^, 
  450. .br
  451.                 \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fIconfine_to\fP\^, \fIcursor\fP\^)
  452. .br
  453.       Display *\fIdisplay\fP\^;
  454. .br
  455.       unsigned int \fIbutton\fP\^;
  456. .br
  457.       unsigned int \fImodifiers\fP\^;
  458. .br
  459.       Window \fIgrab_window\fP\^;
  460. .br
  461.       Bool \fIowner_events\fP\^;
  462. .br
  463.       unsigned int \fIevent_mask\fP\^;    
  464. .br
  465.       int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
  466. .br
  467.       Window \fIconfine_to\fP\^; 
  468. .br
  469.       Cursor \fIcursor\fP\^; 
  470. .FN
  471. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  472. .IP \fIdisplay\fP 1i
  473. Specifies the connection to the X server.
  474. .ds Bu grabbed
  475. .\" $Header: button_gen.a,v 1.2 88/08/04 11:06:39 mento Exp $
  476. .IP \fIbutton\fP 1i
  477. Specifies the pointer button that is to be \*(Bu or
  478. .PN AnyButton .
  479. .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
  480. .IP \fImodifiers\fP 1i
  481. Specifies the set of keymasks or
  482. .PN AnyModifier .
  483. The mask is the bitwise inclusive OR of the valid keymask bits.
  484. .IP \fIgrab_window\fP 1i
  485. Specifies the grab window.
  486. .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
  487. .IP \fIowner_events\fP 1i
  488. Specifies a Boolean value that indicates whether the pointer 
  489. events are to be reported as usual or reported with respect to the grab window 
  490. if selected by the event mask.
  491. .\" $Header: pointermask.a,v 1.3 88/05/14 07:34:39 mento Exp $
  492. .IP \fIevent_mask\fP 1i
  493. Specifies which pointer events are reported to the client.
  494. The mask is the bitwise inclusive OR of the valid pointer event mask bits.
  495. .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
  496. .IP \fIpointer_mode\fP 1i
  497. Specifies further processing of pointer events.
  498. You can pass 
  499. .PN GrabModeSync 
  500. or
  501. .PN GrabModeAsync .
  502. .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
  503. .IP \fIkeyboard_mode\fP 1i
  504. Specifies further processing of keyboard events.
  505. You can pass 
  506. .PN GrabModeSync 
  507. or
  508. .PN GrabModeAsync .
  509. .\" $Header: confineto.a,v 1.2 88/05/14 07:01:28 mento Exp $
  510. .IP \fIconfine_to\fP 1i
  511. Specifies the window to confine the pointer in or
  512. .PN None .
  513. .\" $Header: cursor_def.a,v 1.2 88/05/13 13:12:57 mento Exp $
  514. .IP \fIcursor\fP 1i
  515. Specifies the cursor that is to be displayed or
  516. .PN None .
  517. .\" End marker code here
  518. .LP
  519. .\" $Header: XGrabButton.d,v 1.4 88/08/19 20:24:59 mento Exp $
  520. The
  521. .PN XGrabButton
  522. function establishes a passive grab.
  523. In the future,
  524. the pointer is actively grabbed (as for
  525. .PN XGrabPointer ),
  526. the last-pointer-grab time is set to the time at which the button was pressed
  527. (as transmitted in the
  528. .PN ButtonPress
  529. event), and the
  530. .PN ButtonPress
  531. event is reported if all of the following conditions are true:
  532. .IP \(bu 5
  533. The pointer is not grabbed, and the specified button is logically pressed
  534. when the specified modifier keys are logically down,
  535. and no other buttons or modifier keys are logically down.
  536. .IP \(bu 5
  537. The grab_window contains the pointer.
  538. .IP \(bu 5
  539. The confine_to window (if any) is viewable.
  540. .IP \(bu 5
  541. A passive grab on the same button/key combination does not exist
  542. on any ancestor of grab_window.
  543. .LP
  544. The interpretation of the remaining arguments is as for
  545. .PN XGrabPointer .
  546. The active grab is terminated automatically when the logical state of the
  547. pointer has all buttons released
  548. (independent of the state of the logical modifier keys).
  549. .LP
  550. Note that the logical state of a device (as seen by client applications)
  551. may lag the physical state if device event processing is frozen.
  552. .LP
  553. This request overrides all previous grabs by the same client on the same
  554. button/key combinations on the same window.
  555. A modifiers of 
  556. .PN AnyModifier 
  557. is equivalent to issuing the grab request for all
  558. possible modifier combinations (including the combination of no modifiers).  
  559. It is not required that all modifiers specified have currently assigned 
  560. KeyCodes.
  561. A button of 
  562. .PN AnyButton 
  563. is equivalent to
  564. issuing the request for all possible buttons.
  565. Otherwise, it is not required that the specified button currently be assigned
  566. to a physical button.
  567. .LP
  568. If some other client has already issued a 
  569. .PN XGrabButton
  570. with the same button/key combination on the same window, a
  571. .PN BadAccess 
  572. error results.
  573. When using 
  574. .PN AnyModifier 
  575. or 
  576. .PN AnyButton , 
  577. the request fails completely,
  578. and a
  579. .PN BadAccess
  580. error results (no grabs are
  581. established) if there is a conflicting grab for any combination.
  582. .PN XGrabButton
  583. has no effect on an active grab.
  584. .LP
  585. .PN XGrabButton
  586. can generate
  587. .PN BadCursor ,
  588. .PN BadValue ,
  589. and
  590. .PN BadWindow 
  591. errors.
  592. .LP
  593. .sp
  594. To ungrab a pointer button, use
  595. .PN XUngrabButton .
  596. .IN "Ungrabbing" "buttons"
  597. .IN "Button" "ungrabbing"
  598. .IN "XUngrabButton" "" "@DEF@"
  599. .\" Start marker code here
  600. .FD 0
  601. .\" $Header: XUngrabBut.f,v 1.2 88/05/14 07:50:53 mento Exp $
  602. XUngrabButton\^(\^\fIdisplay\fP, \fIbutton\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
  603. .br
  604.       Display *\fIdisplay\fP\^;
  605. .br
  606.       unsigned int \fIbutton\fP\^;
  607. .br
  608.       unsigned int \fImodifiers\fP\^;
  609. .br
  610.       Window \fIgrab_window\fP\^;
  611. .FN
  612. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  613. .IP \fIdisplay\fP 1i
  614. Specifies the connection to the X server.
  615. .ds Bu released
  616. .\" $Header: button_gen.a,v 1.2 88/08/04 11:06:39 mento Exp $
  617. .IP \fIbutton\fP 1i
  618. Specifies the pointer button that is to be \*(Bu or
  619. .PN AnyButton .
  620. .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
  621. .IP \fImodifiers\fP 1i
  622. Specifies the set of keymasks or
  623. .PN AnyModifier .
  624. The mask is the bitwise inclusive OR of the valid keymask bits.
  625. .IP \fIgrab_window\fP 1i
  626. Specifies the grab window.
  627. .\" End marker code here
  628. .LP
  629. .\" $Header: XUngrabBut.d,v 1.2 88/06/11 07:54:20 mento Exp $
  630. The
  631. .PN XUngrabButton
  632. function releases the passive button/key combination on the specified window if
  633. it was grabbed by this client.
  634. A modifiers of 
  635. .PN AnyModifier 
  636. is
  637. equivalent to issuing 
  638. the ungrab request for all possible modifier combinations, including 
  639. the combination of no modifiers.
  640. A button of 
  641. .PN AnyButton 
  642. is equivalent to issuing the
  643. request for all possible buttons.
  644. .PN XUngrabButton
  645. has no effect on an active grab.
  646. .LP
  647. .PN XUngrabButton
  648. can generate
  649. .PN BadValue
  650. and
  651. .PN BadWindow 
  652. errors.
  653. .NH 2
  654. Keyboard Grabbing 
  655. .XS
  656. \*(SN Keyboard Grabbing 
  657. .XE
  658. .LP
  659. Xlib provides functions that you can use to grab or ungrab the keyboard
  660. as well as allow events.
  661. .LP
  662. For many functions in this section,
  663. you pass keymask bits.
  664. The valid keymask bits are:
  665. .PN ShiftMask ,
  666. .PN LockMask ,
  667. .PN ControlMask ,
  668. .PN Mod1Mask ,
  669. .PN Mod2Mask ,
  670. .PN Mod3Mask ,
  671. .PN Mod4Mask ,
  672. and
  673. .PN Mod5Mask .
  674. .LP
  675. .sp
  676. To grab the keyboard, use
  677. .PN XGrabKeyboard .
  678. .IN "Keyboard" "grabbing"
  679. .IN "Grabbing" "keyboard"
  680. .IN "XGrabKeyboard" "" "@DEF@"
  681. .\" Start marker code here
  682. .FD 0
  683. .\" $Header: XGrabKeybd.f,v 1.1 88/02/26 10:01:05 mento Exp $
  684. int XGrabKeyboard\^(\^\fIdisplay\fP, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^, \fItime\fP\^)
  685. .br
  686.       Display *\fIdisplay\fP\^;
  687. .br
  688.       Window \fIgrab_window\fP\^;
  689. .br
  690.       Bool \fIowner_events\fP\^;
  691. .br
  692.       int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
  693. .br
  694.       Time \fItime\fP\^;
  695. .FN
  696. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  697. .IP \fIdisplay\fP 1i
  698. Specifies the connection to the X server.
  699. .IP \fIgrab_window\fP 1i
  700. Specifies the grab window.
  701. .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
  702. .IP \fIowner_events\fP 1i
  703. Specifies a Boolean value that indicates whether the keyboard events 
  704. are to be reported as usual.
  705. .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
  706. .IP \fIpointer_mode\fP 1i
  707. Specifies further processing of pointer events.
  708. You can pass 
  709. .PN GrabModeSync 
  710. or
  711. .PN GrabModeAsync .
  712. .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
  713. .IP \fIkeyboard_mode\fP 1i
  714. Specifies further processing of keyboard events.
  715. You can pass 
  716. .PN GrabModeSync 
  717. or
  718. .PN GrabModeAsync .
  719. .IP \fItime\fP 1i
  720. Specifies the time.
  721. You can pass either a timestamp or
  722. .PN CurrentTime .
  723. .\" End marker code here
  724. .LP
  725. .\" $Header: XGrabKeybd.d,v 1.4 88/08/19 20:27:03 mento Exp $
  726. The
  727. .PN XGrabKeyboard
  728. function actively grabs control of the keyboard and generates
  729. .PN FocusIn
  730. and
  731. .PN FocusOut
  732. events.
  733. Further key events are reported only to the
  734. grabbing client.
  735. .PN XGrabKeyboard
  736. overrides any active keyboard grab by this client.
  737. If owner_events is 
  738. .PN False , 
  739. all generated key events are reported with
  740. respect to grab_window.  
  741. If owner_events is 
  742. .PN True  
  743. and if a generated
  744. key event would normally be reported to this client, it is reported
  745. normally; otherwise, the event is reported with respect to the
  746. grab_window.  
  747. Both 
  748. .PN KeyPress 
  749. and 
  750. .PN KeyRelease 
  751. events are always reported,
  752. independent of any event selection made by the client.
  753. .LP
  754. If the keyboard_mode argument is 
  755. .PN GrabModeAsync ,
  756. keyboard event processing continues
  757. as usual. 
  758. If the keyboard is currently frozen by this client, 
  759. then processing of keyboard events is resumed.
  760. If the keyboard_mode  argument is
  761. .PN GrabModeSync ,
  762. the state of the keyboard (as seen by client applications) appears to freeze,
  763. and the X server generates no further keyboard events until the
  764. grabbing client issues a releasing 
  765. .PN XAllowEvents 
  766. call or until the keyboard grab is released.
  767. Actual keyboard changes are not lost while the keyboard is frozen; 
  768. they are simply queued in the server for later processing.
  769. .LP
  770. If pointer_mode is 
  771. .PN GrabModeAsync ,
  772. pointer event processing is unaffected
  773. by activation of the grab.  
  774. If pointer_mode is 
  775. .PN GrabModeSync ,
  776. the state of the pointer (as seen by client applications) appears to freeze, 
  777. and the X server generates no further pointer events 
  778. until the grabbing client issues a releasing 
  779. .PN XAllowEvents 
  780. call or until the keyboard grab is released.
  781. Actual pointer changes are not lost while the pointer is frozen; 
  782. they are simply queued in the server for later processing.
  783. .LP
  784. If the keyboard is actively grabbed by some other client,
  785. .PN XGrabKeyboard
  786. fails and returns
  787. .PN AlreadyGrabbed .
  788. If grab_window is not viewable,
  789. it fails and returns
  790. .PN GrabNotViewable .
  791. If the keyboard is frozen by an active grab of another client,
  792. it fails and returns
  793. .PN GrabFrozen .
  794. If the specified time is earlier than the last-keyboard-grab time 
  795. or later than the current X server time,
  796. it fails and returns
  797. .PN GrabInvalidTime .
  798. Otherwise, the last-keyboard-grab time is set to the specified time
  799. .Pn ( CurrentTime 
  800. is replaced by the current X server time).
  801. .LP
  802. .PN XGrabKeyboard
  803. can generate
  804. .PN BadValue
  805. and 
  806. .PN BadWindow 
  807. errors.
  808. .LP
  809. .sp
  810. To ungrab the keyboard, use
  811. .PN XUngrabKeyboard .
  812. .IN "Keyboard" "ungrabbing"
  813. .IN "Ungrabbing" "keyboard"
  814. .IN "XUngrabKeyboard" "" "@DEF@"
  815. .\" Start marker code here
  816. .FD 0
  817. .\" $Header: XUngrabKeybd.f,v 1.1 88/02/26 10:04:05 mento Exp $
  818. XUngrabKeyboard\^(\^\fIdisplay\fP, \fItime\fP\^)
  819. .br
  820.       Display *\fIdisplay\fP\^;
  821. .br
  822.       Time \fItime\fP\^;
  823. .FN
  824. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  825. .IP \fIdisplay\fP 1i
  826. Specifies the connection to the X server.
  827. .IP \fItime\fP 1i
  828. Specifies the time.
  829. You can pass either a timestamp or
  830. .PN CurrentTime .
  831. .\" End marker code here
  832. .LP
  833. .\" $Header: XUngrabKeybd.d,v 1.2 88/06/11 07:54:22 mento Exp $
  834. The
  835. .PN XUngrabKeyboard
  836. function
  837. releases the keyboard and any queued events if this client has it actively grabbed from
  838. either
  839. .PN XGrabKeyboard
  840. or
  841. .PN XGrabKey .
  842. .PN XUngrabKeyboard
  843. does not release the keyboard and any queued events
  844. if the specified time is earlier than
  845. the last-keyboard-grab time or is later than the current X server time.
  846. It also generates
  847. .PN FocusIn 
  848. and 
  849. .PN FocusOut 
  850. events.
  851. The X server automatically performs an 
  852. .PN UngrabKeyboard 
  853. request if the event window for an
  854. active keyboard grab becomes not viewable.
  855. .LP
  856. .sp
  857. To passively grab a single key of the keyboard, use
  858. .PN XGrabKey .
  859. .IN "Key" "grabbing"
  860. .IN "Grabbing" "keys"
  861. .IN "XGrabKey" "" "@DEF@"
  862. .\" Start marker code here
  863. .FD 0
  864. .\" $Header: XGrabKey.f,v 1.1 88/02/26 10:01:04 mento Exp $
  865. XGrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIpointer_mode\fP\^, 
  866. .br
  867.              \fIkeyboard_mode\fP\^)
  868. .br
  869.       Display *\fIdisplay\fP\^;
  870. .br
  871.       int \fIkeycode\fP\^;
  872. .br
  873.       unsigned int \fImodifiers\fP\^;
  874. .br
  875.       Window \fIgrab_window\fP\^;
  876. .br
  877.       Bool \fIowner_events\fP\^;
  878. .br
  879.       int \fIpointer_mode\fP\^, \fIkeyboard_mode\fP\^;
  880. .FN
  881. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  882. .IP \fIdisplay\fP 1i
  883. Specifies the connection to the X server.
  884. .\" $Header: keycode1.a,v 1.1 88/05/14 08:09:00 mento Exp $
  885. .IP \fIkeycode\fP 1i
  886. Specifies the KeyCode or
  887. .PN AnyKey .
  888. .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
  889. .IP \fImodifiers\fP 1i
  890. Specifies the set of keymasks or
  891. .PN AnyModifier .
  892. The mask is the bitwise inclusive OR of the valid keymask bits.
  893. .IP \fIgrab_window\fP 1i
  894. Specifies the grab window.
  895. .\" $Header: ownerevents2.a,v 1.3 88/05/14 07:32:25 mento Exp $
  896. .IP \fIowner_events\fP 1i
  897. Specifies a Boolean value that indicates whether the keyboard events 
  898. are to be reported as usual.
  899. .\" $Header: pointermode.a,v 1.3 88/04/06 14:21:24 mento Exp $
  900. .IP \fIpointer_mode\fP 1i
  901. Specifies further processing of pointer events.
  902. You can pass 
  903. .PN GrabModeSync 
  904. or
  905. .PN GrabModeAsync .
  906. .\" $Header: keybdmode.a,v 1.3 88/04/06 14:22:10 mento Exp $
  907. .IP \fIkeyboard_mode\fP 1i
  908. Specifies further processing of keyboard events.
  909. You can pass 
  910. .PN GrabModeSync 
  911. or
  912. .PN GrabModeAsync .
  913. .\" End marker code here
  914. .LP
  915. .\" $Header: XGrabKey.d,v 1.4 88/08/19 20:28:57 mento Exp $
  916. The
  917. .PN XGrabKey
  918. function establishes a passive grab on the keyboard.
  919. In the future,
  920. the keyboard is actively grabbed (as for
  921. .PN XGrabKeyboard ),
  922. the last-keyboard-grab time is set to the time at which the key was pressed
  923. (as transmitted in the
  924. .PN KeyPress
  925. event), and the
  926. .PN KeyPress
  927. event is reported if all of the following conditions are true:
  928. .IP \(bu 5
  929. The keyboard is not grabbed and the specified key
  930. (which can itself be a modifier key) is logically pressed
  931. when the specified modifier keys are logically down,
  932. and no other modifier keys are logically down.
  933. .IP \(bu 5
  934. Either the grab_window is an ancestor of (or is) the focus window,
  935. or the grab_window is a descendant of the focus window and contains the pointer.
  936. .IP \(bu 5
  937. A passive grab on the same key combination does not exist
  938. on any ancestor of grab_window.
  939. .LP
  940. The interpretation of the remaining arguments is as for 
  941. .PN XGrabKeyboard .
  942. The active grab is terminated automatically when the logical state of the
  943. keyboard has the specified key released
  944. (independent of the logical state of the modifier keys).
  945. .LP
  946. Note that the logical state of a device (as seen by client applications)
  947. may lag the physical state if device event processing is frozen.
  948. .LP
  949. A modifiers argument of 
  950. .PN AnyModifier
  951. is equivalent to issuing the request for all
  952. possible modifier combinations (including the combination of no
  953. modifiers).  
  954. It is not required that all modifiers specified have
  955. currently assigned KeyCodes.
  956. A keycode argument of 
  957. .PN AnyKey
  958. is equivalent to issuing
  959. the request for all possible KeyCodes.
  960. Otherwise, the specified keycode must be in
  961. the range specified by min_keycode and max_keycode in the connection
  962. setup, 
  963. or a
  964. .PN BadValue
  965. error results.
  966. .LP
  967. If some other client has issued a 
  968. .PN XGrabKey
  969. with the same key combination on the same window, a 
  970. .PN BadAccess 
  971. error results.
  972. When using
  973. .PN AnyModifier
  974. or 
  975. .PN AnyKey ,
  976. the request fails completely,
  977. and a
  978. .PN BadAccess 
  979. error results (no grabs are established) 
  980. if there is a conflicting grab for any combination.
  981. .LP
  982. .PN XGrabKey
  983. can generate
  984. .PN BadAccess ,
  985. .PN BadValue , 
  986. and
  987. .PN BadWindow 
  988. errors.
  989. .LP
  990. .sp
  991. To ungrab a key, use
  992. .PN XUngrabKey .
  993. .IN "Key" "ungrabbing"
  994. .IN "Ungrabbing" "keys"
  995. .IN "XUngrabKey" "" "@DEF@"
  996. .\" Start marker code here
  997. .FD 0
  998. .\" $Header: XUngrabKey.f,v 1.2 88/05/14 08:28:06 mento Exp $
  999. XUngrabKey\^(\^\fIdisplay\fP, \fIkeycode\fP\^, \fImodifiers\fP\^, \fIgrab_window\fP\^)
  1000. .br
  1001.       Display *\fIdisplay\fP\^;
  1002. .br
  1003.       int \fIkeycode\fP\^;
  1004. .br
  1005.       unsigned int \fImodifiers\fP\^;
  1006. .br
  1007.       Window \fIgrab_window\fP\^;
  1008. .FN
  1009. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1010. .IP \fIdisplay\fP 1i
  1011. Specifies the connection to the X server.
  1012. .\" $Header: keycode1.a,v 1.1 88/05/14 08:09:00 mento Exp $
  1013. .IP \fIkeycode\fP 1i
  1014. Specifies the KeyCode or
  1015. .PN AnyKey .
  1016. .\" $Header: modifiers.a,v 1.4 88/05/14 07:28:56 mento Exp $
  1017. .IP \fImodifiers\fP 1i
  1018. Specifies the set of keymasks or
  1019. .PN AnyModifier .
  1020. The mask is the bitwise inclusive OR of the valid keymask bits.
  1021. .IP \fIgrab_window\fP 1i
  1022. Specifies the grab window.
  1023. .\" End marker code here
  1024. .LP
  1025. .\" $Header: XUngrabKey.d,v 1.3 88/08/19 20:29:50 mento Exp $
  1026. The
  1027. .PN XUngrabKey
  1028. function releases the key combination on the specified window if it was grabbed
  1029. by this client.
  1030. It has no effect on an active grab.
  1031. A modifiers of
  1032. .PN AnyModifier
  1033. is equivalent to issuing
  1034. the request for all possible modifier combinations
  1035. (including the combination of no modifiers).
  1036. A keycode argument of
  1037. .PN AnyKey
  1038. is equivalent to issuing the request for all possible key codes.
  1039. .LP
  1040. .PN XUngrabKey
  1041. can generate
  1042. .PN BadValue
  1043. and
  1044. .PN BadWindow 
  1045. errors.
  1046. .NH 2
  1047. Resuming Event Processing
  1048. .XS
  1049. \*(SN Resuming Event Processing
  1050. .XE
  1051. .LP
  1052. The previous sections discussed grab mechanisms with which processing
  1053. of events by the server can be temporarily suspended.  This section
  1054. describes the mechanism for resuming event processing.
  1055. .LP
  1056. .sp
  1057. To allow further events to be processed when the device has been frozen, use
  1058. .PN XAllowEvents .
  1059. .IN "XAllowEvents" "" "@DEF@"
  1060. .\" Start marker code here
  1061. .FD 0
  1062. .\" $Header: XAllowEvents.f,v 1.1 88/02/26 09:58:11 mento Exp $
  1063. XAllowEvents\^(\^\fIdisplay\fP, \fIevent_mode\fP\^, \fItime\fP\^)
  1064. .br
  1065.       Display *\fIdisplay\fP\^;
  1066. .br
  1067.       int \fIevent_mode\fP\^; 
  1068. .br
  1069.       Time \fItime\fP\^; 
  1070. .FN
  1071. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1072. .IP \fIdisplay\fP 1i
  1073. Specifies the connection to the X server.
  1074. .\" $Header: eventmode.a,v 1.2 88/04/04 11:13:37 mento Exp $
  1075. .IP \fIevent_mode\fP 1i
  1076. Specifies the event mode.
  1077. You can pass 
  1078. .PN AsyncPointer , 
  1079. .PN SyncPointer , 
  1080. .PN AsyncKeyboard , 
  1081. .PN SyncKeyboard ,
  1082. .PN ReplayPointer , 
  1083. .PN ReplayKeyboard ,
  1084. .PN AsyncBoth ,
  1085. or
  1086. .PN SyncBoth .
  1087. .IP \fItime\fP 1i
  1088. Specifies the time.
  1089. You can pass either a timestamp or
  1090. .PN CurrentTime .
  1091. .\" End marker code here
  1092. .LP
  1093. .\" $Header: XAllowEvents.d,v 1.2 88/06/11 07:48:36 mento Exp $
  1094. The
  1095. .PN XAllowEvents
  1096. function releases some queued events if the client has caused a device 
  1097. to freeze.
  1098. It has no effect if the specified time is earlier than the last-grab
  1099. time of the most recent active grab for the client or if the specified time
  1100. is later than the current X server time.
  1101. Depending on the event_mode argument, the following occurs:
  1102. .TS
  1103. lw(1.25i) lw(4.5i).
  1104. T{
  1105. .PN AsyncPointer
  1106. T}    T{
  1107. If the pointer is frozen by the client,
  1108. pointer event processing continues as usual.
  1109. If the pointer is frozen twice by the client on behalf of two separate grabs,
  1110. .PN AsyncPointer 
  1111. thaws for both.
  1112. .PN AsyncPointer
  1113. has no effect if the pointer is not frozen by the client,
  1114. but the pointer need not be grabbed by the client.
  1115. T}
  1116. .sp 6p
  1117. T{
  1118. .PN SyncPointer 
  1119. T}    T{
  1120. If the pointer is frozen and actively grabbed by the client,
  1121. pointer event processing continues as usual until the next 
  1122. .PN ButtonPress 
  1123. or 
  1124. .PN ButtonRelease 
  1125. event is reported to the client.
  1126. At this time, 
  1127. the pointer again appears to freeze.
  1128. However, if the reported event causes the pointer grab to be released,
  1129. the pointer does not freeze.
  1130. .PN SyncPointer 
  1131. has no effect if the pointer is not frozen by the client
  1132. or if the pointer is not grabbed by the client.
  1133. T}
  1134. .sp 6p
  1135. T{
  1136. .PN ReplayPointer
  1137. T}    T{
  1138. If the pointer is actively grabbed by the client and is frozen as the result of
  1139. an event having been sent to the client (either from the activation of a 
  1140. .PN XGrabButton 
  1141. or from a previous 
  1142. .PN XAllowEvents 
  1143. with mode 
  1144. .PN SyncPointer
  1145. but not from a 
  1146. .PN XGrabPointer ),
  1147. the pointer grab is released and that event is completely reprocessed.
  1148. This time, however, the function ignores any passive grabs at or above 
  1149. (towards the root of) the grab_window of the grab just released.
  1150. The request has no effect if the pointer is not grabbed by the client
  1151. or if the pointer is not frozen as the result of an event.
  1152. T}
  1153. .sp 6p
  1154. T{
  1155. .PN AsyncKeyboard 
  1156. T}    T{
  1157. If the keyboard is frozen by the client,
  1158. keyboard event processing continues as usual.
  1159. If the keyboard is frozen twice by the client on behalf of two separate grabs,
  1160. .PN AsyncKeyboard 
  1161. thaws for both.
  1162. .PN AsyncKeyboard 
  1163. has no effect if the keyboard is not frozen by the client,
  1164. but the keyboard need not be grabbed by the client.
  1165. T}
  1166. .sp 6p
  1167. T{
  1168. .PN SyncKeyboard
  1169. T}    T{
  1170. If the keyboard is frozen and actively grabbed by the client,
  1171. keyboard event processing continues as usual until the next 
  1172. .PN KeyPress 
  1173. or 
  1174. .PN KeyRelease 
  1175. event is reported to the client.
  1176. At this time,
  1177. the keyboard again appears to freeze.
  1178. However, if the reported event causes the keyboard grab to be released,
  1179. the keyboard does not freeze.
  1180. .PN SyncKeyboard 
  1181. has no effect if the keyboard is not frozen by the client
  1182. or if the keyboard is not grabbed by the client.
  1183. T}
  1184. .sp 6p
  1185. T{
  1186. .PN ReplayKeyboard
  1187. T}    T{
  1188. If the keyboard is actively grabbed by the client and is frozen 
  1189. as the result of an event having been sent to the client (either from the
  1190. activation of a 
  1191. .PN XGrabKey 
  1192. or from a previous 
  1193. .PN XAllowEvents 
  1194. with mode 
  1195. .PN SyncKeyboard 
  1196. but not from a 
  1197. .PN XGrabKeyboard ),
  1198. the keyboard grab is released and that event is completely reprocessed.
  1199. This time, however, the function ignores any passive grabs at or above 
  1200. (towards the root of)
  1201. the grab_window of the grab just released.
  1202. The request has no effect if the keyboard is not grabbed by the client
  1203. or if the keyboard is not frozen as the result of an event.
  1204. T}
  1205. .sp 6p
  1206. T{
  1207. .PN SyncBoth
  1208. T}    T{
  1209. If both pointer and keyboard are frozen by the client,
  1210. event processing for both devices continues as usual until the next
  1211. .PN ButtonPress , 
  1212. .PN ButtonRelease , 
  1213. .PN KeyPress , 
  1214. or 
  1215. .PN KeyRelease 
  1216. event is reported to the client for a grabbed device 
  1217. (button event for the pointer, key event for the keyboard), 
  1218. at which time the devices again appear to freeze.  
  1219. However, if the reported event causes the grab to be released,
  1220. then the devices do not freeze (but if the other device is still
  1221. grabbed, then a subsequent event for it will still cause both devices
  1222. to freeze).  
  1223. .PN SyncBoth
  1224. has no effect unless both pointer and keyboard
  1225. are frozen by the client.
  1226. If the pointer or keyboard is frozen twice
  1227. by the client on behalf of two separate grabs, 
  1228. .PN SyncBoth 
  1229. thaws for both (but a subsequent freeze for 
  1230. .PN SyncBoth 
  1231. will only freeze each device once).
  1232. T}
  1233. .sp 6p
  1234. T{
  1235. .PN AsyncBoth
  1236. T}    T{
  1237. If the pointer and the keyboard are frozen by the
  1238. client, event processing for both devices continues as usual.
  1239. If a device is frozen twice by the client on behalf of two separate grabs,
  1240. .PN AsyncBoth 
  1241. thaws for both.
  1242. .PN AsyncBoth 
  1243. has no effect unless both
  1244. pointer and keyboard are frozen by the client.
  1245. T}
  1246. .TE
  1247. .LP
  1248. .PN AsyncPointer , 
  1249. .PN SyncPointer , 
  1250. and 
  1251. .PN ReplayPointer 
  1252. have no effect on the
  1253. processing of keyboard events.
  1254. .PN AsyncKeyboard , 
  1255. .PN SyncKeyboard , 
  1256. and 
  1257. .PN ReplayKeyboard 
  1258. have no effect on the
  1259. processing of pointer events.
  1260. It is possible for both a pointer grab and a keyboard grab (by the same 
  1261. or different clients) to be active simultaneously.
  1262. If a device is frozen on behalf of either grab,
  1263. no event processing is performed for the device.
  1264. It is possible for a single device to be frozen because of both grabs.
  1265. In this case,
  1266. the freeze must be released on behalf of both grabs before events can 
  1267. again be processed.
  1268. If a device is frozen twice by a single client,
  1269. then a single
  1270. .PN AllowEvents
  1271. releases both.
  1272. .LP
  1273. .PN XAllowEvents
  1274. can generate a
  1275. .PN BadValue 
  1276. error.
  1277. .NH 2
  1278. Moving the Pointer
  1279. .XS
  1280. \*(SN Moving the Pointer
  1281. .XE
  1282. .LP
  1283. Although movement of the pointer normally should be left to the
  1284. control of the end user, sometimes it is necessary to move the
  1285. pointer to a new position under program control.
  1286. .LP
  1287. .sp
  1288. To move the pointer to an arbitrary point in a window, use
  1289. .PN XWarpPointer .
  1290. .IN "XWarpPointer" "" "@DEF@"
  1291. .\" Start marker code here
  1292. .FD 0
  1293. .\" $Header: XWarpPointer.f,v 1.1 88/02/26 10:04:13 mento Exp $
  1294. .\" $Header: XWarpPointer.f,v 1.1 88/02/26 10:04:13 mento Exp $
  1295. XWarpPointer\^(\^\fIdisplay\fP, \fIsrc_w\fP\^, \fIdest_w\fP\^, \fIsrc_x\fP\^, \fIsrc_y\fP\^, \fIsrc_width\fP\^, \fIsrc_height\fP\^, \fIdest_x\fP\^, 
  1296. .br
  1297.                 \fIdest_y\fP\^)
  1298. .br
  1299.         Display *\fIdisplay\fP\^;
  1300. .br
  1301.         Window \fIsrc_w\fP\^, \fIdest_w\fP\^;
  1302. .br
  1303.         int \fIsrc_x\fP\^, \fIsrc_y\fP\^;
  1304. .br
  1305.         unsigned int \fIsrc_width\fP\^, \fIsrc_height\fP\^;
  1306. .br
  1307.         int \fIdest_x\fP\^, \fIdest_y\fP\^;
  1308. .FN
  1309. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1310. .IP \fIdisplay\fP 1i
  1311. Specifies the connection to the X server.
  1312. .\" $Header: sw1.a,v 1.1 88/05/14 08:43:03 mento Exp $
  1313. .IP \fIsrc_w\fP 1i
  1314. Specifies the source window or
  1315. .PN None .
  1316. .\" $Header: dw1.a,v 1.1 88/05/14 08:44:37 mento Exp $
  1317. .IP \fIdest_w\fP 1i
  1318. Specifies the destination window or
  1319. .PN None .
  1320. .\" $Header: srcwdht.a,v 1.2 88/04/28 06:03:00 mento Exp $
  1321. .IP \fIsrc_x\fP 1i
  1322. .br
  1323. .ns
  1324. .IP \fIsrc_y\fP 1i
  1325. .br
  1326. .ns
  1327. .IP \fIsrc_width\fP 1i
  1328. .br
  1329. .ns
  1330. .IP \fIsrc_height\fP 1i
  1331. Specify a rectangle in the source window.
  1332. .\" $Header: destxy2.a,v 1.1 88/02/26 10:06:50 mento Exp $
  1333. .IP \fIdest_x\fP 1i
  1334. .br
  1335. .ns
  1336. .IP \fIdest_y\fP 1i
  1337. Specify the x and y coordinates within the destination window.
  1338. .\" End marker code here
  1339. .LP
  1340. .\" $Header: XWarpPointer.d,v 1.3 88/06/11 07:54:36 mento Exp $
  1341. If dest_w is
  1342. .PN None ,
  1343. .PN XWarpPointer
  1344. moves the pointer by the offsets (dest_x, dest_y) relative to the current
  1345. position of the pointer.
  1346. If dest_w is a window,
  1347. .PN XWarpPointer
  1348. moves the pointer to the offsets (dest_x, dest_y) relative to the origin of
  1349. dest_w.
  1350. However, if src_w is a window,
  1351. the move only takes place if the window src_w contains the pointer 
  1352. and if the specified rectangle of src_w contains the pointer.
  1353. .LP
  1354. The src_x and src_y coordinates are relative to the origin of src_w.
  1355. If src_height is zero,
  1356. it is replaced with the current height of src_w minus src_y.
  1357. If src_width is zero,
  1358. it is replaced with the current width of src_w minus src_x.
  1359. .LP
  1360. There is seldom any reason for calling this function. 
  1361. The pointer should normally be left to the user.
  1362. If you do use this function, however, it generates events just as if the user
  1363. had instantaneously moved the pointer from one position to another.
  1364. Note that you cannot use
  1365. .PN XWarpPointer
  1366. to move the pointer outside the confine_to window of an active pointer grab.
  1367. An attempt to do so will only move the pointer as far as the closest edge of the
  1368. confine_to window. 
  1369. .LP
  1370. .PN XWarpPointer
  1371. can generate a
  1372. .PN BadWindow 
  1373. error.
  1374. .NH 2
  1375. Controlling Input Focus
  1376. .XS
  1377. \*(SN Controlling Input Focus 
  1378. .XE
  1379. .LP
  1380. Xlib provides functions that you can use to set and get the input focus.
  1381. The input focus is a shared resource, and cooperation among clients is
  1382. required for correct interaction.  See the
  1383. \fIInter-Client Communication Conventions Manual\fP 
  1384. for input focus policy.
  1385. .LP
  1386. .sp
  1387. To set the input focus, use
  1388. .PN XSetInputFocus .
  1389. .IN "XSetInputFocus" "" "@DEF@"
  1390. .\" Start marker code here
  1391. .FD 0
  1392. .\" $Header: XSetInFocus.f,v 1.1 88/02/26 10:03:18 mento Exp $
  1393. XSetInputFocus\^(\^\fIdisplay\fP, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^)
  1394. .br
  1395.       Display *\fIdisplay\fP\^;
  1396. .br
  1397.       Window \fIfocus\fP\^;
  1398. .br
  1399.       int \fIrevert_to\fP\^; 
  1400. .br
  1401.       Time \fItime\fP\^; 
  1402. .FN
  1403. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1404. .IP \fIdisplay\fP 1i
  1405. Specifies the connection to the X server.
  1406. .IP \fIfocus\fP 1i
  1407. Specifies the window,
  1408. .PN PointerRoot ,
  1409. or
  1410. .PN None .
  1411. .\" $Header: revertto.a,v 1.4 88/08/19 20:33:14 mento Exp $
  1412. .IP \fIrevert_to\fP 1i
  1413. Specifies where the input focus reverts to if the window becomes not
  1414. viewable.
  1415. You can pass 
  1416. .PN RevertToParent , 
  1417. .PN RevertToPointerRoot , 
  1418. or 
  1419. .PN RevertToNone .
  1420. .IP \fItime\fP 1i
  1421. Specifies the time.
  1422. You can pass either a timestamp or
  1423. .PN CurrentTime .
  1424. .\" End marker code here
  1425. .LP
  1426. .\" $Header: XSetInFocus.d,v 1.2 88/06/11 07:53:17 mento Exp $
  1427. The
  1428. .PN XSetInputFocus
  1429. function changes the input focus and the last-focus-change time.
  1430. It has no effect if the specified time is earlier than the current
  1431. last-focus-change time or is later than the current X server time.
  1432. Otherwise, the last-focus-change time is set to the specified time
  1433. .Pn ( CurrentTime 
  1434. is replaced by the current X server time).
  1435. .PN XSetInputFocus
  1436. causes the X server to generate
  1437. .PN FocusIn 
  1438. and 
  1439. .PN FocusOut 
  1440. events.
  1441. .LP
  1442. Depending on the focus argument,
  1443. the following occurs: 
  1444. .IP \(bu 5
  1445. If focus is
  1446. .PN None ,
  1447. all keyboard events are discarded until a new focus window is set,
  1448. and the revert_to argument is ignored.
  1449. .IP \(bu 5
  1450. If focus is a window, 
  1451. it becomes the keyboard's focus window.
  1452. If a generated keyboard event would normally be reported to this window
  1453. or one of its inferiors, the event is reported as usual. 
  1454. Otherwise, the event is reported relative to the focus window.
  1455. .IP \(bu 5
  1456. If focus is
  1457. .PN PointerRoot ,
  1458. the focus window is dynamically taken to be the root window of whatever screen 
  1459. the pointer is on at each keyboard event.  
  1460. In this case, the revert_to argument is ignored.
  1461. .LP
  1462. The specified focus window must be viewable at the time 
  1463. .PN XSetInputFocus
  1464. is called,
  1465. or a
  1466. .PN BadMatch
  1467. error results.
  1468. If the focus window later becomes not viewable, 
  1469. the X server
  1470. evaluates the revert_to argument to determine the new focus window as follows: 
  1471. .IP \(bu 5
  1472. If revert_to is
  1473. .PN RevertToParent ,
  1474. the focus reverts to the parent (or the closest viewable ancestor), 
  1475. and the new revert_to value is taken to be
  1476. .PN RevertToNone .  
  1477. .IP \(bu 5
  1478. If revert_to is
  1479. .PN RevertToPointerRoot 
  1480. or 
  1481. .PN RevertToNone ,
  1482. the focus reverts to
  1483. .PN PointerRoot
  1484. or
  1485. .PN None ,
  1486. respectively.
  1487. When the focus reverts,
  1488. the X server generates
  1489. .PN FocusIn
  1490. and
  1491. .PN FocusOut
  1492. events, but the last-focus-change time is not affected.
  1493. .LP
  1494. .PN XSetInputFocus
  1495. can generate
  1496. .PN BadMatch ,
  1497. .PN BadValue ,
  1498. and
  1499. .PN BadWindow 
  1500. errors.
  1501. .LP
  1502. .sp
  1503. To obtain the current input focus, use
  1504. .PN XGetInputFocus .
  1505. .IN "XGetInputFocus" "" "@DEF@"
  1506. .\" Start marker code here
  1507. .FD 0
  1508. .\" $Header: XGetInFocus.f,v 1.1 88/02/26 10:00:48 mento Exp $
  1509. XGetInputFocus\^(\^\fIdisplay\fP, \fIfocus_return\fP\^, \fIrevert_to_return\fP\^)
  1510. .br
  1511.       Display *\fIdisplay\fP\^;
  1512. .br
  1513.       Window *\fIfocus_return\fP\^;
  1514. .br
  1515.       int *\fIrevert_to_return\fP\^;
  1516. .FN
  1517. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1518. .IP \fIdisplay\fP 1i
  1519. Specifies the connection to the X server.
  1520. .\" $Header: focus.a,v 1.2 88/05/14 08:56:12 mento Exp $
  1521. .IP \fIfocus_return\fP 1i
  1522. Returns the focus window,
  1523. .PN PointerRoot ,
  1524. or 
  1525. .PN None .
  1526. .\" $Header: reverttoret.a,v 1.3 88/05/14 08:57:31 mento Exp $
  1527. .IP \fIrevert_to_return\fP 1i
  1528. Returns the current focus state
  1529. .Pn ( RevertToParent , 
  1530. .PN RevertToPointerRoot , 
  1531. or 
  1532. .PN RevertToNone ).
  1533. .\" End marker code here
  1534. .LP
  1535. .\" $Header: XGetInFocus.d,v 1.2 88/05/14 08:58:23 mento Exp $
  1536. The
  1537. .PN XGetInputFocus
  1538. function returns the focus window and the current focus state.
  1539. .NH 2
  1540. Keyboard and Pointer Settings
  1541. .XS
  1542. \*(SN Keyboard and Pointer Settings 
  1543. .XE
  1544. .LP
  1545. Xlib provides functions that you can use to
  1546. change the keyboard control, obtain a list of the auto-repeat keys,
  1547. turn keyboard auto-repeat on or off, ring the bell, 
  1548. set or obtain the pointer button or keyboard mapping, 
  1549. and obtain a bit vector for the keyboard.
  1550. .LP
  1551. .IN "Keyboard" "bell volume"
  1552. .IN "Keyboard" "keyclick volume"
  1553. .IN "Keyboard" "bit vector"
  1554. .IN "Mouse" "programming"
  1555. This section discusses 
  1556. the user-preference options of bell, key click,
  1557. pointer behavior, and so on.
  1558. The default values for many of these functions are determined by
  1559. command line arguments to the X server and, on POSIX-conformant systems, 
  1560. are typically set in the 
  1561. .PN /etc/ttys 
  1562. file.
  1563. .IN "Files" "/etc/ttys"
  1564. Not all implementations will actually be able to control all of these
  1565. parameters.
  1566. .LP
  1567. The
  1568. .PN XChangeKeyboardControl
  1569. function changes control of a keyboard and operates on a
  1570. .PN XKeyboardControl
  1571. structure:
  1572. .\" Start marker code here
  1573. .LP
  1574. /* Mask bits for ChangeKeyboardControl */
  1575. .TS
  1576. lw(.5i) lw(2.5i) lw(.8i).
  1577. T{
  1578. #define
  1579. T}    T{
  1580. .PN KBKeyClickPercent
  1581. T}    T{
  1582. (1L<<0)
  1583. T}
  1584. T{
  1585. #define
  1586. T}    T{
  1587. .PN KBBellPercent
  1588. T}    T{
  1589. (1L<<1)
  1590. T}
  1591. T{
  1592. #define
  1593. T}    T{
  1594. .PN KBBellPitch
  1595. T}    T{
  1596. (1L<<2)
  1597. T}
  1598. T{
  1599. #define
  1600. T}    T{
  1601. .PN KBBellDuration
  1602. T}    T{
  1603. (1L<<3)
  1604. T}
  1605. T{
  1606. #define
  1607. T}    T{
  1608. .PN KBLed
  1609. T}    T{
  1610. (1L<<4)
  1611. T}
  1612. T{
  1613. #define
  1614. T}    T{
  1615. .PN KBLedMode
  1616. T}    T{
  1617. (1L<<5)
  1618. T}
  1619. T{
  1620. #define
  1621. T}    T{
  1622. .PN KBKey
  1623. T}    T{
  1624. (1L<<6)
  1625. T}
  1626. T{
  1627. #define
  1628. T}    T{
  1629. .PN KBAutoRepeatMode
  1630. T}    T{
  1631. (1L<<7)
  1632. T}
  1633. .TE
  1634. .IN "XKeyboardControl" "" "@DEF@"
  1635. .Ds 0
  1636. .TA .5i 2.5i
  1637. .ta .5i 2.5i
  1638. /* Values */
  1639.  
  1640. typedef struct {
  1641.     int key_click_percent;
  1642.     int bell_percent;
  1643.     int bell_pitch;
  1644.     int bell_duration;
  1645.     int led;
  1646.     int led_mode;    /* LedModeOn, LedModeOff */
  1647.     int key;
  1648.     int auto_repeat_mode;    /* AutoRepeatModeOff, AutoRepeatModeOn, 
  1649.                                 AutoRepeatModeDefault */
  1650. } XKeyboardControl;
  1651. .De
  1652. .\" End marker code here
  1653. .LP
  1654. The key_click_percent member sets the volume for key clicks between 0 (off) 
  1655. and 100 (loud) inclusive, if possible.  
  1656. A setting of \-1 restores the default.
  1657. Other negative values generate a
  1658. .PN BadValue
  1659. error.
  1660. .LP
  1661. The bell_percent sets the base volume for the bell between 0 (off) and 100
  1662. (loud) inclusive, if possible.  
  1663. A setting of \-1 restores the default.
  1664. Other negative values generate a
  1665. .PN BadValue
  1666. error.
  1667. The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible.
  1668. A setting of \-1 restores the default.
  1669. Other negative values generate a
  1670. .PN BadValue
  1671. error.
  1672. The bell_duration member sets the duration of the
  1673. bell specified in milliseconds, if possible.  
  1674. A setting of \-1 restores the default.
  1675. Other negative values generate a
  1676. .PN BadValue
  1677. error.
  1678. .LP
  1679. If both the led_mode and led members are specified,
  1680. the state of that LED is changed, if possible.  
  1681. The led_mode member can be set to
  1682. .PN LedModeOn
  1683. or
  1684. .PN LedModeOff .
  1685. If only led_mode is specified, the state of
  1686. all LEDs are changed, if possible.  
  1687. At most 32 LEDs numbered from one are supported. 
  1688. No standard interpretation of LEDs is defined.
  1689. If led is specified without led_mode, a
  1690. .PN BadMatch
  1691. error results. 
  1692. .LP
  1693. If both the auto_repeat_mode and key members are specified, 
  1694. the auto_repeat_mode of that key is changed (according to
  1695. .PN AutoRepeatModeOn ,
  1696. .PN AutoRepeatModeOff ,
  1697. or
  1698. .PN AutoRepeatModeDefault ),
  1699. if possible.
  1700. If only auto_repeat_mode is
  1701. specified, the global auto_repeat_mode for the entire keyboard is
  1702. changed, if possible, and does not affect the per key settings.
  1703. If a key is specified without an auto_repeat_mode, a
  1704. .PN BadMatch
  1705. error results.
  1706. Each key has an individual mode of whether or not it should auto-repeat
  1707. and a default setting for the mode.
  1708. In addition,
  1709. there is a global mode of whether auto-repeat should be enabled or not
  1710. and a default setting for that mode.
  1711. When global mode is
  1712. .PN AutoRepeatModeOn ,
  1713. keys should obey their individual auto-repeat modes.
  1714. When global mode is
  1715. .PN AutoRepeatModeOff ,
  1716. no keys should auto-repeat.
  1717. An auto-repeating key generates alternating
  1718. .PN KeyPress
  1719. and
  1720. .PN KeyRelease
  1721. events.
  1722. When a key is used as a modifier,
  1723. it is desirable for the key not to auto-repeat,
  1724. regardless of its auto-repeat setting.
  1725. .LP
  1726. A bell generator connected with the console but not directly on a
  1727. keyboard is treated as if it were part of the keyboard.
  1728. The order in which controls are verified and altered is server-dependent.
  1729. If an error is generated, a subset of the controls may have been altered.
  1730. .LP
  1731. .sp
  1732. .IN "XChangeKeyboardControl" "" "@DEF@"
  1733. .\" Start marker code here
  1734. .FD 0
  1735. .\" $Header: XChKeyCon.f,v 1.1 88/02/26 09:58:32 mento Exp $
  1736. XChangeKeyboardControl\^(\^\fIdisplay\fP, \fIvalue_mask\fP\^, \fIvalues\fP\^)
  1737. .br
  1738.       Display *\fIdisplay\fP\^;
  1739. .br
  1740.       unsigned long \fIvalue_mask\fP\^;
  1741. .br
  1742.       XKeyboardControl *\fIvalues\fP\^;
  1743. .FN
  1744. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1745. .IP \fIdisplay\fP 1i
  1746. Specifies the connection to the X server.
  1747. .\" $Header: value_mask1.a,v 1.3 88/04/28 06:04:45 mento Exp $
  1748. .IP \fIvalue_mask\fP 1i
  1749. Specifies which controls to change.
  1750. This mask is the bitwise inclusive OR of the valid control mask bits.
  1751. .\" $Header: values2.a,v 1.2 88/04/06 17:16:22 mento Exp $
  1752. .IP \fIvalues\fP 1i
  1753. Specifies one value for each bit set to 1 in the mask.
  1754. .\" End marker code here
  1755. .LP
  1756. .\" $Header: XChKeyCon.d,v 1.2 88/05/16 10:04:53 mento Exp $
  1757. The
  1758. .PN XChangeKeyboardControl
  1759. function controls the keyboard characteristics defined by the
  1760. .PN XKeyboardControl
  1761. structure.
  1762. The value_mask argument specifies which values are to be changed.
  1763. .LP
  1764. .PN XChangeKeyboardControl
  1765. can generate
  1766. .PN BadMatch
  1767. and
  1768. .PN BadValue 
  1769. errors.
  1770. .LP
  1771. .sp
  1772. To obtain the current control values for the keyboard, use
  1773. .PN XGetKeyboardControl .
  1774. .IN "XGetKeyboardControl" "" "@DEF@"
  1775. .\" Start marker code here
  1776. .FD 0
  1777. .\" $Header: XGetKeybdCnt.f,v 1.1 88/02/26 10:00:50 mento Exp $
  1778. XGetKeyboardControl\^(\^\fIdisplay\fP, \fIvalues_return\fP\^)
  1779. .br
  1780.       Display *\fIdisplay\fP\^;
  1781. .br
  1782.       XKeyboardState *\fIvalues_return\fP\^;
  1783. .FN
  1784. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1785. .IP \fIdisplay\fP 1i
  1786. Specifies the connection to the X server.
  1787. .\" $Header: values3.a,v 1.2 88/04/06 17:19:04 mento Exp $
  1788. .IP \fIvalues_return\fP 1i
  1789. Returns the current keyboard controls in the specified
  1790. .PN XKeyboardState 
  1791. structure.
  1792. .\" End marker code here
  1793. .LP
  1794. .\" $Header: XGetKeybdCnt.d,v 1.1 88/02/26 10:48:27 mento Exp $
  1795. The
  1796. .PN XGetKeyboardControl
  1797. function returns the current control values for the keyboard to the
  1798. .PN XKeyboardState
  1799. structure.
  1800. .LP
  1801. .IN "XGetKeyboardControl"
  1802. .IN "XKeyboardState" "" "@DEF@"
  1803. .\" Start marker code here
  1804. .Ds 0
  1805. .TA .5i 
  1806. .ta .5i
  1807. typedef struct {
  1808.     int key_click_percent;
  1809.     int bell_percent;
  1810.     unsigned int bell_pitch, bell_duration;
  1811.     unsigned long led_mask;
  1812.     int global_auto_repeat;
  1813.     char auto_repeats[32];
  1814. } XKeyboardState;
  1815. .De
  1816. .\" End marker code here
  1817. .LP
  1818. For the LEDs, 
  1819. the least-significant bit of led_mask corresponds to LED one,
  1820. and each bit set to 1 in led_mask indicates an LED that is lit.
  1821. The global_auto_repeat member can be set to
  1822. .PN AutoRepeatModeOn
  1823. or
  1824. .PN AutoRepeatModeOff .
  1825. The auto_repeats member is a bit vector.
  1826. Each bit set to 1 indicates that auto-repeat is enabled 
  1827. for the corresponding key.
  1828. The vector is represented as 32 bytes.  
  1829. Byte N (from 0) contains the bits for keys 8N to 8N + 7
  1830. with the least-significant bit in the byte representing key 8N.
  1831. .LP
  1832. .sp
  1833. To turn on keyboard auto-repeat, use
  1834. .PN XAutoRepeatOn .
  1835. .IN "XAutoRepeatOn" "" "@DEF@"
  1836. .\" Start marker code here
  1837. .FD 0
  1838. .\" $Header: XAutoReptOn.f,v 1.1 88/02/26 09:58:16 mento Exp $
  1839. XAutoRepeatOn\^(\^\fIdisplay\fP\^)
  1840. .br
  1841.       Display *\fIdisplay\fP\^;
  1842. .FN
  1843. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1844. .IP \fIdisplay\fP 1i
  1845. Specifies the connection to the X server.
  1846. .\" End marker code here
  1847. .LP
  1848. .\" $Header: XAutoReptOn.d,v 1.1 88/02/26 10:41:06 mento Exp $
  1849. The
  1850. .PN XAutoRepeatOn
  1851. function turns on auto-repeat for the keyboard on the specified display.
  1852. .LP
  1853. .sp
  1854. To turn off keyboard auto-repeat, use
  1855. .PN XAutoRepeatOff .
  1856. .IN "XAutoRepeatOff" "" "@DEF@"
  1857. .\" Start marker code here
  1858. .FD 0
  1859. .\" $Header: XAutoReptOff.f,v 1.1 88/02/26 09:58:13 mento Exp $
  1860. XAutoRepeatOff\^(\^\fIdisplay\fP\^)
  1861. .br
  1862.       Display *\fIdisplay\fP\^;
  1863. .FN
  1864. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1865. .IP \fIdisplay\fP 1i
  1866. Specifies the connection to the X server.
  1867. .\" End marker code here
  1868. .LP
  1869. .\" $Header: XAutoReptOff.d,v 1.1 88/02/26 10:41:05 mento Exp $
  1870. The
  1871. .PN XAutoRepeatOff
  1872. function turns off auto-repeat for the keyboard on the specified display.
  1873. .LP
  1874. .sp
  1875. To ring the bell, use
  1876. .PN XBell .
  1877. .IN "XBell" "" "@DEF@"
  1878. .\" Start marker code here
  1879. .FD 0
  1880. .\" $Header: XBell.f,v 1.1 88/02/26 09:58:18 mento Exp $
  1881. XBell\^(\^\fIdisplay\fP, \fIpercent\fP\^)
  1882. .br
  1883.       Display *\fIdisplay\fP\^;
  1884. .br
  1885.       int \fIpercent\fP\^;
  1886. .FN
  1887. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1888. .IP \fIdisplay\fP 1i
  1889. Specifies the connection to the X server.
  1890. .\" $Header: percent.a,v 1.2 88/04/06 17:20:22 mento Exp $
  1891. .IP \fIpercent\fP 1i
  1892. Specifies the volume for the bell,
  1893. which can range from \-100 to 100 inclusive. 
  1894. .\" End marker code here
  1895. .LP
  1896. .\" $Header: XBell.d,v 1.2 88/06/11 07:48:47 mento Exp $
  1897. The
  1898. .PN XBell
  1899. function rings the bell on the keyboard on the specified display, if possible.
  1900. The specified volume is relative to the base volume for the keyboard.
  1901. If the value for the percent argument is not in the range \-100 to 100
  1902. inclusive, a
  1903. .PN BadValue
  1904. error results.
  1905. The volume at which the bell rings
  1906. when the percent argument is nonnegative is:
  1907. .IP
  1908. base \- [(base * percent) / 100] + percent
  1909. .LP
  1910. The volume at which the bell rings
  1911. when the percent argument is negative is:
  1912. .IP
  1913. base + [(base * percent) / 100]
  1914. .LP
  1915. To change the base volume of the bell, use
  1916. .PN XChangeKeyboardControl .
  1917. .LP
  1918. .PN XBell
  1919. can generate a
  1920. .PN BadValue 
  1921. error.
  1922. .LP
  1923. .sp
  1924. To obtain a bit vector that describes the state of the keyboard, use
  1925. .PN XQueryKeymap .
  1926. .IN "XQueryKeymap" "" "@DEF@"
  1927. .\" Start marker code here
  1928. .FD 0
  1929. .\" $Header: XQueryKeybd.f,v 1.1 88/02/26 10:02:17 mento Exp $
  1930. XQueryKeymap\^(\^\fIdisplay\fP, \fIkeys_return\fP\^)
  1931. .br
  1932.       Display *\fIdisplay\fP\^;
  1933. .br
  1934.       char \fIkeys_return\fP[32]\^;
  1935. .FN
  1936. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1937. .IP \fIdisplay\fP 1i
  1938. Specifies the connection to the X server.
  1939. .\" $Header: keys.a,v 1.1 88/02/26 10:28:26 mento Exp $
  1940. .IP \fIkeys_return\fP 1i
  1941. Returns an array of bytes that identifies which keys are pressed down.
  1942. Each bit represents one key of the keyboard.
  1943. .\" End marker code here
  1944. .LP
  1945. .\" $Header: XQueryKeybd.d,v 1.3 88/06/11 07:52:42 mento Exp $
  1946. The
  1947. .PN XQueryKeymap
  1948. function returns a bit vector for the logical state of the keyboard, 
  1949. where each bit set to 1 indicates that the corresponding key is currently 
  1950. pressed down.
  1951. The vector is represented as 32 bytes.
  1952. Byte N (from 0) contains the bits for keys 8N to 8N + 7 
  1953. with the least-significant bit in the byte representing key 8N.
  1954. .LP
  1955. Note that the logical state of a device (as seen by client applications)
  1956. may lag the physical state if device event processing is frozen.
  1957. .LP
  1958. .sp
  1959. To set the mapping of the pointer buttons, use
  1960. .PN XSetPointerMapping .
  1961. .IN "XSetPointerMapping" "" "@DEF@"
  1962. .\" Start marker code here
  1963. .FD 0
  1964. int XSetPointerMapping\^(\^\fIdisplay\fP, \fImap\fP, \fInmap\fP\^)
  1965. .br
  1966.       Display *\fIdisplay\fP\^;
  1967. .br
  1968.       unsigned char \fImap\fP\^[]\^;
  1969. .br
  1970.       int \fInmap\fP\^;
  1971. .FN
  1972. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  1973. .IP \fIdisplay\fP 1i
  1974. Specifies the connection to the X server.
  1975. .IP \fImap\fP 1i
  1976. Specifies the mapping list.
  1977. .IP \fInmap\fP 1i
  1978. Specifies the number of items in the mapping list.
  1979. .\" End marker code here
  1980. .LP
  1981. .\" $Header: XSetPMap.d,v 1.3 88/06/11 07:53:27 mento Exp $
  1982. The
  1983. .PN XSetPointerMapping
  1984. function sets the mapping of the pointer.
  1985. If it succeeds, the X server generates a
  1986. .PN MappingNotify
  1987. event, and
  1988. .PN XSetPointerMapping
  1989. returns
  1990. .PN MappingSuccess .
  1991. Element map[i] defines the logical button number for the physical button
  1992. i+1.
  1993. The length of the list must be the same as
  1994. .PN XGetPointerMapping
  1995. would return,
  1996. or a
  1997. .PN BadValue
  1998. error results.
  1999. A zero element disables a button, and elements are not restricted in
  2000. value by the number of physical buttons.
  2001. However, no two elements can have the same nonzero value,
  2002. or a
  2003. .PN BadValue
  2004. error results.
  2005. If any of the buttons to be altered are logically in the down state,
  2006. .PN XSetPointerMapping
  2007. returns
  2008. .PN MappingBusy ,
  2009. and the mapping is not changed.
  2010. .LP
  2011. .PN XSetPointerMapping
  2012. can generate a
  2013. .PN BadValue 
  2014. error.
  2015. .LP
  2016. .sp
  2017. To get the pointer mapping, use
  2018. .PN XGetPointerMapping .
  2019. .IN "XGetPointerMapping" "" "@DEF@"
  2020. .\" Start marker code here
  2021. .FD 0
  2022. int XGetPointerMapping\^(\^\fIdisplay\fP, \fImap_return\fP, \fInmap\fP\^)
  2023. .br
  2024.       Display *\fIdisplay\fP\^;
  2025. .br
  2026.       unsigned char \fImap_return\fP\^[]\^;
  2027. .br
  2028.       int \fInmap\fP\^;
  2029. .FN
  2030. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2031. .IP \fIdisplay\fP 1i
  2032. Specifies the connection to the X server.
  2033. .IP \fImap_return\fP 1i
  2034. Returns the mapping list.
  2035. .IP \fInmap\fP 1i
  2036. Specifies the number of items in the mapping list.
  2037. .\" End marker code here
  2038. .LP
  2039. .\" $Header: XGetPMap.d,v 1.2 88/06/11 07:51:13 mento Exp $
  2040. The
  2041. .PN XGetPointerMapping
  2042. function returns the current mapping of the pointer.
  2043. Pointer buttons are numbered starting from one.
  2044. .PN XGetPointerMapping
  2045. returns the number of physical buttons actually on the pointer.
  2046. The nominal mapping for a pointer is map[i]=i+1.
  2047. The nmap argument specifies the length of the array where the pointer
  2048. mapping is returned, and only the first nmap elements are returned 
  2049. in map_return.
  2050. .LP
  2051. .sp
  2052. To control the pointer's interactive feel, use
  2053. .PN XChangePointerControl .
  2054. .IN "XChangePointerControl" "" "@DEF@"
  2055. .\" Start marker code here
  2056. .FD 0
  2057. .\" $Header: XChPointCon.f,v 1.1 88/02/26 09:58:33 mento Exp $
  2058. XChangePointerControl\^(\^\fIdisplay\fP, \fIdo_accel\fP\^, \fIdo_threshold\fP\^, \fIaccel_numerator\fP\^, 
  2059. .br
  2060.                         \fIaccel_denominator\fP\^, \fIthreshold\fP\^)
  2061. .br
  2062.       Display *\fIdisplay\fP\^;
  2063. .br
  2064.       Bool \fIdo_accel\fP\^, \fIdo_threshold\fP\^;
  2065. .br
  2066.       int \fIaccel_numerator\fP\^, \fIaccel_denominator\fP\^;
  2067. .br
  2068.       int \fIthreshold\fP\^;
  2069. .FN
  2070. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2071. .IP \fIdisplay\fP 1i
  2072. Specifies the connection to the X server.
  2073. .\" $Header: doaccel.a,v 1.4 88/05/14 09:22:57 mento Exp $
  2074. .IP \fIdo_accel\fP 1i
  2075. Specifies a Boolean value that controls whether the values for 
  2076. the accel_numerator or accel_denominator are used.
  2077. .\" $Header: dothreshold.a,v 1.5 88/05/14 09:24:07 mento Exp $
  2078. .IP \fIdo_threshold\fP 1i
  2079. Specifies a Boolean value that controls whether the value for the 
  2080. threshold is used.
  2081. .\" $Header: accelnum.a,v 1.1 88/02/26 10:04:44 mento Exp $
  2082. .IP \fIaccel_numerator\fP 1i
  2083. Specifies the numerator for the acceleration multiplier.
  2084. .\" $Header: acceldenom.a,v 1.1 88/02/26 10:04:37 mento Exp $
  2085. .IP \fIaccel_denominator\fP 1i
  2086. Specifies the denominator for the acceleration multiplier.
  2087. .\" $Header: threshold.a,v 1.1 88/02/26 10:31:38 mento Exp $
  2088. .IP \fIthreshold\fP 1i
  2089. Specifies the acceleration threshold.
  2090. .\" End marker code here
  2091. .LP
  2092. .\" $Header: XChPointCon.d,v 1.2 88/06/11 07:49:03 mento Exp $
  2093. The
  2094. .PN XChangePointerControl
  2095. function defines how the pointing device moves.
  2096. The acceleration, expressed as a fraction, is a
  2097. multiplier for movement. 
  2098. For example,
  2099. specifying 3/1 means the pointer moves three times as fast as normal.
  2100. The fraction may be rounded arbitrarily by the X server.  
  2101. Acceleration
  2102. only takes effect if the pointer moves more than threshold pixels at
  2103. once and only applies to the amount beyond the value in the threshold argument.
  2104. Setting a value to \-1 restores the default.
  2105. The values of the do_accel and do_threshold arguments must be 
  2106. .PN True 
  2107. for the pointer values to be set,
  2108. or the parameters are unchanged.
  2109. Negative values (other than \-1) generate a
  2110. .PN BadValue
  2111. error, as does a zero value
  2112. for the accel_denominator argument.
  2113. .LP
  2114. .PN XChangePointerControl
  2115. can generate a
  2116. .PN BadValue 
  2117. error.
  2118. .LP
  2119. .sp
  2120. To get the current pointer parameters, use
  2121. .PN XGetPointerControl .
  2122. .IN "XGetPointerControl" "" "@DEF@"
  2123. .\" Start marker code here
  2124. .FD 0
  2125. .\" $Header: XGetPntrCnt.f,v 1.1 88/02/26 10:00:55 mento Exp $
  2126. XGetPointerControl\^(\^\fIdisplay\fP, \fIaccel_numerator_return\fP\^, \fIaccel_denominator_return\fP\^, 
  2127. .br
  2128.                        \fIthreshold_return\fP\^)
  2129. .br
  2130.       Display *\fIdisplay\fP\^;
  2131. .br
  2132.       int *\fIaccel_numerator_return\fP\^, *\fIaccel_denominator_return\fP\^;
  2133. .br
  2134.       int *\fIthreshold_return\fP\^;
  2135. .FN
  2136. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2137. .IP \fIdisplay\fP 1i
  2138. Specifies the connection to the X server.
  2139. .\" $Header: accelnumret.a,v 1.1 88/02/26 10:04:45 mento Exp $
  2140. .IP \fIaccel_numerator_return\fP 1i
  2141. Returns the numerator for the acceleration multiplier.
  2142. .\" $Header: acceldenomrt.a,v 1.1 88/02/26 10:04:37 mento Exp $
  2143. .IP \fIaccel_denominator_return\fP 1i
  2144. Returns the denominator for the acceleration multiplier.
  2145. .\" $Header: thresholdret.a,v 1.1 88/02/26 10:31:39 mento Exp $
  2146. .IP \fIthreshold_return\fP 1i
  2147. Returns the acceleration threshold.
  2148. .\" End marker code here
  2149. .LP
  2150. .\" $Header: XGetPntrCnt.d,v 1.1 88/02/26 10:48:32 mento Exp $
  2151. The
  2152. .PN XGetPointerControl
  2153. function returns the pointer's current acceleration multiplier
  2154. and acceleration threshold.
  2155. .NH 2
  2156. Keyboard Encoding
  2157. .XS
  2158. \*(SN Keyboard Encoding 
  2159. .XE
  2160. .LP
  2161. A KeyCode represents a physical (or logical) key.  
  2162. KeyCodes lie in the inclusive range [8,255].  
  2163. A KeyCode value carries no intrinsic information,
  2164. although server implementors may attempt to encode geometry 
  2165. (for example, matrix) information in some fashion so that it can
  2166. be interpreted in a server-dependent fashion.
  2167. The mapping between keys and KeyCodes cannot be changed.
  2168. .LP
  2169. A KeySym is an encoding of a symbol on the cap of a key.  
  2170. The set of defined KeySyms includes the ISO Latin character sets (1\-4), 
  2171. Katakana, Arabic, Cyrillic, Greek, Technical,
  2172. Special, Publishing, APL, Hebrew,
  2173. and a special miscellany of keys found
  2174. on keyboards (Return, Help, Tab, and so on).  
  2175. To the extent possible, these sets are derived from international
  2176. standards. 
  2177. In areas where no standards exist,
  2178. some of these sets are derived from Digital Equipment Corporation standards.
  2179. The list of defined symbols can be found in
  2180. .Pn < X11/keysymdef.h >.
  2181. Unfortunately, some C preprocessors have
  2182. limits on the number of defined symbols.
  2183. If you must use KeySyms not
  2184. in the Latin 1\-4, Greek, and miscellaneous classes,
  2185. you may have to define a symbol for those sets.
  2186. Most applications usually only include 
  2187. .Pn < X11/keysym.h >,
  2188. which defines symbols for ISO Latin 1\-4, Greek, and miscellaneous.
  2189. .LP
  2190. A list of KeySyms is associated with each KeyCode.
  2191. The list is intended to convey the set of symbols on the corresponding key.
  2192. If the list (ignoring trailing NoSymbol entries) is 
  2193. a single KeySym ``\fIK\fP,''
  2194. then the list is treated as if it were the list 
  2195. ``\fIK\fP NoSymbol \fIK\fP NoSymbol.''
  2196. If the list (ignoring trailing NoSymbol entries) is 
  2197. a pair of KeySyms ``\fIK1 K2\fP,''
  2198. then the list is treated as if it were the list ``\fIK1 K2 K1 K2\fP.''
  2199. If the list (ignoring trailing NoSymbol entries) is 
  2200. a triple of KeySyms ``\fIK1 K2 K3\fP,''
  2201. then the list is treated as if it were the list ``\fIK1 K2 K3\fP NoSymbol.''
  2202. When an explicit ``void'' element is desired in the list,
  2203. the value VoidSymbol can be used.
  2204. .LP
  2205. The first four elements of the list are split into two groups of KeySyms.
  2206. Group 1 contains the first and second KeySyms;
  2207. Group 2 contains the third and fourth KeySyms.
  2208. Within each group,
  2209. if the second element of the group is NoSymbol,
  2210. then the group should be treated as if the second element were 
  2211. the same as the first element,
  2212. except when the first element is an alphabetic KeySym ``\fIK\fP'' 
  2213. for which both lowercase and uppercase forms are defined.
  2214. In that case,
  2215. the group should be treated as if the first element were 
  2216. the lowercase form of ``\fIK\fP'' and the second element were 
  2217. the uppercase form of ``\fIK\fP.''
  2218. .LP
  2219. The standard rules for obtaining a KeySym from a
  2220. .PN KeyPress
  2221. event make use of only the Group 1 and Group 2 KeySyms;
  2222. no interpretation of other KeySyms in the list is given.
  2223. Which group to use is determined by the modifier state.
  2224. Switching between groups is controlled by the KeySym named MODE SWITCH,
  2225. by attaching that KeySym to some KeyCode and attaching 
  2226. that KeyCode to any one of the modifiers Mod1 through Mod5.
  2227. This modifier is called the ``group modifier.''
  2228. For any KeyCode,
  2229. Group 1 is used when the group modifier is off,
  2230. and Group 2 is used when the group modifier is on.
  2231. .LP
  2232. Within a group,
  2233. the modifier state also determines which KeySym to use.
  2234. The first KeySym is used when the Shift and Lock modifiers are off.
  2235. The second KeySym is used when the Shift modifier is on,
  2236. when the Lock modifier is on and the second KeySym is uppercase alphabetic,
  2237. or when the Lock modifier is on and is interpreted as ShiftLock.
  2238. Otherwise, when the Lock modifier is on and is interpreted as CapsLock,
  2239. the state of the Shift modifier is applied first to select a KeySym;
  2240. but if that KeySym is lowercase alphabetic,
  2241. then the corresponding uppercase KeySym is used instead.
  2242. .LP
  2243. No spatial geometry of the symbols on the key is defined by
  2244. their order in the KeySym list, 
  2245. although a geometry might be defined on a
  2246. vendor-specific basis.
  2247. The X server does not use the mapping between KeyCodes and KeySyms.
  2248. Rather, it stores it merely for reading and writing by clients.
  2249. .LP
  2250. The KeyMask modifier named Lock is intended to be mapped 
  2251. to either a CapsLock or a ShiftLock key,
  2252. but which one is left as application-specific and/or user-specific.
  2253. However, it is suggested that the determination be made according to the
  2254. associated KeySym(s) of the corresponding KeyCode.
  2255. .sp
  2256. .LP
  2257. To obtain the legal KeyCodes for a display, use
  2258. .PN XDisplayKeycodes .
  2259. .IN "XDisplayKeycodes" "" "@DEF@"
  2260. .\" Start marker code here
  2261. .FD 0
  2262. XDisplayKeycodes\^(\^\fIdisplay\fP\^, \fImin_keycodes_return\fP\^, \
  2263. \fImax_keycodes_return\fP\^)
  2264. .br
  2265.         Display *\^\fIdisplay\fP\^;
  2266. .br
  2267.         int *\^\fImin_keycodes_return\fP\^, *\^\fImax_keycodes_return\fP\^;
  2268. .FN
  2269. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2270. .IP \fIdisplay\fP 1i
  2271. Specifies the connection to the X server.
  2272. .IP \fImin_keycodes_return\fP 1i
  2273. Returns the minimum number of KeyCodes.
  2274. .IP \fImax_keycodes_return\fP 1i
  2275. Returns the maximum number of KeyCodes.
  2276. .\" End marker code here
  2277. .LP
  2278. The
  2279. .PN XDisplayKeycodes
  2280. function returns the min-keycodes and max-keycodes supported by the
  2281. specified display.
  2282. The minimum number of KeyCodes returned is never less than 8,
  2283. and the maximum number of KeyCodes returned is never greater than 255.
  2284. Not all KeyCodes in this range are required to have corresponding keys.
  2285. .sp
  2286. .LP
  2287. To obtain the symbols for the specified KeyCodes, use
  2288. .PN XGetKeyboardMapping .
  2289. .IN "XGetKeyboardMapping" "" "@DEF@"
  2290. .\" Start marker code here
  2291. .FD 0
  2292. KeySym *XGetKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, 
  2293. .br
  2294.                             \fIkeysyms_per_keycode_return\fP\^)
  2295. .br
  2296.       Display *\fIdisplay\fP\^;
  2297. .br
  2298.       KeyCode \fIfirst_keycode\fP\^;
  2299. .br
  2300.       int \fIkeycode_count\fP\^;
  2301. .br
  2302.       int *\fIkeysyms_per_keycode_return\fP\^;
  2303. .FN
  2304. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2305. .IP \fIdisplay\fP 1i
  2306. Specifies the connection to the X server.
  2307. .ds Kc returned
  2308. .IP \fIfirst_keycode\fP 1i
  2309. Specifies the first KeyCode that is to be \*(Kc.
  2310. .IP \fIkeycode_count\fP 1i
  2311. Specifies the number of KeyCodes that are to be returned.
  2312. .IP \fIkeysyms_per_keycode_return\fP 1i
  2313. Returns the number of KeySyms per KeyCode.
  2314. .\" End marker code here
  2315. .LP
  2316. .\" $Header: XGetKeyMap.d,v 1.5 88/07/10 11:18:06 mento Exp $
  2317. The
  2318. .PN XGetKeyboardMapping
  2319. function returns the symbols for the specified number of KeyCodes
  2320. starting with first_keycode.
  2321. The value specified in first_keycode must be greater than 
  2322. or equal to min_keycode as returned by
  2323. .PN XDisplayKeycodes ,
  2324. or a
  2325. .PN BadValue 
  2326. error results.
  2327. In addition, the following expression must be less than or equal 
  2328. to max_keycode as returned by
  2329. .PN XDisplayKeycodes :
  2330. .LP
  2331. .Ds 
  2332. first_keycode + keycode_count \- 1
  2333. .De
  2334. .LP
  2335. If this is not the case, a 
  2336. .PN BadValue 
  2337. error results. 
  2338. The number of elements in the KeySyms list is:
  2339. .LP
  2340. .Ds 
  2341. keycode_count * keysyms_per_keycode_return
  2342. .De
  2343. .LP
  2344. KeySym number N, counting from zero, for KeyCode K has the following index
  2345. in the list, counting from zero: 
  2346. .Ds
  2347. (K \- first_code) * keysyms_per_code_return + N
  2348. .De
  2349. .LP
  2350. The X server arbitrarily chooses the keysyms_per_keycode_return value 
  2351. to be large enough to report all requested symbols. 
  2352. A special KeySym value of 
  2353. .PN NoSymbol 
  2354. is used to fill in unused elements for
  2355. individual KeyCodes.
  2356. To free the storage returned by 
  2357. .PN XGetKeyboardMapping ,
  2358. use
  2359. .PN XFree .
  2360. .LP
  2361. .PN XGetKeyboardMapping
  2362. can generate a
  2363. .PN BadValue 
  2364. error.
  2365. .LP
  2366. .sp
  2367. To change the keyboard mapping, use
  2368. .PN XChangeKeyboardMapping .
  2369. .IN "XChangeKeyboardMapping" "" "@DEF@"
  2370. .\" Start marker code here
  2371. .FD 0
  2372. XChangeKeyboardMapping(\^\fIdisplay\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fInum_codes\fP\^)
  2373. .br
  2374.       Display *\fIdisplay\fP\^;
  2375. .br
  2376.       int \fIfirst_keycode\fP\^;
  2377. .br
  2378.       int \fIkeysyms_per_keycode\fP\^;
  2379. .br
  2380.       KeySym *\fIkeysyms\fP\^;
  2381. .br
  2382.       int \fInum_codes\fP\^;
  2383. .FN
  2384. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2385. .IP \fIdisplay\fP 1i
  2386. Specifies the connection to the X server.
  2387. .ds Kc changed
  2388. .IP \fIfirst_keycode\fP 1i
  2389. Specifies the first KeyCode that is to be \*(Kc.
  2390. .IP \fIkeysyms_per_keycode\fP 1i
  2391. Specifies the number of KeySyms per KeyCode.
  2392. .IP \fIkeysyms\fP 1i
  2393. Specifies an array of KeySyms.
  2394. .IP \fInum_codes\fP 1i
  2395. Specifies the number of KeyCodes that are to be changed.
  2396. .\" End marker code here
  2397. .LP
  2398. .\" $Header: XCKMap.d,v 1.6 88/08/19 20:53:42 mento Exp $
  2399. The
  2400. .PN XChangeKeyboardMapping
  2401. function defines the symbols for the specified number of KeyCodes
  2402. starting with first_keycode.
  2403. The symbols for KeyCodes outside this range remain unchanged.  
  2404. The number of elements in keysyms must be:
  2405. .LP
  2406. .Ds
  2407. num_codes * keysyms_per_keycode
  2408. .De
  2409. .LP
  2410. The specified first_keycode must be greater than or equal to min_keycode 
  2411. returned by
  2412. .PN XDisplayKeycodes ,
  2413. or a 
  2414. .PN BadValue 
  2415. error results.
  2416. In addition, the following expression must be less than or equal to 
  2417. max_keycode as returned by
  2418. .PN XDisplayKeycodes ,
  2419. or a
  2420. .PN BadValue 
  2421. error results:
  2422. .LP
  2423. .Ds
  2424. first_keycode + num_codes \- 1
  2425. .De
  2426. .LP
  2427. KeySym number N, counting from zero, for KeyCode K has the following index
  2428. in keysyms, counting from zero: 
  2429. .LP
  2430. .Ds 
  2431. (K \- first_keycode) * keysyms_per_keycode + N
  2432. .De
  2433. .LP
  2434. The specified keysyms_per_keycode can be chosen arbitrarily by the client
  2435. to be large enough to hold all desired symbols. 
  2436. A special KeySym value of 
  2437. .PN NoSymbol 
  2438. should be used to fill in unused elements 
  2439. for individual KeyCodes.  
  2440. It is legal for 
  2441. .PN NoSymbol 
  2442. to appear in nontrailing positions
  2443. of the effective list for a KeyCode.
  2444. .PN XChangeKeyboardMapping
  2445. generates a 
  2446. .PN MappingNotify 
  2447. event.
  2448. .LP
  2449. There is no requirement that the X server interpret this mapping. 
  2450. It is merely stored for reading and writing by clients.
  2451. .LP
  2452. .PN XChangeKeyboardMapping
  2453. can generate
  2454. .PN BadAlloc 
  2455. and
  2456. .PN BadValue 
  2457. errors.
  2458. .LP
  2459. The next four functions make use of the 
  2460. .PN XModifierKeymap
  2461. data structure, which contains:
  2462. .LP
  2463. .IN "XModifierKeymap" "" "@DEF@"
  2464. .\" Start marker code here
  2465. .Ds 0
  2466. .TA .5i 2.5i
  2467. .ta .5i 2.5i
  2468. typedef struct {
  2469.     int max_keypermod;    /* This server's max number of keys per modifier */
  2470.     KeyCode *modifiermap;    /* An 8 by max_keypermod array of the modifiers */
  2471. } XModifierKeymap;
  2472. .De
  2473. .\" End marker code here
  2474. .LP
  2475. To create an
  2476. .PN XModifierKeymap
  2477. structure, use
  2478. .PN XNewModifiermap .
  2479. .IN "XNewModifiermap" "" "@DEF@"
  2480. .\" Start marker code here
  2481. .FD 0
  2482. XModifierKeymap *XNewModifiermap(\^\fImax_keys_per_mod\fP\^)
  2483. .br
  2484.         int \fImax_keys_per_mod\fP\^;
  2485. .FN
  2486. .IP \fImax_keys_per_mod\fP 1i
  2487. Specifies the number of KeyCode entries preallocated to the modifiers
  2488. in the map.
  2489. .\" End marker code here
  2490. .LP
  2491. .\" $Header: XNewModMap.d,v 1.5 88/08/19 20:54:43 mento Exp $
  2492. The
  2493. .PN XNewModifiermap
  2494. function returns a pointer to
  2495. .PN XModifierKeymap
  2496. structure for later use.
  2497. .LP
  2498. .sp
  2499. To add a new entry to an 
  2500. .PN XModifierKeymap
  2501. structure, use
  2502. .PN XInsertModifiermapEntry .
  2503. .IN "XInsertModifiermapEntry" "" "@DEF@"
  2504. .\" Start marker code here
  2505. .FD 0
  2506. XModifierKeymap *XInsertModifiermapEntry\^(\^\fImodmap\fP, \
  2507. \fIkeycode_entry\fP, \fImodifier\fP\^)
  2508. .br
  2509.      XModifierKeymap *\fImodmap\fP\^;
  2510. .br
  2511.      KeyCode \fIkeycode_entry\fP\^;
  2512. .br
  2513.      int \fImodifier\fP\^;
  2514. .FN
  2515. .IP \fImodmap\fP 1i
  2516. Specifies the 
  2517. .PN XModifierKeymap
  2518. structure.
  2519. .IP \fIkeycode_entry\fP 1i
  2520. Specifies the KeyCode. 
  2521. .IP \fImodifier\fP 1i
  2522. Specifies the modifier.
  2523. .\" End marker code here
  2524. .LP
  2525. The
  2526. .PN XInsertModifiermapEntry
  2527. function adds the specified KeyCode to the set that controls the specified
  2528. modifier and returns the resulting
  2529. .PN XModifierKeymap
  2530. structure (expanded as needed).
  2531. .LP
  2532. .sp
  2533. To delete an entry from an 
  2534. .PN XModifierKeymap
  2535. structure, use
  2536. .PN XDeleteModifiermapEntry .
  2537. .IN "XDeleteModifiermapEntry" "" "@DEF@"
  2538. .\" Start marker code here
  2539. .FD 0
  2540. XModifierKeymap *XDeleteModifiermapEntry\^(\^\fImodmap\fP, \
  2541. \fIkeycode_entry\fP, \fImodifier\fP\^)
  2542. .br
  2543.      XModifierKeymap *\fImodmap\fP\^;
  2544. .br
  2545.      KeyCode \fIkeycode_entry\fP\^;
  2546. .br
  2547.      int \fImodifier\fP\^;
  2548. .FN
  2549. .IP \fImodmap\fP 1i
  2550. Specifies the 
  2551. .PN XModifierKeymap
  2552. structure.
  2553. .IP \fIkeycode_entry\fP 1i
  2554. Specifies the KeyCode. 
  2555. .IP \fImodifier\fP 1i
  2556. Specifies the modifier.
  2557. .\" End marker code here
  2558. .LP
  2559. The
  2560. .PN XDeleteModifiermapEntry
  2561. function deletes the specified KeyCode from the set that controls the
  2562. specified modifier and returns a pointer to the resulting
  2563. .PN XModifierKeymap
  2564. structure.
  2565. .LP
  2566. .sp
  2567. To destroy an
  2568. .PN XModifierKeymap
  2569. structure, use
  2570. .PN XFreeModifiermap .
  2571. .IN "XFreeModifiermap" "" "@DEF@"
  2572. .\" Start marker code here
  2573. .FD 0
  2574. XFreeModifiermap(\^\fImodmap\fP\^)
  2575. .br
  2576.         XModifierKeymap *\fImodmap\fP;
  2577. .FN
  2578. .IP \fImodmap\fP 1i
  2579. Specifies the 
  2580. .PN XModifierKeymap
  2581. structure.
  2582. .\" End marker code here
  2583. .LP
  2584. .\" $Header: XFreeModMap.d,v 1.3 88/04/23 10:21:33 mento Exp $
  2585. The
  2586. .PN XFreeModifiermap
  2587. function frees the specified
  2588. .PN XModifierKeymap
  2589. structure.
  2590. .LP
  2591. .sp
  2592. To set the KeyCodes to be used as modifiers, use
  2593. .PN XSetModifierMapping .
  2594. .IN "XSetModifierMapping" "" "@DEF@"
  2595. .\" Start marker code here
  2596. .FD 0
  2597. int XSetModifierMapping(\^\fIdisplay\fP, \fImodmap\fP\^)
  2598. .br
  2599.         Display *\fIdisplay\fP\^;
  2600. .br
  2601.         XModifierKeymap *\fImodmap\fP\^;
  2602. .FN
  2603. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2604. .IP \fIdisplay\fP 1i
  2605. Specifies the connection to the X server.
  2606. .IP \fImodmap\fP 1i
  2607. Specifies the 
  2608. .PN XModifierKeymap
  2609. structure.
  2610. .\" End marker code here
  2611. .LP
  2612. .\" $Header: XSetModMap.d,v 1.6 88/08/19 20:58:48 mento Exp $
  2613. The
  2614. .PN XSetModifierMapping
  2615. function specifies the KeyCodes of the keys (if any) that are to be used 
  2616. as modifiers.
  2617. If it succeeds,
  2618. the X server generates a
  2619. .PN MappingNotify
  2620. event, and
  2621. .PN XSetModifierMapping
  2622. returns
  2623. .PN MappingSuccess .
  2624. X permits at most eight modifier keys.
  2625. If more than eight are specified in the
  2626. .PN XModifierKeymap
  2627. structure, a
  2628. .PN BadLength
  2629. error results.
  2630. .LP
  2631. The modifiermap member of the 
  2632. .PN XModifierKeymap
  2633. structure contains eight sets of max_keypermod KeyCodes, 
  2634. one for each modifier in the order 
  2635. .PN Shift , 
  2636. .PN Lock , 
  2637. .PN Control , 
  2638. .PN Mod1 , 
  2639. .PN Mod2 , 
  2640. .PN Mod3 , 
  2641. .PN Mod4 , 
  2642. and 
  2643. .PN Mod5 .
  2644. Only nonzero KeyCodes have meaning in each set, 
  2645. and zero KeyCodes are ignored.
  2646. In addition, all of the nonzero KeyCodes must be in the range specified by 
  2647. min_keycode and max_keycode in the 
  2648. .PN Display 
  2649. structure,
  2650. or a 
  2651. .PN BadValue 
  2652. error results.
  2653. .LP
  2654. An X server can impose restrictions on how modifiers can be changed, 
  2655. for example,
  2656. if certain keys do not generate up transitions in hardware,
  2657. if auto-repeat cannot be disabled on certain keys,
  2658. or if multiple modifier keys are not supported.  
  2659. If some such restriction is violated, 
  2660. the status reply is
  2661. .PN MappingFailed ,
  2662. and none of the modifiers are changed.
  2663. If the new KeyCodes specified for a modifier differ from those
  2664. currently defined and any (current or new) keys for that modifier are
  2665. in the logically down state, 
  2666. .PN XSetModifierMapping
  2667. returns
  2668. .PN MappingBusy , 
  2669. and none of the modifiers is changed.
  2670. .LP
  2671. .PN XSetModifierMapping
  2672. can generate
  2673. .PN BadAlloc
  2674. and 
  2675. .PN BadValue 
  2676. errors.
  2677. .LP
  2678. .sp
  2679. To obtain the KeyCodes used as modifiers, use
  2680. .PN XGetModifierMapping .
  2681. .IN "XGetModifierMapping" "" "@DEF@"
  2682. .\" Start marker code here
  2683. .FD 0
  2684. XModifierKeymap *XGetModifierMapping(\^\fIdisplay\fP\^)
  2685. .br
  2686.       Display *\fIdisplay\fP\^;
  2687.  
  2688. .FN
  2689. .\" $Header: display.a,v 1.1 88/02/26 10:26:29 mento Exp $
  2690. .IP \fIdisplay\fP 1i
  2691. Specifies the connection to the X server.
  2692. .\" End marker code here
  2693. .LP
  2694. .\" $Header: XGetModMap.d,v 1.3 88/08/19 21:00:28 mento Exp $
  2695. The
  2696. .PN XGetModifierMapping
  2697. function returns a pointer to a newly created
  2698. .PN XModifierKeymap
  2699. structure that contains the keys being used as modifiers.
  2700. The structure should be freed after use by calling
  2701. .PN XFreeModifiermap .
  2702. If only zero values appear in the set for any modifier, 
  2703. that modifier is disabled.
  2704. .bp
  2705.