---

Keyboard Layout Services Reference

Overview

Keyboard Layout Services is the programming interface that lets you obtain information about available keyboard layouts, set a keyboard layout, and access a keyboard layout property list. Keyboard Layout Services fully supports Unicode ('uchr') as well as old style ('KCHR') keyboard layouts.

Functions by Task

Working With Keyboard Layouts

• KBGetLayoutType
• KLGetCurrentKeyboardLayout Deprecated in Mac OS X v10.5
• KLGetKeyboardLayoutAtIndex Deprecated in Mac OS X v10.5
• KLGetKeyboardLayoutCount Deprecated in Mac OS X v10.5
• KLGetKeyboardLayoutProperty Deprecated in Mac OS X v10.5
• KLGetKeyboardLayoutWithIdentifier Deprecated in Mac OS X v10.5
• KLGetKeyboardLayoutWithName Deprecated in Mac OS X v10.5
• KLSetCurrentKeyboardLayout Deprecated in Mac OS X v10.5

Unsupported Functions

• KLGetIndexedKeyboardLayout

Functions

KBGetLayoutType

Obtains the type of keyboard attached to the computer.

PhysicalKeyboardLayoutType KBGetLayoutType (
   SInt16 iKeyboardType
);

Parameters

keyboardType

The keyboard type ID of the keyboard whose type you want to obtain. You can obtain the keyboard type ID by calling the Event Manager function LMGetKbdType.

Return Value

The type of the keyboard attached to the computer. See “Physical Keyboard Layout Types” for the values that can be returned.

Discussion

You can call the function KBGetLayoutType to determine whether the keyboard attached to the computer is ANSI, ISO, or JIS. You should call this function in Mac OS 9 only if the Gestalt selector gestaltKeyboardLib is present.

Availability

• Not available in CarbonLib.
• Available in Mac OS X version 10.0 and later.

Declared In

Keyboards.h

KLGetIndexedKeyboardLayout

Obtains the keyboard layout reference associated with the specified index.

Not supported.

OSStatus KLGetIndexedKeyboardLayout (
   CFIndex iIndex,
   KeyboardLayoutRef * oKeyboardLayout
);

Availability

• Unsupported. Not available in CarbonLib. Not available in Mac OS X version 10.2 and later.

Carbon Porting Notes

You should use the function KLGetKeyboardLayoutAtIndex instead.

Declared In

Keyboards.h

Data Types

KeyboardLayoutRef

Specifies a reference to an opaque keyboard layout data structure.

typedef struct OpaqueKeyboardLayoutRef * KeyboardLayoutRef;

Discussion

You can use the Keyboard Layout Services functions KLGetKeyboardLayoutAtIndex, KLGetKeyboardLayoutWithIdentifier, KLGetKeyboardLayoutWithName,or KLGetCurrentKeyboardLayout to obtain a keyboard layout reference. If you want to obtain keyboard layout data, use the function KLGetKeyboardLayoutProperty.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

Keyboards.h

Constants

Keyboard Layout Constants

Keyboard Layout Identifier

Specifies a layout identifier for a keyboard.

typedef SInt32 KeyboardLayoutIdentifier;
enum {
   kKLUSKeyboard = 0
};

Constants

kKLUSKeyboard

Specifies a US keyboard layout. All systems support this keyboard layout.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

Discussion

You can supply this constant as the iIdentifier parameter to the function KLGetKeyboardLayoutWithIdentifier. This constant is the property value associated with the keyboard layout property tag kKLIdentifier.

Keyboard Layout Formats

Specify the layout format used for a keyboard.

typedef SInt32 KeyboardLayoutKind;
enum {
   kKLKCHRuchrKind = 0,
   kKLKCHRKind = 1,
   kKLuchrKind = 2
};

Constants

kKLKCHRuchrKind

Specifies that both 'KCHR' and 'uchr' formats are available.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLKCHRKind

Specifies that only the 'KCHR' format is available.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLuchrKind

Specifies that only the 'uchr' format is available.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

Discussion

These values are associated with the keyboard layout property tag kKLKind.

Keyboard Layout Property Tag

Specify the property tag for a keyboard layout.

typedef UInt32 KeyboardLayoutPropertyTag;
enum {
   kKLKCHRData = 0,
   kKLuchrData = 1,
   kKLIdentifier = 2,
   kKLIcon = 3,
   kKLLocalizedName = 4,
   kKLName = 5,
   kKLGroupIdentifier = 6,
   kKLKind = 7
};

Constants

kKLKCHRData

Specifies 'KCHR' layout format. The data associated with this tag is a pointer (const void *) to keyboard layout data formatted as 'KCHR' data. You can use 'KCHR' data with the Event Manager function KeyTranslate.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLuchrData

Specifies 'uchr' layout format. The data associated with this tag is a pointer (const void *) to keyboard layout data formatted as 'uchr' data. You can use 'uchr' data with the Unicode Utilities function UCKeyTranslate.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLIdentifier

Specifies a keyboard layout identifier. The data associated with this tag a “Keyboard Layout Identifier” constant.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLIcon

Specifies a keyboard layout icon. The data associated with this tag is an icon reference (IconRef) that specifies the icon that appears in the Keyboard menu.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLLocalizedName

Specifies the localized keyboard layout name. The data associated with this tag is a CFStringRef that specifies the localized name for the keyboard layout.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLName

Specifies the keyboard layout name. The data associated with this tag is a CFStringRef that specifies the name for the keyboard layout.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLGroupIdentifier

Specifies the keyboard layout group identifier. The data associated with this tag is an SInt32 value that specifies the grouping of a keyboard layout in the Keyboard menu.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

kKLKind

Specifies the keyboard layout format. The data associated with this tag is a “Keyboard Layout Formats” constant.

Available in Mac OS X v10.2 and later.

Declared in Keyboards.h

Discussion

You can supply any of these constants as the iPropertyTag parameter to the function KLGetKeyboardLayoutProperty to retrieve the data associated with the property tag.

Physical Keyboard Layout Types

Specify the layout type associated with a physical keyboard.

typedef UInt32 PhysicalKeyboardLayoutType;
enum {
   kKeyboardJIS = 'JIS ',
   kKeyboardANSI = 'ANSI',
   kKeyboardISO = 'ISO ',
   kKeyboardUnknown = kUnknownType
};

Constants

kKeyboardJIS

Specifies a JIS keyboard.

Available in Mac OS X v10.0 and later.

Declared in Keyboards.h

kKeyboardANSI

Specifies an ANSI keyboard layout.

Available in Mac OS X v10.0 and later.

Declared in Keyboards.h

kKeyboardISO

Specifies an ISO keyboard layout.

Available in Mac OS X v10.0 and later.

Declared in Keyboards.h

kKeyboardUnknown

Specifies the keyboard layout type is unknown.

Available in Mac OS X v10.0 and later.

Declared in Keyboards.h

Discussion

These constants are returned by the function KBGetLayoutType.

Unsupported Constants

Trap Value

Specifies a trap value for Keyboard Layout Services.

enum {
   _KeyboardDispatch = 0xAA7A
};

Discussion

This constant is not needed in Mac OS X.

PS2 Error Codes

Specify an error returned by unsupported PS2 keyboard functions.

enum {
   errKBPS2KeyboardNotAvailable = -30850,
   errKBIlligalParameters = -30851,
   errKBFailSettingID = -30852,
   errKBFailTranslationTable = -30853
   errKBFailWritePreference = -30854
};

Discussion

These constants are returned as error codes by the unsupported PS2 keyboard functions. They are not relevant to the functions whose prefix is ‘KL’.

---