home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / textmode.zip / kbd.doc < prev    next >
Text File  |  1995-07-06  |  17KB  |  594 lines
  1. *
  2. * Title: kbd.doc
  3. *
  4. * Function:
  5. *     Workplace OS/2 keyboard APIs
  6. *
  7. * Copyright:
  8. *     Copyright (C) IBM Corp. 1993, 1995
  9. *
  10. * Notes:
  11. *     This is preliminary documentation and subject to change.
  12. *
  13. ========================================================================
  14.  
  15. KbdCharIn - Read Character from Keyboard
  16.  
  17. APIRET APIENTRY  KbdCharIn(PKBDKEYINFO CharData, ULONG Flag, HKBD hkbd);
  18.  
  19. KbdCharIn reads a character data record from the keyboard
  20.  
  21. Parameters
  22.  
  23.     CharData (PKBDKEYINFO)  output
  24.         Address of character data structure:
  25.         USHORT   ucUniChar - Unicode char
  26.         USHORT   chChar    - Char in current codepage
  27.         UCHAR    chScan    - Scan code
  28.         UCHAR    fbStatus  - Final/Interim bits
  29.         USHORT   fsState   - Shift state
  30.         ULONG    VKey      - Virtual key
  31.         UCHAR    bNlsShift - NLS Shift state
  32.         UCHAR    resv      - Reserved
  33.         ULONG    time      - Time stamp (ms from IPL)
  34.  
  35.     Flag (ULONG)  input
  36.         Wait for a keystorke if not available
  37.         0 = Wait if a keystroke is not available
  38.         1 = Immediate return if no keystroke available
  39.         2 = Return keystroke if available, but do not remove from queue
  40.  
  41.     hkbd (HKBD)  input
  42.         Reserved, must be zero
  43.  
  44. Returns
  45.     0    = No error
  46.     375  = ERROR_KBD_INVALID_IOWAIT
  47.     439  = ERROR_KBD_INVALID_HANDLE
  48.  
  49. Comments
  50.     Note: KbdCharIn returns a complete keystroke.  This behavior is
  51.     unlike the OS/2 1.X version, which only returned a single byte.
  52.  
  53.     If bit 0 of fbStatus is set, the character returned is either 0
  54.     or 0xe0.  The unicode character contains the virtual key.
  55.  
  56.     For valid characters, the character in the current codepage is
  57.     returned, and the unicode character contains the unicode encoding
  58.     of the character.
  59.  
  60. ========================================================================
  61.  
  62. KbdFlushBuffer - Flush the input keyboard buffer
  63.  
  64. APIRET APIENTRY  KbdFlushBuffer (HKBD hkbd);
  65.  
  66. KbdFlushBuffer removes all entries from the keyboard buffer.  This
  67. discards all user type ahead.
  68.  
  69. Parameters
  70.  
  71.     hkbd (HKBD)  input
  72.         Reserved, must be zero
  73.  
  74. Returns
  75.     0    = No error
  76.     439  = ERROR_KBD_INVALID_HANDLE
  77.  
  78. Comments
  79.  
  80. ========================================================================
  81.  
  82. KbdGetConsole - Read Key or Event from Console
  83.  
  84. APIRET APIENTRY  KbdGetConsole(PVOID Data, PULONG Kind, ULONG Flags,
  85.                     HKBD hkbd);
  86.  
  87. KbdCharIn reads a key, mouse event, or notify from the console.
  88.  
  89. Parameters
  90.  
  91.     Data (PVOID)   output
  92.         The form of the data returned depends on the type of event.
  93.         For keyboard events, this is of type KBDKEYINFO.  For mouse
  94.         events this is of the form MOUQUEINFO.
  95.  
  96.     Kind (PULONG)  output
  97.         The returned event kind:
  98.         0 = No event available
  99.         1 = Keyboard event (not a valid character)
  100.         2 = Character returned
  101.         3 = Mouse event
  102.         4 = Notification
  103.  
  104.     Flag (ULONG)  input
  105.         Wait for a keystorke if not available
  106.         0 = Wait if an event is not available
  107.         1 = Immediate return if no keystroke available
  108.         2 = Return event if available, but do not remove from queue
  109.         3 = Wait for event and return it, but do not remove from queue
  110.  
  111.     hkbd (HKBD)  input
  112.         Reserved, must be zero
  113.  
  114. Returns
  115.     0    = No error
  116.     375  = ERROR_KBD_INVALID_IOWAIT
  117.     439  = ERROR_KBD_INVALID_HANDLE
  118.  
  119. Comments
  120.     KbdGetConsole allows the retrieval of either a keyboard or mouse
  121.     event.  This should be used by programs using both input devices.
  122.     See KbdCharIn and MouReadEventQue for details of the returned
  123.     values and conditions.
  124.  
  125.     Note: Only those mouse events which are enabled by the event mask
  126.     are returned.  By default, the event mask is disabled.
  127.  
  128. ========================================================================
  129.  
  130. KbdGetCp - Get keyboard codepage
  131.  
  132. APIRET APIENTRY  KbdGetCp (ULONG ulReserved, PUSHORT pidCP, HKBD hkbd);
  133.  
  134. KbdGetCp returns the current keyboard codepage.
  135.  
  136. Parameters
  137.  
  138.     ulReserved (ULONG)  input
  139.         Reserved, must be zero
  140.  
  141.     pidCP (PUSHORT)  output
  142.         Pointer to location to return code page
  143.  
  144.     hkbd (HKBD)  input
  145.         Reserved, must be zero
  146.  
  147. Returns
  148.     0    = No error
  149.     439  = ERROR_KBD_INVALID_HANDLE
  150.  
  151. Comments
  152.  
  153. ========================================================================
  154.  
  155. KbdGetHWID - Get keyboard hardware ID
  156.  
  157. APIRET APIENTRY  KbdGetHWID (PKBDHWID pkbdhwid, HKBD hkbd);
  158.  
  159. KbdGetHWID returns the type of keyboard in use.  The hardware ID
  160. specifies the type of keyboard attached, and is defined by the
  161. manufacturer.
  162.  
  163. Parameters
  164.  
  165.     pkbdhwid (PKBDHWID)  output
  166.         Pointer to location to return keyboard hardware ID.
  167.  
  168.     hkbd (HKBD)  input
  169.         Reserved, must be zero
  170.  
  171. Returns
  172.     0    = No error
  173.     439  = ERROR_KBD_INVALID_HANDLE
  174.  
  175. Comments
  176.  
  177. ========================================================================
  178.  
  179. KbdGetLayout - Get keyboard layout
  180.  
  181. APIRET APIENTRY  KbdGetLayout(PSZ name, HKBD hkbd);
  182.  
  183. Returns the name of the keyboard layout in use in ASCII.
  184.  
  185. Parameters
  186.  
  187.     name (PSZ)  output
  188.         Pointer to location to return keyboard layout.
  189.  
  190.     hkbd (HKBD)  input
  191.         Reserved, must be zero
  192.  
  193. Returns
  194.     0    = No error
  195.     439  = ERROR_KBD_INVALID_HANDLE
  196.  
  197. Comments
  198.  
  199. ========================================================================
  200.  
  201. KbdGetLayoutUni - Get keyboard layout Uni
  202.  
  203. APIRET APIENTRY  KbdGetLayout(UniChar * name, HKBD hkbd);
  204.  
  205. Returns the name of the keyboard layout in use in Unicode.
  206.  
  207. Parameters
  208.  
  209.     name (UniChar *)  output
  210.         Pointer to location to return keyboard layout.
  211.  
  212.     hkbd (HKBD)  input
  213.         Reserved, must be zero
  214.  
  215. Returns
  216.     0    = No error
  217.     439  = ERROR_KBD_INVALID_HANDLE
  218.  
  219. Comments
  220.  
  221. ========================================================================
  222.  
  223. KbdGetStatus - Get keyboard status
  224.  
  225. APIRET APIENTRY  KbdGetStatus (PKBDINFO pkbdinfo, HKBD hkbd);
  226.  
  227. KbdGetStatus returns a set of information concerning the keyboard.
  228.  
  229. Parameters
  230.  
  231.     pkbdinfo (PKBDINFO)  output
  232.         Pointer to location to return keyboard status.
  233.         USHORT cb           - Length of returned data (10)
  234.         USHORT fsMask       - State mask
  235.         USHORT chTurnAround - Turnaround character
  236.         USHORT fsInterim    - Interim character state (and NLS Shift)
  237.         USHORT fsState      - Current shift state
  238.  
  239.     hkbd (HKBD)  input
  240.         Reserved, must be zero
  241.  
  242. Returns
  243.     0    = No error
  244.     376  = ERROR_KBD_INVALID_LENGTH
  245.     439  = ERROR_KBD_INVALID_HANDLE
  246.  
  247. Comments
  248.     Some of the keyboard status information may be changed using
  249.     KbdSetStatus.
  250.  
  251.     The upper byte within fsInterim is the NLS Shift state.  The
  252.     meaning of the NLS shift varies by language.  The following bits
  253.     are defined to access this data.
  254.  
  255.     NLSS_NLS1   (0x01)  -  Fullwidth, National layer
  256.     NLSS_NLS2   (0x02)  -  Katakana, JAMO, phonetic
  257.     NLSS_NLS3   (0x04)  -  Hiragana, Hangeul, TsangJye
  258.     NLSS_APPL   (0x10)  -  Application bit
  259.     NLSS_NLS4   (0x40)  -  Romanji, HanjaCsr
  260.     NLSS_KANJI  (0x80)  -  Kanji, Hanja
  261.  
  262.  
  263. ========================================================================
  264.  
  265. KbdPeek - Peek at a keyboard character
  266.  
  267. APIRET APIENTRY  KbdPeek(PKBDKEYINFO CharData, HKBD hkbd);
  268.  
  269. KbdPeek returns keyboard data if available, but does not remove it
  270. from the queue.
  271.  
  272. Parameters
  273.  
  274.     CharData (PKBDKEYINFO)  output
  275.         Address of character data structure:
  276.         USHORT   ucUniChar - Unicode char
  277.         USHORT   chChar    - Char in current codepage
  278.         UCHAR    chScan    - Scan code
  279.         UCHAR    fbStatus  - Final/Interim bits
  280.         USHORT   fsState   - Shift state
  281.         ULONG    VKey      - Virtual key
  282.         UCHAR    bNlsShift - NLS Shift state
  283.         UCHAR    resv      - Reserved
  284.         ULONG    time      - Time stamp (ms from IPL)
  285.  
  286.     hkbd (HKBD)  input
  287.         Reserved, must be zero
  288.  
  289. Returns
  290.     0    = No error
  291.     375  = ERROR_KBD_INVALID_IOWAIT
  292.     439  = ERROR_KBD_INVALID_HANDLE
  293.  
  294. Comments
  295.     Note: KbdPeek returns a complete keystroke.  This behavior is
  296.     unlike the OS/2 1.X version, which only returned a single byte.
  297.  
  298.     If bit 0 of fbStatus is set, the character returned is either 0
  299.     or 0xe0.  The unicode character contains the virtual key.
  300.  
  301.     For valid characters, the character in the current codepage is
  302.     returned, and the unicode character contains the unicode encoding
  303.     of the character.
  304.  
  305. ========================================================================
  306.  
  307. KbdSetCp - Set keyboard codepage
  308.  
  309. APIRET APIENTRY  KbdGetCp (ULONG ulReserved, USHORT idCP, HKBD hkbd);
  310.  
  311. KbdSetCp sets the current keyboard codepage.  This causes a change in
  312. the translation of keys.  The codepage may be any non-stateful codepage.
  313. Setting this codepage does not affect the display or process codepages.
  314.  
  315. Parameters
  316.  
  317.     ulReserved (ULONG)  input
  318.         Reserved, must be zero
  319.  
  320.     idCP (USHORT)  input
  321.         Pointer to location to return code page
  322.  
  323.     hkbd (HKBD)  input
  324.         Reserved, must be zero
  325.  
  326. Returns
  327.     0    = No error
  328.     439  = ERROR_KBD_INVALID_HANDLE
  329.     443  = ERROR_KBD_INVALID_CODEPAGE_ID
  330.  
  331. Comments
  332.  
  333. ========================================================================
  334.  
  335. KbdSetLayout - Set keyboard layout
  336.  
  337. APIRET APIENTRY  KbdSetLayout(PSZ name, HKBD hkbd);
  338.  
  339. Returns the name of the keyboard layout in use in ASCII.
  340.  
  341. Parameters
  342.  
  343.     name (PSZ)  input
  344.         Name of new keyboard layout.
  345.  
  346.     hkbd (HKBD)  input
  347.         Reserved, must be zero
  348.  
  349. Returns
  350.     0    = No error
  351.     439  = ERROR_KBD_INVALID_HANDLE
  352.     476  = ERROR_CODE_PAGE_NOT_FOUND
  353.  
  354. Comments
  355.  
  356. ========================================================================
  357.  
  358. KbdSetLayoutUni - Set keyboard layout
  359.  
  360. APIRET APIENTRY  KbdSetLayout(UniChar * name, HKBD hkbd);
  361.  
  362. Returns the name of the keyboard layout in use in Unicode.
  363.  
  364. Parameters
  365.  
  366.     name (UniChar *)  input
  367.         Name of new keyboard layout.
  368.  
  369.     hkbd (HKBD)  input
  370.         Reserved, must be zero
  371.  
  372. Returns
  373.     0    = No error
  374.     439  = ERROR_KBD_INVALID_HANDLE
  375.          = ERROR_INVALID_KBD_LAYOUT
  376.  
  377. Comments
  378.  
  379. ========================================================================
  380.  
  381. KbdSetRate - Set keyboard rate and delay
  382.  
  383. APIRET APIENTRY  KbdSetRate (ULONG rate, ULONG delay, HKBD hkbd);
  384.  
  385. KbdSetRate allows the typomatic rate of the keyboard to be changed.
  386. The change is global and affects all sessions.  If the device is not
  387. capable of the specified rate, device is set to the nearest available
  388. value.
  389.  
  390. Parameters
  391.  
  392.     rate (ULONG)  input
  393.         Number of repeated keys per second.  This is normally a value
  394.         between 1 and 30.
  395.  
  396.     delay (ULONG)  input
  397.         Delay before first repeated key.  This is normally a value
  398.         between 250 and 1000.
  399.  
  400.     hkbd (HKBD)  input
  401.         Reserved, must be zero
  402.  
  403. Returns
  404.     0    = No error
  405.     439  = ERROR_KBD_INVALID_HANDLE
  406.  
  407. Comments
  408.  
  409.  
  410. ========================================================================
  411.  
  412. KbdSetStatus - Set keyboard status
  413.  
  414. APIRET APIENTRY  KbdSetStatus (PKBDINFO pkbdinfo, HKBD hkbd);
  415.  
  416. KbdSetStatus allows the current state of the keyboard to be changed.
  417.  
  418. Parameters
  419.  
  420.     pkbdhwid (PKBDINFO)  input
  421.         Pointer to location to return keyboard status.
  422.         USHORT cb           - Length of returned data (10)
  423.         USHORT fsMask       - State mask
  424.         USHORT chTurnAround - Turnaround character
  425.         USHORT fsInterim    - Interim character state (and NLS shift)
  426.         USHORT fsState      - Current shift state
  427.  
  428.     hkbd (HKBD)  input
  429.         Reserved, must be zero
  430.  
  431. Returns
  432.     0    = No error
  433.     376  = ERROR_KBD_INVALID_LENGTH
  434.     439  = ERROR_KBD_INVALID_HANDLE
  435.  
  436. Comments
  437.  
  438.     Bits 15-8  Reserved (must be zero)
  439.     Bit  9     Set terminal input mode
  440.     Bit  8     Return shifts
  441.     Bit  7     Use two byte turnaround
  442.     Bit  6     Modify turn around character
  443.     Bit  5     Modify interim flags
  444.     Bit  4     Modify shift state
  445.     Bit  3     Set ASCII input mode
  446.     Bit  2     Set Binary input mode
  447.     Bit  1     Set Echo off
  448.     Bit  0     Set Echo on
  449.  
  450. Notes:
  451.     The upper byte of the fsInterim is the NLS shift state, and may
  452.     be modified by this API.
  453.  
  454. ========================================================================
  455.  
  456. KbdStringIn - Get string input
  457.  
  458. APIRET APIENTRY  KbdStringIn (PCH pch, PSTRINGINBUF pchIn, ULONG Flag,
  459.                                      HKBD hkbd);
  460.  
  461. KbdStringIn gets a string of keyboard input.
  462.  
  463. Parameters
  464.  
  465.     pch (PCH)  output
  466.  
  467.     pchIn (PSTRINGINBUF)  input/output
  468.         Pointer to buffer length structure
  469.         USHORT cb    - Length of input buffer (bytes)
  470.         USHORT cchIn - Number of bytes returned
  471.  
  472.     Flag (ULONG)  input
  473.         Wait for a keystorke if not availab*e
  474.         0 = Wait if a keystroke is not available
  475.         1 = Immediate return if no keystroke available
  476.  
  477.     hkbd (HKBD)  input
  478.         Reserved, must be zero
  479.  
  480. Returns
  481.     0    = No error
  482.     376  = ERROR_KBD_INVALID_LENGTH
  483.     439  = ERROR_KBD_INVALID_HANDLE
  484.  
  485. Comments
  486.     Note: This function is retained only for compatibility.  New code
  487.     should not use it.  KbdGetConsole is the preferred function for
  488.     new code.
  489.  
  490.     The contents and ending condition depends on the keyboard state:
  491.  
  492.     ASCII  - Only valid characters are placed in the input buffer.
  493.              The function ends when a turnaround character is found,
  494.              or when the buffer fills.  The turnaround character is
  495.              placed in the buffer, but is not included in the string
  496.              length returned.
  497.  
  498.     BINARY - Both valid characters and extended keys are returned.
  499.              The extended keys are returned as two byte strings with
  500.              a leading 0x00 or 0xe0 character.  The function ends
  501.              when the buffer fills.
  502.  
  503.     The maximum buffer length is 255 bytes.
  504.  
  505. ========================================================================
  506.  
  507. KbdStringInUni - Get string input
  508.  
  509. APIRET APIENTRY  KbdStringInUni (UniChar * puch, PSTRINGINBUF pchIn, ULONG Flag,
  510.                                      HKBD hkbd);
  511.  
  512. KbdStringIn gets a string of keyboard input.
  513.  
  514. Parameters
  515.  
  516.     puch (UniChar *)  output
  517.  
  518.     pchIn (PSTRINGINBUF)  input/output
  519.         Pointer to buffer length structure
  520.         USHORT cb    - Length of input buffer (bytes)
  521.         USHORT cchIn - Number of bytes returned
  522.  
  523.     Flag (ULONG)  input
  524.         Wait for a keystorke if not availab*e
  525.         0 = Wait if a keystroke is not available
  526.         1 = Immediate return if no keystroke available
  527.  
  528.     hkbd (HKBD)  input
  529.         Reserved, must be zero
  530.  
  531. Returns
  532.     0    = No error
  533.     376  = ERROR_KBD_INVALID_LENGTH
  534.     439  = ERROR_KBD_INVALID_HANDLE
  535.  
  536. Comments
  537.     Note: This function is retained only for compatibility.  New code
  538.     should not use it.  KbdGetConsole is the preferred function for
  539.     new code.
  540.  
  541.     The contents and ending condition depends on the keyboard state:
  542.  
  543.     ASCII  - Only valid characters are placed in the input buffer.
  544.              The function ends when a turnaround character is found,
  545.              or when the buffer fills.  The turnaround character is
  546.              placed in the buffer, but is not included in the string
  547.              length returned.
  548.  
  549.     BINARY - Both valid characters and extended keys are returned.
  550.              The extended keys are returned as two byte strings with
  551.              a leading 0x00 or 0xe0 character.  The function ends
  552.              when the buffer fills.
  553.  
  554.     The maximum buffer length is 255 bytes.
  555.  
  556. ========================================================================
  557.  
  558. KbdXlate - Translate scan codes
  559.  
  560. APIRET APIENTRY  KbdXlate (PKBDKEYINFO pKey, HKBD hkbd);
  561.  
  562. KbdXlate allows for the translation of scan codes to characters.
  563.  
  564. Parameters
  565.  
  566.     pKey (PKBDKEYINFO)  input/output
  567.         Address of character data structure:
  568.         USHORT   ucUniChar - Unicode char
  569.         USHORT   chChar    - Char in current codepage
  570.         UCHAR    chScan    - Scan code
  571.         UCHAR    fbStatus  - Final/Interim bits
  572.         USHORT   fsState   - Shift state
  573.         ULONG    VKey      - Virtual key
  574.         UCHAR    bNlsShift - NLS Shift state
  575.         UCHAR    resv      - Reserved
  576.         ULONG    time      - Time stamp (ms from IPL)
  577.  
  578.     hkbd (HKBD)  input
  579.         Reserved, must be zero
  580.  
  581. Returns
  582.     0    = No error
  583.     376  = ERROR_KBD_INVALID_LENGTH
  584.     439  = ERROR_KBD_INVALID_HANDLE
  585.  
  586. Comments
  587.     This function is designed for conditions where the scan codes
  588.     are known, but not the character.  This must be used with care,
  589.     and is not designed to substitute for the normal OS/2 keyboard
  590.     translation functions.
  591.  
  592.     The field resv must be maintained from call to call whenever
  593.     an interim bit is set.
  594.