Xcode icon

KeyNaming

About

KeyNaming is a library for Mac OS which translates virtual key codes to user-readable strings, taking into account the current keyboard mapping. It is fully Unicode-aware. It should in principle work under Mac OS 8 and 9 with any version of CarbonLib, but this hasn’t been tested recently. I believe it works under all versions of Mac OS X, but may have problems with Unicode keyboard layouts on systems earlier than 10.2.

Virtual key codes are provided by all the standard event processing mechanisms in Mac OS X (Carbon Events, NSEvent, WaitNextEvent()) as well as GetKeys().

Overview

In normal use, one simply passes a virtual key code to KeyNamingCopyOneKeyName(), or an array of virtual key codes to KeyNamingCopyKeyNames(), and gets a CFString back. Most keys are handled by calling UCKeyTranslate() or KeyTranslate() as appropriate. A number of special keys – modifier keys, keypad keys, arrow keys and others – are instead looked up in a string file. Various subtleties, like distinguishing between escape and clear, and allowing F keys to be remapped to characters, are handled correctly.

The string file can of course be customised. Two sets are provided, with short and long names. The long names provide strings like “Command  Shift  Left Arrow”. The short names provide strings like “⌘  ⇧  ⇠”. By default, names are looked up in KeyNaming.strings, but this can be changed by calling KeyNamingSetStringTable() or KeyNamingSetStringTableAndBundle(). String files for English and Swedish are currently included; submissions for other languages would be gratefully accepted.

For more information, see the HeaderDoc documentation.

Configuration

Several macros can be used to modify the behaviour of KeyNaming.

  • KEYNAMING_ENABLE_VKC: if defined, treated as a boolean flag indicating whether the virtual key code interface should be available. If not defined, the header will define it as 1.
  • KEYNAMING_ENABLE_HID: if defined, treated as a boolean flag indicating whether the USB HID usage code interface should be available. If not defined, the header will define it as 1.
  • KEYNAMING_MAKE_TEST_RIG: if defined, a main() function which tests the virtual key code interface will be generated. The value of the macro is currently ignored.

Name Checks

An earlier, non-Unicode version of KeyNaming was used in the Mac version of Black & White.

KeyNaming is used in OmniDazzle.

The Code

  • Code is available from GitHub.

License

KeyNaming is distributed under the MIT/X11 license. This license is approved as a GPL-compatible Free Software license by the Free Software Foundation, and as an Open Source license by the Open Source Initiative. The text of the license is as follows:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.