KPR Library Overview

Introduction

The KPR library provides support for the following features.

The KPR library is separate from the KBD library so that these functions can be supported by a physical keyboard or by a virtual on-screen keyboard.

Architecture

The library implements queues that hold wchar_t (u16) values. Characters are placed in a queue, the library processes them, and then the processed output is retrieved from the queue.

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.

Queue overflow should not occur if the above protocol is followed. It is an application error to put characters into a queue and not try to remove them immediately afterwards. If overflow does occur, a fatal error results.

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 0-9 keys on the keypad are entered. To generate output when the ALT key is released, the value 0 is placed into the queue.

The following macros from kbd.h are helpful for ALT+keypad support:

    // Indicate if a key is a keypad number (digit) key with NumLock on
    #define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9)))
    // Indicate if a key is a keypad number (digit) key with NumLock off
    #define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up)))
    // Convert from NumLock off digit key to NumLock on digit key
    #define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))
    
    // Indicate if a ModState represents NumLock == on
    #define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT))

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.

Interface

First, you must call KPRInitRegionUS, KPRInitRegionJP, or KPRInitRegionEU to set up the code and maps for the appropriate region. It is acceptable to call more than one of these functions, as long as at least one is called. KPRInitQueue is called to initialize a queue. The processing mode is set using KPRSetMode. The KPRPutChar function is used to put characters into the queue. The KPRGetChar function is used to get characters from the head of the queue. The KPRRemoveChar function can be used to remove unprocessed characters from the queue's tail. The KPRLookAhead function can be used to get a copy of the characters that are in the queue but have not been processed yet.

Revision History

2013/05/08 Automated cleanup pass.
2012/08/21 Cleanup Pass


CONFIDENTIAL