1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 4<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 7<base target="main"> 8<title>KPR API Introduction</title> 9</head> 10 11<body> 12 13<h1>KPR API Introduction</h1> 14 15<h2>Introduction</h2> 16 17<p>KPR library provides support for the following functions:</p> 18<ul> 19<li>Support for "dead" keys to create accented characters</li> 20<li>Support for using the Alt key with the numeric keypad to enter Unicode values</li> 21<li>Support for converting Roman (Romaji) characters to Hiragana or Katakana</li> 22</ul> 23<p>To allow support for these functions by either a physical keyboard or a virtual on-screen keyboard, the KPR library is separate from the KBD library.</p> 24 25<h2>Architecture</h2> 26 27<p>The library implements queues that hold <code>wchar_t (u16)</code> values. Characters are placed into a queue, the library processes them, and the processed output is then retrieved from the queue.</p> 28<p>Characters should be entered into the appropriate queue as they are generated by the keyboard. Immediately after entering the character in the queue, the application should try to get the processed characters from the queue. The application should try to remove characters in a loop, since one input may generate multiple outputs. An output of 0 indicates that the queue is empty.</p> 29<p>Queue overflow should not occur if the above protocol is followed. It is an application error to put characters into a queue and not to try removing them immediately afterwards. If overflow does occur, a fatal error results.</p> 30<p>To support Alt+keypad keys, the private Unicode values KBK_Keypad_0 through KBK_Keypad_9 are placed in a queue whenever the Alt key is pressed while Num Lock is active and the keys 0-9 on the keypad are entered. To generate output when the Alt key is released, the value 0 should be entered into the queue.</p> 31<p>The following macros from <CODE>kbd.h</CODE> are helpful for Alt+keypad support:<code><pre>// Indicate if a key is a keypad number (digit) key with NumLock on 32#define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9))) 33// Indicate if a key is a keypad number (digit) key with NumLock off 34#define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up))) 35// Convert from NumLock off digit key to NumLock on digit key 36#define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40)) 37 38// Indicate if a ModState represents NumLock == on 39#define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT)) 40</pre></code> 41</p> 42<p>Each queue has a mode which indicates the type of processing to be done. More than one mode may be active at the same time, but with restrictions. Alt+keypad processing can always be turned on. Dead-key processing and Japanese-character processing are mutually exclusive. The two different kinds of Japanese-character processing are also mutually exclusive.</p> 43<h2>Interface</h2> 44<p>First, you must call <a href="KPRInitRegionUS.html"><code>KPRInitRegionUS</code></a>, <a href="KPRInitRegionJP.html"><code>KPRInitRegionJP</code></a>, or <a href="KPRInitRegionEU.html"><code>KPRInitRegionEU</code></a> to set up the code and maps for the appropriate region. It is okay to call more than one of these functions, as long as at least one is called. <a href="KPRInitQueue.html"><code>KPRInitQueue</code></a> is called to initialize a queue. The processing mode may be set using <a href="KPRSetMode.html"><code>KPRSetMode</code></a>. Use the <a href="KPRPutChar.html"><code>KPRPutChar</code></a> function to place characters in the queue; use the <a href="KPRPutChar.html"><code>KPRGetChar</code></a> function to get characters from the front of the queue. The function <a href="KPRRemoveChar.html"><code>KPRRemoveChar</code></a> can be used to remove unprocessed characters from the queue's tail, and <a href="KPRLookAhead.html"><code>KPRLookAhead</code></a> can be used to get a copy of the characters that are in the queue but have not been processed yet.</p> 45 46<h2>Revision History</h2> 47<P>2007/05/31 Initial version.</p> 48 49 50</BODY> 51</HTML>