keyboard.xml 32 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060
  1. <?xml version="1.0" encoding="ISO8859-1"?>
  2. <fpdoc-descriptions>
  3. <!--
  4. $Id$
  5. This file is part of the FPC documentation.
  6. Copyright (C) 1997, by Michael Van Canneyt
  7. The FPC documentation is free text; you can redistribute it and/or
  8. modify it under the terms of the GNU Library General Public License as
  9. published by the Free Software Foundation; either version 2 of the
  10. License, or (at your option) any later version.
  11. The FPC Documentation is distributed in the hope that it will be useful,
  12. but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. Library General Public License for more details.
  15. You should have received a copy of the GNU Library General Public
  16. License along with the FPC documentation; see the file COPYING.LIB. If not,
  17. write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18. Boston, MA 02111-1307, USA.
  19. -->
  20. <package name="rtl">
  21. <module name="keyboard">
  22. <short>Access to low-level keyboard functions</short>
  23. <!-- \FPCexampledir{kbdex} -->
  24. <descr>
  25. <p>
  26. The <file>KeyBoard</file> unit implements a keyboard access layer which is system
  27. independent. It can be used to poll the keyboard state and wait for certain
  28. events. Waiting for a keyboard event can be done with the <link id="GetKeyEvent"/>
  29. function, which will return a driver-dependent key event. This key event can
  30. be translated to a interpretable event by the <link id="TranslateKeyEvent"/>
  31. function. The result of this function can be used in the other event
  32. examining functions.
  33. </p>
  34. <p>
  35. A custom keyboard driver can be installed using the <link id="SetKeyboardDriver"/>
  36. function. The current keyboard driver can be retrieved using the
  37. <link id="GetKeyboardDriver"/> function. The last section of this chapter
  38. demonstrates how to make a keyboard driver.
  39. </p>
  40. </descr>
  41. <element name="errKbdBase">
  42. <short>Base of keyboard routine error reporting constants.</short>
  43. </element>
  44. <element name="errKbdInitError">
  45. <short>Failed to initialize keyboard driver</short>
  46. </element>
  47. <element name="errKbdNotImplemented">
  48. <short>Keyboard driver not implemented.</short>
  49. </element>
  50. <element name="kbdF1">
  51. <short>F1 function key pressed.</short>
  52. </element>
  53. <element name="kbdF2">
  54. <short>F2 function key pressed.</short>
  55. </element>
  56. <element name="kbdF3">
  57. <short>F3 function key pressed.</short>
  58. </element>
  59. <element name="kbdF4">
  60. <short>F4 function key pressed.</short>
  61. </element>
  62. <element name="kbdF5">
  63. <short>F5 function key pressed.</short>
  64. </element>
  65. <element name="kbdF6">
  66. <short>F6 function key pressed.</short>
  67. </element>
  68. <element name="kbdF7">
  69. <short>F7 function key pressed.</short>
  70. </element>
  71. <element name="kbdF8">
  72. <short>F8 function key pressed.</short>
  73. </element>
  74. <element name="kbdF9">
  75. <short>F9 function key pressed.</short>
  76. </element>
  77. <element name="kbdF10">
  78. <short>F10 function key pressed.</short>
  79. </element>
  80. <element name="kbdF11">
  81. <short>F12 function key pressed.</short>
  82. </element>
  83. <element name="kbdF12">
  84. <short>F12 function key pressed.</short>
  85. </element>
  86. <element name="kbdF13">
  87. <short>F13 function key pressed.</short>
  88. </element>
  89. <element name="kbdF14">
  90. <short>F14 function key pressed.</short>
  91. </element>
  92. <element name="kbdF15">
  93. <short>F15 function key pressed.</short>
  94. </element>
  95. <element name="kbdF16">
  96. <short>F16 function key pressed.</short>
  97. </element>
  98. <element name="kbdF17">
  99. <short>F17 function key pressed.</short>
  100. </element>
  101. <element name="kbdF18">
  102. <short>F18 function key pressed.</short>
  103. </element>
  104. <element name="kbdF19">
  105. <short>F19 function key pressed.</short>
  106. </element>
  107. <element name="kbdF20">
  108. <short>F20 function key pressed.</short>
  109. </element>
  110. <element name="kbFnKey">
  111. <short>function key pressed.</short>
  112. </element>
  113. <element name="ShiftPrefix">
  114. <short>Shift key name index.</short>
  115. </element>
  116. <element name="AltPrefix">
  117. <short>Alt key name index.</short>
  118. </element>
  119. <element name="CtrlPrefix">
  120. <short>Alt key name index.</short>
  121. </element>
  122. <element name="ShiftPrefix">
  123. <short>Shift key name index.</short>
  124. </element>
  125. <element name="kbdHome">
  126. <short>Home key pressed</short>
  127. </element>
  128. <element name="kbdUp">
  129. <short>Arrow up key pressed</short>
  130. </element>
  131. <element name="kbdDown">
  132. <short>Arrow down key pressed</short>
  133. </element>
  134. <element name="kbdPgUp">
  135. <short>Page Up key pressed</short>
  136. </element>
  137. <element name="kbdLeft">
  138. <short>Arrow left key pressed</short>
  139. </element>
  140. <element name="kbdMiddle">
  141. <short>Middle key pad key pressed (numerical 5)</short>
  142. </element>
  143. <element name="kbdRight">
  144. <short>Arrow right key pressed</short>
  145. </element>
  146. <element name="kbdEnd">
  147. <short>End key pressed</short>
  148. </element>
  149. <element name="kbdPgDn">
  150. <short>Page down key pressed</short>
  151. </element>
  152. <element name="kbdInsert">
  153. <short>Insert key pressed</short>
  154. </element>
  155. <element name="kbdDelete">
  156. <short>Delete key pressed</short>
  157. </element>
  158. <element name="kbASCII">
  159. <short>Ascii code key event</short>
  160. </element>
  161. <element name="kbUniCode">
  162. <short>Unicode code key event</short>
  163. </element>
  164. <element name="kbPhys">
  165. <short>Physical key code event</short>
  166. </element>
  167. <element name="kbReleased">
  168. <short>Key release event</short>
  169. </element>
  170. <element name="kbLeftShift">
  171. <short>Left shift key modifier</short>
  172. </element>
  173. <element name="kbRightShift">
  174. <short>Right shift key modifier</short>
  175. </element>
  176. <element name="kbShift">
  177. <short>Shift key modifier</short>
  178. </element>
  179. <element name="kbCtrl">
  180. <short>Control key modifier</short>
  181. </element>
  182. <element name="kbAlt">
  183. <short>Alt key modifier</short>
  184. </element>
  185. <element name="SShift">
  186. <short>Names of modifier keys</short>
  187. <descr>
  188. This constant describes the various modifier keys.
  189. This constant is used by the key event description routines.
  190. It can be changed to localize the key descriptions when needed.
  191. </descr>
  192. <seealso>
  193. <link id="KeyEventToString"/>
  194. <link id="FunctionKeyName"/>
  195. </seealso>
  196. </element>
  197. <element name="SLeftRight">
  198. <short>Names for left-right keys</short>
  199. <descr>
  200. This constant contains strings to describe left and right keys.
  201. This constant is used by the key event description routines.
  202. It can be changed to localize the key descriptions when needed.
  203. </descr>
  204. <seealso>
  205. <link id="KeyEventToString"/>
  206. <link id="FunctionKeyName"/>
  207. </seealso>
  208. </element>
  209. <element name="SUnicodeChar">
  210. <short>Unicode character string.</short>
  211. <descr>
  212. This constant contains a string to denote a unicode key event.
  213. This constant is used by the key event description routines.
  214. It can be changed to localize the key descriptions when needed.
  215. </descr>
  216. <seealso>
  217. <link id="KeyEventToString"/>
  218. <link id="FunctionKeyName"/>
  219. </seealso>
  220. </element>
  221. <element name="SScanCode">
  222. <short>Scancode key</short>
  223. <descr>
  224. This constant contains a string to denote a scancode key event.
  225. This constant is used by the key event description routines.
  226. It can be changed to localize the key descriptions when needed.
  227. </descr>
  228. <seealso>
  229. <link id="KeyEventToString"/>
  230. <link id="FunctionKeyName"/>
  231. </seealso>
  232. </element>
  233. <element name="SUnknownFunctionKey">
  234. <short>Unknown function key</short>
  235. <descr>
  236. This constant contains a string to denote that an unknown function key was
  237. found. This constant is used by the key event description routines.
  238. It can be changed to localize the key descriptions when needed.
  239. </descr>
  240. <seealso>
  241. <link id="KeyEventToString"/>
  242. <link id="FunctionKeyName"/>
  243. </seealso>
  244. </element>
  245. <element name="SAnd">
  246. <short>'And' description string</short>
  247. <descr>
  248. This constant is used as the 'And' word in key descriptions.
  249. This constant is used by the key event description routines.
  250. It can be changed to localize the key descriptions when needed.
  251. </descr>
  252. <seealso>
  253. <link id="KeyEventToString"/>
  254. <link id="FunctionKeyName"/>
  255. </seealso>
  256. </element>
  257. <element name="SKeyPad">
  258. <short>Names of keypad keys</short>
  259. <descr>
  260. This constant describes all keypad keys.
  261. This constant is used by the key event description routines.
  262. It can be changed to localize the key descriptions when needed.
  263. </descr>
  264. <seealso>
  265. <link id="KeyEventToString"/>
  266. <link id="FunctionKeyName"/>
  267. </seealso>
  268. </element>
  269. <element name="TKeyEvent">
  270. <short>Base type to describe all key events.</short>
  271. <descr>
  272. <p>
  273. The <var>TKeyEvent</var> type is the base type for all keyboard events.
  274. </p>
  275. <p>
  276. The key stroke is encoded in the 4 bytes of the <var>TKeyEvent</var> type.
  277. The various fields of the key stroke encoding can be obtained by typecasting
  278. the <var>TKeyEvent</var> type to the <link id="TKeyRecord"/> type.
  279. </p>
  280. </descr>
  281. </element>
  282. <element name="TKeyRecord">
  283. <short>Key event decoding type.</short>
  284. <descr>
  285. <p>
  286. The structure of a <var>TKeyRecord</var> structure is explained in the
  287. following table:
  288. </p>
  289. <table>
  290. <caption>Structure of TKeyRecord</caption>
  291. <th><td>Field</td><td>Meaning</td></th>
  292. <tr><td>KeyCode</td><td>
  293. Depending on <var>flags</var> either the physical representation of a key
  294. (under DOS scancode, ascii code pair), or the translated
  295. ASCII/unicode character.
  296. </td></tr>
  297. <tr>
  298. <td>ShiftState</td>
  299. <td>
  300. Shift-state when this key was pressed (or shortly after)
  301. </td></tr>
  302. <tr><td>Flags</td>
  303. <td>
  304. Determine how to interpret <var>KeyCode</var>
  305. </td></tr>
  306. </table>
  307. <p>
  308. The shift-state can be checked using the various shift-state constants,
  309. and the flags in the last byte can be checked using one of the
  310. kbASCII, kbUniCode, kbFnKey, kbPhys, kbReleased constants.
  311. </p>
  312. <p>
  313. If there are two keys returning the same char-code, there's no way to find
  314. out which one was pressed (Gray+ and Simple+). If it needs to be known which
  315. was pressed, the untranslated keycodes must be used, but these are system
  316. dependent. System dependent constants may be defined to cover those, with
  317. possibily having the same name (but different value).
  318. </p>
  319. </descr>
  320. <seealso>
  321. <link id="kbdscancode"/>
  322. <link id="TKeyEvent"/>
  323. </seealso>
  324. </element>
  325. <element name="TKeyboardDriver">
  326. <short>Keyboard driver structure</short>
  327. <descr>
  328. <p>
  329. The <var>TKeyboardDriver</var> record can be used to install a custom keyboard
  330. driver with the <link id="SetKeyboardDriver"/> function.
  331. </p>
  332. <p>
  333. The various fields correspond to the different functions of the keyboard unit
  334. interface. For more information about this record see <link id="kbddriver"/>
  335. </p>
  336. </descr>
  337. <seealso>
  338. <link id="SetKeyboardDriver"/>
  339. <link id="kbddriver"/>
  340. </seealso>
  341. </element>
  342. <element name="DoneKeyboard">
  343. <short>Deactivate keyboard driver.</short>
  344. <descr>
  345. <p>
  346. <var>DoneKeyboard</var> de-initializes the keyboard interface if the keyboard
  347. driver is active. If the keyboard driver is not active, the function does
  348. nothing.
  349. </p>
  350. <p>
  351. This will cause the keyboard driver to clear up any allocated memory,
  352. or restores the console or terminal the program was running in to its
  353. initial state before the call to <link id="InitKeyBoard"/>. This function should
  354. be called on program exit. Failing to do so may leave the terminal or
  355. console window in an unusable state. Its exact action depends on the
  356. platform on which the program is running.
  357. </p>
  358. <p>
  359. For an example, see most other functions.
  360. </p>
  361. </descr>
  362. <errors>
  363. None.
  364. </errors>
  365. <seealso>
  366. <link id="InitKeyBoard"/>
  367. </seealso>
  368. </element>
  369. <element name="FunctionKeyName">
  370. <short>Return string representation of a function key code.</short>
  371. <descr>
  372. <var>FunctionKeyName</var> returns a string representation of the function key
  373. with code <var>KeyCode</var>. This can be an actual function key, or one of the
  374. cursor movement keys.
  375. </descr>
  376. <errors>
  377. In case <var>KeyCode</var> does not contain a function code, the
  378. <var>SUnknownFunctionKey</var> string is returned, appended with the
  379. <var>KeyCode</var>.
  380. </errors>
  381. <seealso>
  382. <link id="ShiftStateToString"/>
  383. <link id="KeyEventToString"/>
  384. </seealso>
  385. <example file="kbdex/ex8"/>
  386. </element>
  387. <element name="GetKeyboardDriver">
  388. <short>Return the current keyboard driver record.</short>
  389. <descr>
  390. <p>
  391. <var>GetKeyBoardDriver</var> returns in <var>Driver</var> the currently active
  392. keyboard driver. This function can be used to enhance an existing
  393. keyboarddriver.
  394. </p>
  395. <p>
  396. For more information on getting and setting the keyboard driver
  397. <link id="kbddriver"/>.
  398. </p>
  399. </descr>
  400. <errors>
  401. None.
  402. </errors>
  403. <seealso>
  404. <link id="SetKeyboardDriver"/>
  405. </seealso>
  406. </element>
  407. <element name="GetKeyEvent">
  408. <short>Get the next raw key event, wait if needed.</short>
  409. <descr>
  410. <p>
  411. <var>GetKeyEvent</var> returns the last keyevent if one was stored in
  412. <var>PendingKeyEvent</var>, or waits for one if none is available.
  413. A non-blocking version is available in <link id="PollKeyEvent"/>.
  414. </p>
  415. <p>
  416. The returned key is encoded as a <var>TKeyEvent</var> type variable, and
  417. is normally the physical key scan code, (the scan code is driver
  418. dependent) which can be translated with one of the translation
  419. functions <link id="TranslateKeyEvent"/> or <link id="TranslateKeyEventUniCode"/>.
  420. See the types section for a description of how the key is described.
  421. </p>
  422. </descr>
  423. <errors>
  424. If no key became available, 0 is returned.
  425. </errors>
  426. <seealso>
  427. <link id="PutKeyEvent"/>
  428. <link id="PollKeyEvent"/>
  429. <link id="TranslateKeyEvent"/>,
  430. <link id="TranslateKeyEventUniCode"/>
  431. </seealso>
  432. <example file="kbdex/ex1"/>
  433. </element>
  434. <element name="GetKeyEventChar">
  435. <short>Get the character key part of a key event.</short>
  436. <descr>
  437. <p>
  438. <var>GetKeyEventChar</var> returns the charcode part of the given
  439. <var>KeyEvent</var>, if it contains a translated character key
  440. keycode. The charcode is simply the ascii code of the
  441. character key that was pressed.
  442. </p>
  443. <p>
  444. It returns the null character if the key was not a character key, but e.g. a
  445. function key.
  446. </p>
  447. <p>
  448. For an example, see <link id="GetKeyEvent"/>
  449. </p>
  450. </descr>
  451. <errors>
  452. None.
  453. </errors>
  454. <seealso>
  455. <link id="GetKeyEventUniCode"/>,
  456. <link id="GetKeyEventShiftState"/>,
  457. <link id="GetKeyEventFlags"/>,
  458. <link id="GetKeyEventCode"/>,
  459. <link id="GetKeyEvent"/>
  460. </seealso>
  461. </element>
  462. <element name="GetKeyEventCode">
  463. <short>Translate function key part of a key event code.</short>
  464. <descr>
  465. <p>
  466. <var>GetKeyEventCode</var> returns the translated function keycode part of
  467. the given KeyEvent, if it contains a translated function key.
  468. </p>
  469. <p>
  470. If the key pressed was not a function key, the null character is returned.
  471. </p>
  472. </descr>
  473. <errors>
  474. None.
  475. </errors>
  476. <seealso>
  477. <link id="GetKeyEventUniCode"/>,
  478. <link id="GetKeyEventShiftState"/>,
  479. <link id="GetKeyEventFlags"/>,
  480. <link id="GetKeyEventChar"/>,
  481. <link id="GetKeyEvent"/>
  482. </seealso>
  483. <example file="kbdex/ex2"/>
  484. </element>
  485. <element name="GetKeyEventFlags">
  486. <short>Extract the flags from a key event.</short>
  487. <descr>
  488. <p>
  489. <var>GetKeyEventFlags</var> returns the flags part of the given
  490. <var>KeyEvent</var>.
  491. </p>
  492. <p>
  493. For an example, see <link id="GetKeyEvent"/>
  494. </p>
  495. </descr>
  496. <errors>
  497. None.
  498. </errors>
  499. <seealso>
  500. <link id="GetKeyEventUniCode"/>,
  501. <link id="GetKeyEventShiftState"/>,
  502. <link id="GetKeyEventCode"/>,
  503. <link id="GetKeyEventChar"/>,
  504. <link id="GetKeyEvent"/>
  505. </seealso>
  506. </element>
  507. <element name="GetKeyEventShiftState">
  508. <short>Return the current state of the shift keys.</short>
  509. <descr>
  510. <p>
  511. <var>GetKeyEventShiftState</var> returns the shift-state values of
  512. the given <var>KeyEvent</var>. This can be used to detect which of the modifier
  513. keys <var>Shift</var>, <var>Alt</var> or <var>Ctrl</var> were pressed. If none were
  514. pressed, zero is returned.
  515. </p>
  516. <p>
  517. Note that this function does not always return expected results;
  518. In a unix X-Term, the modifier keys do not always work.
  519. </p>
  520. </descr>
  521. <errors>
  522. None.
  523. </errors>
  524. <seealso>
  525. <link id="GetKeyEventUniCode"/>,
  526. <link id="GetKeyEventFlags"/>,
  527. <link id="GetKeyEventCode"/>,
  528. <link id="GetKeyEventChar"/>,
  529. <link id="GetKeyEvent"/>
  530. </seealso>
  531. <example file="kbdex/ex3"/>
  532. </element>
  533. <element name="GetKeyEventUniCode">
  534. <short>Return the unicode key event.</short>
  535. <descr>
  536. <var>GetKeyEventUniCode</var> returns the unicode part of the
  537. given <var>KeyEvent</var> if it contains a translated unicode
  538. character.
  539. </descr>
  540. <errors>
  541. None.
  542. </errors>
  543. <seealso>
  544. <link id="GetKeyEventShiftState"/>,
  545. <link id="GetKeyEventFlags"/>,
  546. <link id="GetKeyEventCode"/>,
  547. <link id="GetKeyEventChar"/>,
  548. <link id="GetKeyEvent"/>
  549. </seealso>
  550. </element>
  551. <element name="InitKeyBoard">
  552. <short>Initialize the keyboard driver.</short>
  553. <descr>
  554. <p>
  555. <var>InitKeyboard</var> initializes the keyboard driver.
  556. If the driver is already active, it does nothing. When the driver is
  557. initialized, it will do everything necessary to ensure the functioning of
  558. the keyboard, including allocating memory, initializing the terminal etc.
  559. </p>
  560. <p>
  561. This function should be called once, before using any of the
  562. keyboard functions. When it is called, the <link id="DoneKeyboard"/> function
  563. should also be called before exiting the program or changing the keyboard
  564. driver with <link id="SetKeyboardDriver"/>.
  565. </p>
  566. <p>
  567. For an example, see most other functions.
  568. </p>
  569. </descr>
  570. <errors>
  571. None.
  572. </errors>
  573. <seealso>
  574. <link id="DoneKeyboard"/>
  575. <link id="SetKeyboardDriver"/>
  576. </seealso>
  577. </element>
  578. <element name="AddSequence" skip="1"/>
  579. <element name="FindSequence" skip="1"/>
  580. <element name="RawReadKey" skip="1"/>
  581. <element name="RawReadString" skip="1"/>
  582. <element name="RestoreStartMode" skip="1"/>
  583. <element name="IsFunctionKey">
  584. <short>Check whether a given event is a function key event.</short>
  585. <descr>
  586. <var>IsFunctionKey</var> returns <var>True</var> if the given key event
  587. in <var>KeyEvent</var> was a function key or not.
  588. </descr>
  589. <errors>
  590. None.
  591. </errors>
  592. <seealso>
  593. <link id="GetKeyEvent"/>
  594. </seealso>
  595. <example file="kbdex/ex7"/>
  596. </element>
  597. <element name="KeyEventToString">
  598. <short>Return a string describing the key event.</short>
  599. <descr>
  600. <p>
  601. <var>KeyEventToString</var> translates the key event in <var>KeyEvent</var> to a
  602. human-readable description of the pressed key. It will use the constants
  603. described in the constants section to do so.
  604. </p>
  605. <p>
  606. For an example, see most other functions.
  607. </p>
  608. </descr>
  609. <errors>
  610. If an unknown key is passed, the scancode is returned, prefixed with the
  611. <var>SScanCode</var> string.
  612. </errors>
  613. <seealso>
  614. <link id="FunctionKeyName"/>
  615. <link id="ShiftStateToString"/>
  616. </seealso>
  617. </element>
  618. <element name="KeyPressed">
  619. <short>Check event queue for key press</short>
  620. <descr>
  621. <var>KeyPressed</var> checks the keyboard event queue to see whether a key
  622. event is present, and returns <var>True</var> if a key event is available.
  623. This function simply calls <link id="PollKeyEvent"/> and checks for a valid
  624. result.
  625. </descr>
  626. <errors>
  627. None.
  628. </errors>
  629. <seealso>
  630. <link id="PollKeyEvent"/>
  631. <link id="GetKeyEvent"/>
  632. </seealso>
  633. </element>
  634. <element name="PollKeyEvent">
  635. <short>Get next key event, but does not wait.</short>
  636. <descr>
  637. <p>
  638. <var>PollKeyEvent</var> checks whether a key event is available,
  639. and returns it if one is found. If no event is pending,
  640. it returns 0.
  641. </p>
  642. <p>
  643. Note that this does not remove the key from the pending keys.
  644. The key should still be retrieved from the pending key events
  645. list with the <link id="GetKeyEvent"/> function.
  646. </p>
  647. </descr>
  648. <errors>
  649. None.
  650. </errors>
  651. <seealso>
  652. <link id="PutKeyEvent"/>
  653. <link id="GetKeyEvent"/>
  654. </seealso>
  655. <example file="kbdex/ex4"/>
  656. </element>
  657. <element name="PollShiftStateEvent">
  658. <short>Check current shift state. </short>
  659. <descr>
  660. <var>PollShiftStateEvent</var> returns the current shiftstate in a
  661. keyevent. This will return 0 if there is no key event pending.
  662. </descr>
  663. <errors>
  664. None.
  665. </errors>
  666. <seealso>
  667. <link id="PollKeyEvent"/>
  668. <link id="GetKeyEvent"/>
  669. </seealso>
  670. <example file="kbdex/ex6"/>
  671. </element>
  672. <element name="PutKeyEvent">
  673. <short>Put a key event in the event queue.</short>
  674. <descr>
  675. <var>PutKeyEvent</var> adds the given <var>KeyEvent</var> to the input
  676. queue. Please note that depending on the implementation this
  677. can hold only one value, i.e. when calling <var>PutKeyEvent</var>
  678. multiple times, only the last pushed key will be remembered.
  679. </descr>
  680. <errors>
  681. None
  682. </errors>
  683. <seealso>
  684. <link id="PollKeyEvent"/>
  685. <link id="GetKeyEvent"/>
  686. </seealso>
  687. <example file="kbdex/ex5"/>
  688. </element>
  689. <element name="SetKeyboardDriver">
  690. <short>Set a new keyboard driver.</short>
  691. <descr>
  692. <p>
  693. <var>SetKeyBoardDriver</var> sets the keyboard driver to <var>Driver</var>, if the
  694. current keyboard driver is not yet initialized. If the current
  695. keyboard driver is initialized, then <var>SetKeyboardDriver</var> does
  696. nothing. Before setting the driver, the currently active driver should
  697. be disabled with a call to <link id="DoneKeyboard"/>.
  698. </p>
  699. <p>
  700. The function returns <var>True</var> if the driver was set, <var>False</var> if not.
  701. </p>
  702. <p>
  703. For more information on setting the keyboard driver, see <link id="kbddriver"/>.
  704. </p>
  705. </descr>
  706. <errors>
  707. None.
  708. </errors>
  709. <seealso>
  710. <link id="GetKeyboardDriver"/>
  711. <link id="DoneKeyboard"/>.
  712. </seealso>
  713. </element>
  714. <element name="ShiftStateToString">
  715. <short>Return description of key event shift state</short>
  716. <descr>
  717. <p>
  718. <var>ShiftStateToString</var> returns a string description of the shift state
  719. of the key event <var>KeyEvent</var>. This can be an empty string.
  720. </p>
  721. <p>
  722. The shift state is described using the strings in the <var>SShift</var> constant.
  723. </p>
  724. <p>
  725. For an example, see <link id="PollShiftStateEvent"/>.
  726. </p>
  727. </descr>
  728. <errors>
  729. None.
  730. </errors>
  731. <seealso>
  732. <link id="FunctionKeyName"/>
  733. <link id="KeyEventToString"/>
  734. </seealso>
  735. </element>
  736. <element name="TranslateKeyEvent">
  737. <short>Translate raw event to ascii key event</short>
  738. <descr>
  739. <p>
  740. <var>TranslateKeyEvent</var> performs ASCII translation of the <var>KeyEvent</var>.
  741. It translates a physical key to a function key if the key is a function key,
  742. and translates the physical key to the ordinal of the ascii character if
  743. there is an equivalent character key.
  744. </p>
  745. <p>
  746. For an example, see <link id="GetKeyEvent"/>
  747. </p>
  748. </descr>
  749. <errors>
  750. None.
  751. </errors>
  752. <seealso>
  753. <link id="TranslateKeyEventUniCode"/>
  754. </seealso>
  755. </element>
  756. <element name="TranslateKeyEventUniCode">
  757. <short>Translate raw event to UNICode key event</short>
  758. <descr>
  759. <var>TranslateKeyEventUniCode</var> performs Unicode translation of the
  760. <var>KeyEvent</var>. It is not yet implemented for all platforms.
  761. </descr>
  762. <errors>
  763. If the function is not yet implemented, then the <var>ErrorCode</var> of the
  764. <file>system</file> unit will be set to <var>errKbdNotImplemented</var>
  765. </errors>
  766. <seealso>
  767. <link id="TranslateKeyEvent"/>
  768. </seealso>
  769. </element>
  770. <topic name="kbdscancode">
  771. <short>Keyboard scan codes</short>
  772. <descr>
  773. <p>
  774. Special physical keys are encoded with the DOS scan codes for these keys
  775. in the second byte of the <link id="TKeyEvent"/> type.
  776. A complete list of scan codes can be found in the below table.
  777. This is the list of keys that is used by the default key event translation mechanism.
  778. When writing a keyboard driver, either these constants should be returned
  779. by the various key event functions, or the <var>TranslateKeyEvent</var> hook
  780. should be implemented by the driver.
  781. </p>
  782. <table border="1">
  783. <caption>Key Scancodes</caption>
  784. <th><td>Code</td><td>Key</td><td>Code</td><td>Key</td><td>Code</td><td>Key</td></th>
  785. <tr><td>00 </td><td> NoKey </td><td> 3D </td><td> F3 </td><td> 70 </td><td> ALT-F9 </td></tr>
  786. <tr><td>01 </td><td> ALT-Esc </td><td> 3E </td><td> F4 </td><td> 71 </td><td> ALT-F10 </td></tr>
  787. <tr><td>02 </td><td> ALT-Space </td><td> 3F </td><td> F5 </td><td> 72 </td><td> CTRL-PrtSc </td></tr>
  788. <tr><td>04 </td><td> CTRL-Ins </td><td> 40 </td><td> F6 </td><td> 73 </td><td> CTRL-Left </td></tr>
  789. <tr><td>05 </td><td> SHIFT-Ins </td><td> 41 </td><td> F7 </td><td> 74 </td><td> CTRL-Right </td></tr>
  790. <tr><td>06 </td><td> CTRL-Del </td><td> 42 </td><td> F8 </td><td> 75 </td><td> CTRL-end </td></tr>
  791. <tr><td>07 </td><td> SHIFT-Del </td><td> 43 </td><td> F9 </td><td> 76 </td><td> CTRL-PgDn </td></tr>
  792. <tr><td>08 </td><td> ALT-Back </td><td> 44 </td><td> F10 </td><td> 77 </td><td> CTRL-Home </td></tr>
  793. <tr><td>09 </td><td> ALT-SHIFT-Back </td><td> 47 </td><td> Home </td><td> 78 </td><td> ALT-1 </td></tr>
  794. <tr><td>0F </td><td> SHIFT-Tab </td><td> 48 </td><td> Up </td><td> 79 </td><td> ALT-2 </td></tr>
  795. <tr><td>10 </td><td> ALT-Q </td><td> 49 </td><td> PgUp </td><td> 7A </td><td> ALT-3 </td></tr>
  796. <tr><td>11 </td><td> ALT-W </td><td> 4B </td><td> Left </td><td> 7B </td><td> ALT-4 </td></tr>
  797. <tr><td>12 </td><td> ALT-E </td><td> 4C </td><td> Center </td><td> 7C </td><td> ALT-5 </td></tr>
  798. <tr><td>13 </td><td> ALT-R </td><td> 4D </td><td> Right </td><td> 7D </td><td> ALT-6 </td></tr>
  799. <tr><td>14 </td><td> ALT-T </td><td> 4E </td><td> ALT-GrayPlus </td><td> 7E </td><td> ALT-7 </td></tr>
  800. <tr><td>15 </td><td> ALT-Y </td><td> 4F </td><td> end </td><td> 7F </td><td> ALT-8 </td></tr>
  801. <tr><td>16 </td><td> ALT-U </td><td> 50 </td><td> Down </td><td> 80 </td><td> ALT-9 </td></tr>
  802. <tr><td>17 </td><td> ALT-I </td><td> 51 </td><td> PgDn </td><td> 81 </td><td> ALT-0 </td></tr>
  803. <tr><td>18 </td><td> ALT-O </td><td> 52 </td><td> Ins </td><td> 82 </td><td> ALT-Minus </td></tr>
  804. <tr><td>19 </td><td> ALT-P </td><td> 53 </td><td> Del </td><td> 83 </td><td> ALT-Equal </td></tr>
  805. <tr><td>1A </td><td> ALT-LftBrack </td><td> 54 </td><td> SHIFT-F1 </td><td> 84 </td><td> CTRL-PgUp </td></tr>
  806. <tr><td>1B </td><td> ALT-RgtBrack </td><td> 55 </td><td> SHIFT-F2 </td><td> 85 </td><td> F11 </td></tr>
  807. <tr><td>1E </td><td> ALT-A </td><td> 56 </td><td> SHIFT-F3 </td><td> 86 </td><td> F12 </td></tr>
  808. <tr><td>1F </td><td> ALT-S </td><td> 57 </td><td> SHIFT-F4 </td><td> 87 </td><td> SHIFT-F11 </td></tr>
  809. <tr><td>20 </td><td> ALT-D </td><td> 58 </td><td> SHIFT-F5 </td><td> 88 </td><td> SHIFT-F12 </td></tr>
  810. <tr><td>21 </td><td> ALT-F </td><td> 59 </td><td> SHIFT-F6 </td><td> 89 </td><td> CTRL-F11 </td></tr>
  811. <tr><td>22 </td><td> ALT-G </td><td> 5A </td><td> SHIFT-F7 </td><td> 8A </td><td> CTRL-F12 </td></tr>
  812. <tr><td>23 </td><td> ALT-H </td><td> 5B </td><td> SHIFT-F8 </td><td> 8B </td><td> ALT-F11 </td></tr>
  813. <tr><td>24 </td><td> ALT-J </td><td> 5C </td><td> SHIFT-F9 </td><td> 8C </td><td> ALT-F12 </td></tr>
  814. <tr><td>25 </td><td> ALT-K </td><td> 5D </td><td> SHIFT-F10 </td><td> 8D </td><td> CTRL-Up </td></tr>
  815. <tr><td>26 </td><td> ALT-L </td><td> 5E </td><td> CTRL-F1 </td><td> 8E </td><td> CTRL-Minus </td></tr>
  816. <tr><td>27 </td><td> ALT-SemiCol </td><td> 5F </td><td> CTRL-F2 </td><td> 8F </td><td> CTRL-Center </td></tr>
  817. <tr><td>28 </td><td> ALT-Quote </td><td> 60 </td><td> CTRL-F3 </td><td> 90 </td><td> CTRL-GreyPlus </td></tr>
  818. <tr><td>29 </td><td> ALT-OpQuote </td><td> 61 </td><td> CTRL-F4 </td><td> 91 </td><td> CTRL-Down </td></tr>
  819. <tr><td>2B </td><td> ALT-BkSlash </td><td> 62 </td><td> CTRL-F5 </td><td> 94 </td><td> CTRL-Tab </td></tr>
  820. <tr><td>2C </td><td> ALT-Z </td><td> 63 </td><td> CTRL-F6 </td><td> 97 </td><td> ALT-Home </td></tr>
  821. <tr><td>2D </td><td> ALT-X </td><td> 64 </td><td> CTRL-F7 </td><td> 98 </td><td> ALT-Up </td></tr>
  822. <tr><td>2E </td><td> ALT-C </td><td> 65 </td><td> CTRL-F8 </td><td> 99 </td><td> ALT-PgUp </td></tr>
  823. <tr><td>2F </td><td> ALT-V </td><td> 66 </td><td> CTRL-F9 </td><td> 9B </td><td> ALT-Left </td></tr>
  824. <tr><td>30 </td><td> ALT-B </td><td> 67 </td><td> CTRL-F10 </td><td> 9D </td><td> ALT-Right </td></tr>
  825. <tr><td>31 </td><td> ALT-N </td><td> 68 </td><td> ALT-F1 </td><td> 9F </td><td> ALT-end </td></tr>
  826. <tr><td>32 </td><td> ALT-M </td><td> 69 </td><td> ALT-F2 </td><td> A0 </td><td> ALT-Down </td></tr>
  827. <tr><td>33 </td><td> ALT-Comma </td><td> 6A </td><td> ALT-F3 </td><td> A1 </td><td> ALT-PgDn </td></tr>
  828. <tr><td>34 </td><td> ALT-Period </td><td> 6B </td><td> ALT-F4 </td><td> A2 </td><td> ALT-Ins </td></tr>
  829. <tr><td>35 </td><td> ALT-Slash </td><td> 6C </td><td> ALT-F5 </td><td> A3 </td><td> ALT-Del </td></tr>
  830. <tr><td>37 </td><td> ALT-GreyAst </td><td> 6D </td><td> ALT-F6 </td><td> A5 </td><td> ALT-Tab </td></tr>
  831. <tr><td>3B </td><td> F1 </td><td> 6E </td><td> ALT-F7 </td><td> </td><td> </td></tr>
  832. <tr><td>3C </td><td> F2 </td><td> 6F </td><td> ALT-F8 </td><td> </td><td> </td></tr>
  833. </table>
  834. <p>
  835. A list of scan codes for special keys and combinations with the SHIFT, ALT
  836. and CTRL keys can be found in the following table: They are for quick reference
  837. only.
  838. </p>
  839. <table border="1">
  840. <caption>Special keys scan codes</caption>
  841. <th><td>Key </td><td> Code </td><td> SHIFT-Key </td><td> CTRL-Key </td><td> Alt-Key</td></th>
  842. <tr><td>NoKey </td><td> 00 </td><td> </td><td> </td><td> </td></tr>
  843. <tr><td>F1 </td><td> 3B </td><td> 54 </td><td> 5E </td><td> 68 </td></tr>
  844. <tr><td>F2 </td><td> 3C </td><td> 55 </td><td> 5F </td><td> 69 </td></tr>
  845. <tr><td>F3 </td><td> 3D </td><td> 56 </td><td> 60 </td><td> 6A </td></tr>
  846. <tr><td>F4 </td><td> 3E </td><td> 57 </td><td> 61 </td><td> 6B </td></tr>
  847. <tr><td>F5 </td><td> 3F </td><td> 58 </td><td> 62 </td><td> 6C </td></tr>
  848. <tr><td>F6 </td><td> 40 </td><td> 59 </td><td> 63 </td><td> 6D </td></tr>
  849. <tr><td>F7 </td><td> 41 </td><td> 5A </td><td> 64 </td><td> 6E </td></tr>
  850. <tr><td>F8 </td><td> 42 </td><td> 5A </td><td> 65 </td><td> 6F </td></tr>
  851. <tr><td>F9 </td><td> 43 </td><td> 5B </td><td> 66 </td><td> 70 </td></tr>
  852. <tr><td>F10 </td><td> 44 </td><td> 5C </td><td> 67 </td><td> 71 </td></tr>
  853. <tr><td>F11 </td><td> 85 </td><td> 87 </td><td> 89 </td><td> 8B </td></tr>
  854. <tr><td>F12 </td><td> 86 </td><td> 88 </td><td> 8A </td><td> 8C </td></tr>
  855. <tr><td>Home </td><td> 47 </td><td> </td><td> 77 </td><td> 97 </td></tr>
  856. <tr><td>Up </td><td> 48 </td><td> </td><td> 8D </td><td> 98 </td></tr>
  857. <tr><td>PgUp </td><td> 49 </td><td> </td><td> 84 </td><td> 99 </td></tr>
  858. <tr><td>Left </td><td> 4B </td><td> </td><td> 73 </td><td> 9B </td></tr>
  859. <tr><td>Center </td><td> 4C </td><td> </td><td> 8F </td><td> </td></tr>
  860. <tr><td>Right </td><td> 4D </td><td> </td><td> 74 </td><td> 9D </td></tr>
  861. <tr><td>end </td><td> 4F </td><td> </td><td> 75 </td><td> 9F </td></tr>
  862. <tr><td>Down </td><td> 50 </td><td> </td><td> 91 </td><td> A0 </td></tr>
  863. <tr><td>PgDn </td><td> 51 </td><td> </td><td> 76 </td><td> A1 </td></tr>
  864. <tr><td>Ins </td><td> 52 </td><td> 05 </td><td> 04 </td><td> A2 </td></tr>
  865. <tr><td>Del </td><td> 53 </td><td> 07 </td><td> 06 </td><td> A3 </td></tr>
  866. <tr><td>Tab </td><td> 8 </td><td> 0F </td><td> 94 </td><td> A5 </td></tr>
  867. <tr><td>GreyPlus </td><td> </td><td> </td><td> 90 </td><td> 4E </td></tr>
  868. </table>
  869. </descr>
  870. </topic>
  871. <topic name="kbddriver">
  872. <short>Writing a keyboard driver</short>
  873. <descr>
  874. <p>
  875. Writing a keyboard driver means that hooks must be created for most of the
  876. keyboard unit functions. The <var>TKeyBoardDriver</var> record contains a field
  877. for each of the possible hooks:
  878. </p>
  879. <code>
  880. TKeyboardDriver = Record
  881. InitDriver : Procedure;
  882. DoneDriver : Procedure;
  883. GetKeyEvent : Function : TKeyEvent;
  884. PollKeyEvent : Function : TKeyEvent;
  885. GetShiftState : Function : Byte;
  886. TranslateKeyEvent : Function (KeyEvent: TKeyEvent): TKeyEvent;
  887. TranslateKeyEventUniCode: Function (KeyEvent: TKeyEvent): TKeyEvent;
  888. end;
  889. </code>
  890. <p>
  891. The meaning of these hooks is explained below:
  892. </p>
  893. <dl>
  894. <dt>InitDriver</dt>
  895. <dd> Called to initialize and enable the driver.
  896. Guaranteed to be called only once. This should initialize all needed things
  897. for the driver.
  898. </dd>
  899. <dt>DoneDriver</dt>
  900. <dd> Called to disable and clean up the driver. Guaranteed to be
  901. called after a call to <var>initDriver</var>. This should clean up all
  902. things initialized by <var>InitDriver</var>.
  903. </dd>
  904. <dt>GetKeyEvent</dt>
  905. <dd> Called by <link id="GetKeyEvent"/>. Must wait for and return the
  906. next key event. It should NOT store keys.
  907. </dd>
  908. <dt>PollKeyEvent</dt>
  909. <dd> Called by <link id="PollKeyEvent"/>. It must return the next key
  910. event if there is one. Should not store keys.
  911. </dd>
  912. <dt>GetShiftState</dt>
  913. <dd> Called by <link id="PollShiftStateEvent"/>. Must return the current
  914. shift state.
  915. </dd>
  916. <dt>TranslateKeyEvent</dt>
  917. <dd> Should translate a raw key event to a cOrrect
  918. key event, i.e. should fill in the shiftstate and convert function key
  919. scancodes to function key keycodes. If the
  920. <var>TranslateKeyEvent</var> is not filled in, a default translation function
  921. will be called which converts the known scancodes from the tables in the
  922. previous section to a correct keyevent.
  923. </dd>
  924. <dt>TranslateKeyEventUniCode</dt>
  925. <dd> Should translate a key event to a unicode key
  926. representation.
  927. </dd>
  928. </dl>
  929. <p>
  930. Strictly speaking, only the <var>GetKeyEvent</var> and <var>PollKeyEvent</var>
  931. hooks must be implemented for the driver to function correctly.
  932. </p>
  933. <p>
  934. The example unit demonstrates how a keyboard driver can be installed.
  935. It takes the installed driver, and hooks into the <var>GetKeyEvent</var>
  936. function to register and log the key events in a file. This driver
  937. can work on top of any other driver, as long as it is inserted in the
  938. <var>uses</var> clause <em> after</em> the real driver unit, and the real driver unit
  939. should set the driver record in its initialization section.
  940. </p>
  941. <p>
  942. Note that with a simple extension of this unit could be used to make a
  943. driver that is capable of recording and storing a set of keyboard strokes,
  944. and replaying them at a later time, so a 'keyboard macro' capable driver.
  945. This driver could sit on top of any other driver.
  946. </p>
  947. </descr>
  948. <example file="kbdex/logkeys"/>
  949. <example file="kbdex/ex9"/>
  950. </topic>
  951. </module>
  952. </package>
  953. </fpdoc-descriptions>